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.
48 endpoints across 14 categories. Click any row to jump to its full reference page (parameters, request/response shapes, Try-It playground). Sections and rows follow the same order as the API Reference sidebar.
Legend. Bearer = requires Authorization: Bearer <access_token> on top of client_id. CDN = served from data.simkl.in; no auth.
Trending
Trending overview → · Pre-built JSON, no auth. Mirrors Simkl’s Most Watched pages.
| Method | Endpoint | Description |
|---|
GET | /discover/trending/{file}.json | CDN. Combined trending: movies + TV + anime in one response. |
GET | /discover/trending/{type}/{file}.json | CDN. Per-category trending: movies, TV, or anime separately. |
GET | /discover/dvd/{file}.json | CDN. Latest popular DVD / Blu-ray releases (movies). |
Calendar
Calendar overview → · CDN-hosted upcoming-episode and movie-release schedules.
| Method | Endpoint | Description |
|---|
GET | /calendar/{type}.json | CDN. Rolling 33-day calendar — TV, anime, or movie releases. |
GET | /calendar/{year}/{month}/{type}.json | CDN. Monthly archive — same shape, specific month. |
Redirect
Redirect overview →
| Method | Endpoint | Description |
|---|
GET | /redirect | Resolve a Simkl-canonical URL from a TMDB / IMDB / trailer / Twitter handle. |
Auth
Auth overview → · Browser and PIN flows for getting an access_token. See the Authentication guide for which flow fits your platform.
| Method | Endpoint | Description |
|---|
GET | /oauth/authorize | Send the user to Simkl’s consent screen. Browser flow (web / mobile / desktop). |
POST | /oauth/token | Exchange the authorization code (or PKCE verifier) for an access_token. |
GET | /oauth/pin | Request a short PIN code for TVs / consoles / CLIs that can’t open a browser. |
GET | /oauth/pin/{user_code} | Poll until the user enters the PIN at simkl.com/pin. |
Scrobble
Scrobble overview → · Real-time playback tracking. All four require Bearer. See the Scrobble guide for the lifecycle.
| Method | Endpoint | Description |
|---|
POST | /scrobble/checkin | Bearer. Fire-and-forget — Simkl auto-completes when runtime elapses. |
POST | /scrobble/pause | Bearer. Save current progress as a resumable playback. |
POST | /scrobble/start | Bearer. Begin / resume a playback session; shows “Watching now”. |
POST | /scrobble/stop | Bearer. End a session — ≥80% marks watched, below saves as playback. |
Playback
Playback overview → · Cross-device resume points saved by /scrobble/pause and /scrobble/stop.
| Method | Endpoint | Description |
|---|
GET | /sync/playback/{type} | Bearer. List saved paused playbacks for cross-device resume. |
DELETE | /sync/playback/{id} | Bearer. Remove a saved playback. |
Sync
Sync overview → · Read and write watch history, watchlists, and ratings. All require Bearer. See the Sync guide for the activities-driven refresh strategy.
| Method | Endpoint | Description |
|---|
GET | /sync/activities | Bearer. Last-modified timestamps per category — the “is anything new?” gate before re-syncing. |
POST | /sync/add-to-list | Bearer. Move titles between watchlist statuses (watching, plantowatch, completed, hold, dropped). |
GET | /sync/all-items/{type}/{status} | Bearer. Read a user’s library, filtered by type and status. Pair with date_from for deltas. |
POST | /sync/history | Bearer. Mark items watched. Top-level movies / shows / episodes arrays. |
POST | /sync/history/remove | Bearer. Un-mark items watched. |
POST | /sync/ratings | Bearer. Rate items 1–10. |
POST | /sync/ratings/remove | Bearer. Clear user-set ratings. |
GET | /sync/ratings/{type}/{rating} | Bearer. List items the user has rated, optionally filtered by rating value. |
POST | /sync/watched | Bearer. Bulk “have I watched these?” lookup, by IDs or per-episode. |
Search
Search overview → · Find titles by file name, external ID, free-text query, or “surprise me”. Public — client_id is the only requirement.
| Method | Endpoint | Description |
|---|
POST | /search/file | Identify a single video file the user just opened (desktop scrobblers, player overlays). Not for library scraping — use the media server’s own metadata for that. |
GET | /search/id | Legacy external-ID lookup. Use /redirect instead — header-only, Cloudflare-cached, and the canonical resolver. |
POST | /search/random | Random pick with filters (genre, year, country, service). Optional bearer skips already-watched titles. |
GET | /search/{type} | Free-text search across movies, TV, or anime. Paginated. |
| Method | Endpoint | Description |
|---|
GET | /tv/airing | What’s airing today / tomorrow / on a specific date. |
GET | /tv/best/{filter} | Top-rated / most-watched / most-voted TV shows. |
GET | /tv/episodes/{id} | Full episode list for a show, including specials. |
GET | /tv/genres/... | TV by genre × type × country × network × year × sort. Paginated. |
GET | /tv/premieres/{param} | New premieres (new) or upcoming ones (soon). |
GET | /tv/{id} | Single show record — overview, network, runtime, status, genres, episode count, ratings, trailers, external IDs. Full record is returned by default. |
Anime
Anime overview →
| Method | Endpoint | Description |
|---|
GET | /anime/airing | Today / tomorrow / specific-date anime airings. |
GET | /anime/best/{filter} | Top-rated / most-watched / most-voted anime. |
GET | /anime/episodes/{id} | Episode list with AniDB / TVDB cross-references. |
GET | /anime/genres/... | Anime by genre × type × network × year × sort. Paginated. |
GET | /anime/premieres/{param} | Recent or upcoming anime premieres. |
GET | /anime/{id} | Single anime record. extended=full_anime_seasons adds mapped TVDB seasons. |
Movies
Movies overview →
| Method | Endpoint | Description |
|---|
GET | /movies/genres/... | Movies by genre × type × country × year × sort. Paginated. |
GET | /movies/{id} | Single movie record — overview, director, runtime, country, genres, ratings, release dates, budget, revenue, trailers, external IDs, similar movies. Full record is returned by default. |
Ratings
Ratings overview → · Per-title ratings live inside the detail endpoints (/movies/{id} · /tv/{id} · /anime/{id}) under their ratings field. Use GET /redirect first if you only have an external ID. The bulk-watchlist endpoint below covers the “ratings for everything in a user’s library” case.
| Method | Endpoint | Description |
|---|
GET | /ratings/{type} | Bearer. Simkl community rating + droprate for every item in the user’s watchlist (?user_watchlist=watching,plantowatch,... selects which bucket). |
Users
Users overview →
| Method | Endpoint | Description |
|---|
GET | /users/recently-watched-background/{user_id} | Auto-generated cover image (PNG) from a user’s recently-watched titles. No auth. |
POST | /users/settings | Bearer. The authenticated user’s profile + privacy settings. |
POST | /users/{user_id}/stats | Bearer. Aggregated watch-stats for a Simkl user. |
Changes
| Method | Endpoint | Description |
|---|
GET | /changes | Modification feed for the public catalog — titles updated since a given date. |
Looking for something specific? Hit Ctrl+K (or ⌘+K) to search across every endpoint, guide, and convention.
