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 V2

AUTH V2 overview → · Standards-compliant OAuth 2.0, and the right choice for anything new. See Set up authentication for the client type, secret, flow and scope decisions.

Method	Endpoint	Description
Browser	`/oauth2/authorize`	Not an API call — a URL you open in the user’s browser, on `simkl.com`. PKCE (`S256`) is mandatory.
`POST`	`/oauth2/token`	All three grants — authorization code, refresh, and device code.
`POST`	`/oauth2/device`	Start the device flow for TVs, consoles and CLIs. Returns an 8-character code.
`POST`	`/oauth2/revoke`	Invalidate a token when a user disconnects.

AUTH V1

AUTH V1 overview → · The original flows. Being retired around April 2027 — see Migrating from V1 to V2.

Method	Endpoint	Description
Browser	`/oauth/authorize`	Not an API call — a URL you open in the user’s browser, on `simkl.com`.
`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`.

Custom Lists

Custom lists overview → · Read-only and in beta. Requires a Simkl PRO or VIP access token — free and anonymous callers get a 200 carrying premium_only, not an error.

Method	Endpoint	Description
`GET`	`/lists/{id}`	One custom list’s metadata and its items.
`GET`	`/lists/user/{userId}`	Every custom list belonging to one user, paginated.

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.
`GET`	`/users/settings`	Bearer. The authenticated user’s profile + privacy settings.
`GET`	`/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 V2

AUTH V1

Custom Lists

Scrobble

Playback

Sync

Search

TV

Anime

Movies

Ratings

Users

Changes

​Trending

​Calendar

​Redirect

​AUTH V2

​AUTH V1

​Custom Lists

​Scrobble

​Playback

​Sync

​Search

​TV

​Anime

​Movies

​Ratings

​Users

​Changes

Trending

Calendar

Redirect

AUTH V2

AUTH V1

Custom Lists

Scrobble

Playback

Sync

Search

TV

Anime

Movies

Ratings

Users

Changes