Skip to main content

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.

The TV API returns metadata about TV shows in Simkl’s catalog. None of these endpoints require an OAuth token — a client_id is enough. The status field on a show can be ended, tba, or airing.

​
Look up a show

Item-level lookups for when you already know which show you want. Both are Cloudflare-cached by Simkl ID — see Rate limits → Parallel requests.

Show details

GET /tv/{id} — full record (overview, network, runtime, country, certification, genres, status, first/last-aired dates, total episodes, airs schedule, ratings, posters, fanart, trailers, external IDs, user recommendations).

Episode list

GET /tv/episodes/{id} — every season + episode for a show, with aired flags and airdates.
If you only have an external ID (IMDb, TMDB, TVDB), resolve it to a Simkl ID via GET /redirect first — header-only, Cloudflare-cached, and the canonical resolver.

​
Browse & discover

Find shows by what’s on now, what’s coming, what’s top-rated, or by genre / country / network / year.

Airing

GET /tv/airing — what’s airing right now.

Premieres

GET /tv/premieres/{param} — upcoming season and series premieres.

Best of

GET /tv/best/{filter} — top-rated shows by filter (year, all-time, etc.).

Genres

GET /tv/genres/... — browse by genre, country, network, year.

​
Pre-built data files (no per-user cost)

Two static JSON resources on the CDN cover the most common “what’s hot / what’s airing” surfaces without paying any per-user request budget. Send the standard URL parameters and User-Agent; no Authorization token needed.

Trending TV

https://data.simkl.in/trending/tv_today.json + week / month variants, plus Top-100 and Top-500 versions. Refreshed daily. Drives “Most Watched” / “Trending Now” surfaces without polling.

TV airing calendar

https://data.simkl.in/calendar/tv.json + per-month archives at /calendar/{YEAR}/{MONTH}/tv.json. Updated every 6 hours. Far cheaper than polling /tv/airing.