Top-rated TV shows
Top-rated TV shows. Mirrors the Simkl Best TV pages. No access_token needed on AUTH V1. AUTH V2 apps must send the user’s token — an anonymous call returns 401 user_token_required. See AUTH V2 overview.
Pick a bucket via the {filter} path segment:
| Filter | What you get |
|---|---|
all | All-time top-rated. |
year | Top-rated for the current year. |
month | Top-rated for the current month. |
voted | Most-voted titles (sorted by total IMDB votes). Items also include a votes count. |
watched | Most-watched this month. Items also include a watched count. |
Unknown filter values fall back to all.
Optionally narrow by type=series, documentary, entertainment, or animation. Unknown values are ignored.
60 items, no pagination. The endpoint always returns up to 60 items in one call. The page and limit query parameters are accepted but ignored. For paginated browsing use GET /tv/genres/....
Errors
| Status | When |
|---|---|
401 user_token_required | AUTH V2 app called without the user’s token |
412 | Missing or invalid client_id |
500 | Server error |
Unknown filter or type values silently fall back — no 400. The endpoint never returns 404.
Authorizations
Preferred form: your client_id as a URL query parameter on every request. Self-describing in logs and curl commands. See Headers and required parameters.
Headers
Path Parameters
Response
OK — array of items, or bare null when a ?type= filter zeroes the result set.
Type 4 null — no poster on file. See Null and missing values. When present, it's an image path fragment — build the full URL using the patterns in Image conventions (e.g. https://wsrv.nl/?url=https://simkl.in/posters/{poster}_m.webp&q=90).