API Reference
Trending
Calendar
Redirect
Sync
Changes
Top-rated TV shows
Top-rated TV shows. Mirrors the Simkl Best TV pages. No access_token required.
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/....
type=documentary can return null. When the type filter doesn’t match anything in the top set, the response body is bare null rather than an empty array. Handle both shapes in your parser.
Errors
| Status | When |
|---|---|
412 | Missing or invalid client_id |
500 | Server error |
Unknown filter or type values silently fall back — no 400. The endpoint never returns 404.
Documentation Index
Fetch the complete documentation index at: https://api.simkl.org/llms.txt
Use this file to discover all available pages before exploring further.
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
Descriptive identifier for your app, ideally name/version. Examples: PlexMediaServer/1.43.1.10540, kodi-simkl/0.9.2, MyApp/2.4.1 (https://myapp.com).
Path Parameters
Which top-rated bucket to return. Unknown values fall back to all.
month, all, year, voted, watched Query Parameters
Optional. Narrow by show type. Unknown values are ignored. Watch out: type=documentary can return a bare null body when no documentaries are in the top 60.
series, documentary, entertainment, animation Your client_id from your Simkl developer settings. Required on every request.
Short, lowercase identifier for your app (e.g. plex-scrobbler, kodi-bridge). Helps Simkl identify which apps are using the API.
Your app's current version (e.g. 1.0, 2.4.1). Helps Simkl debug issues you report.
Response
OK — array of items, or bare null when a ?type= filter zeroes the result set.
Display title.
Premiere year.
simkl.com URL relative to the root, with the slug appended.
"/tv/11121/breaking-bad"
Aggregate ratings. Always carries simkl. TV items carry imdb; anime items carry mal (the other key isn't present at all).
Hide child attributes
Hide child attributes
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://simkl.in/posters/{poster}_m.webp).
Total IMDB / MAL vote count (whichever applies). Only present when you call with filter=voted — absent from items on other filters.
Number of Simkl users who watched this title this month. Only present when you call with filter=watched — absent from items on other filters.
Was this page helpful?