All endpoints

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 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.

TV

TV overview →

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.

Get started

Authentication

Conventions

Guides

API Debug

Resources

Calendar

Redirect

Auth

Scrobble

Playback

Sync

Search

TV

Anime

Movies

Ratings

Users

Changes

​Trending

​Calendar

​Redirect

​Auth

​Scrobble

​Playback

​Sync

​Search

​TV

​Anime

​Movies

​Ratings

​Users

​Changes

Trending

Calendar

Redirect

Auth

Scrobble

Playback

Sync

Search

TV

Anime

Movies

Ratings

Users

Changes