# Simkl API > Build apps that track Movies, TV Shows, and Anime — scrobble playback, sync watch history, and pull rich metadata from the Simkl API. ## Docs - [All endpoints](https://api.simkl.org/all-endpoints.md): Every endpoint Simkl exposes, grouped by category. Use this page as a skim/grep index — each row links to the full reference. - [About Anime](https://api.simkl.org/api-reference/anime.md): Look up anime, browse what's airing or premiering, and pull episode lists. - [Choose a flow](https://api.simkl.org/api-reference/auth.md): OAuth or PIN — pick the one that matches your platform and ship in under an hour. - [Calendar data files](https://api.simkl.org/api-reference/calendar.md): CDN-hosted JSON for upcoming episodes, premieres, and movie releases. - [Introduction](https://api.simkl.org/api-reference/introduction.md): Everything you need to know before you make your first call to the Simkl API. - [About Movies](https://api.simkl.org/api-reference/movies.md): Browse and look up movies — discover by genre/country/year, or pull full details for a single title. - [OAuth flow](https://api.simkl.org/api-reference/oauth.md): Authorize a user, get a code, exchange it for an access token. - [OAuth client libraries](https://api.simkl.org/api-reference/oauth-libraries.md): Every popular OAuth library mints real Simkl tokens with default config. Copy-paste working code per language. - [OAuth 2.0 + PKCE for public clients](https://api.simkl.org/api-reference/oauth-pkce.md): OAuth 2.0 without `client_secret` for mobile apps, single-page apps, browser extensions, desktop binaries, and any other public client. Uses `code_verifier` + `code_challenge` to prove the redeeming client is the same one that initiated the flow. - [PIN flow](https://api.simkl.org/api-reference/pin.md): Device-friendly auth flow for TVs, consoles, CLIs, and other limited-input devices. - [How playbacks work](https://api.simkl.org/api-reference/playback.md): Saved pause points across devices. When users pause or stop watching before 80%, Simkl saves their position so any signed-in device can resume. - [About Ratings](https://api.simkl.org/api-reference/ratings.md): Where to read Simkl's community ratings, IMDb / MAL scores, drop rates, and rank — for any title in the catalog or just the items in a user's watchlist. - [Redirect & deep-linking](https://api.simkl.org/api-reference/redirect.md): Two jobs: link from anywhere into the right Simkl page (no API call), or resolve any external ID to a Simkl ID at the lowest possible cost. - [How scrobbling works](https://api.simkl.org/api-reference/scrobble.md): Report real-time playback — start, pause, stop, checkin — so Simkl tracks 'Watching now' and auto-marks items watched. - [About Search](https://api.simkl.org/api-reference/search.md): Look up items by ID, by title, by file name, or pull a random item. - [Add Ratings](https://api.simkl.org/api-reference/simkl/add-ratings.md): Apply user ratings (1-10) to movies, shows, or anime. Same auth model and batching rules as the rest of the [Sync API](/guides/sync). To **read** ratings back, use [`GET /sync/ratings/:type/:rating`](/api-reference/simkl/get-user-ratings) — see [Read side](#read-side) below. - [Add to History](https://api.simkl.org/api-reference/simkl/add-to-history.md): Record watch events. The unit is the **watch event** — adding "I watched The Walking Dead S01E01 at 8pm" — not list membership (use [`POST /sync/add-to-list`](/api-reference/simkl/add-to-list) for that, or set `status` per-item here to do both at once). - [Add to Watchlist](https://api.simkl.org/api-reference/simkl/add-to-list.md): Move an item into one of the user's **Watchlist** statuses. The body's per-item `to` field selects the destination: - [Authorize a user](https://api.simkl.org/api-reference/simkl/authorize.md): Step 1 of the OAuth 2.0 authorization-code flow. Redirect the user's browser to this URL on **simkl.com** (not api.simkl.com). Simkl shows a consent screen and, once the user approves, redirects to your `redirect_uri` with `?code=…`. - [Poll PIN code for the access token](https://api.simkl.org/api-reference/simkl/check-pin.md): Step 3 of the **PIN flow**. Poll this endpoint every `interval` seconds (returned in step 1, currently `5`) to learn whether the user has entered the code. **Stop polling when `expires_in` (currently `900` seconds) elapses** and prompt the user to restart. - [Delete Playback](https://api.simkl.org/api-reference/simkl/delete-playback.md): Removes a saved playback session by its `id`. **HTTP method is `DELETE`** — using `POST` or `GET` against this URL will not delete and will instead hit the list handler. Get the IDs from [`GET /sync/playback/{type}`](/api-reference/simkl/get-playback-sessions). - [Exchange an authorization code for an access token](https://api.simkl.org/api-reference/simkl/exchange-token.md): Step 2 of OAuth 2.0. POST your authorization `code` here to receive an `access_token`. The success response carries `{access_token, token_type: "bearer", scope: "public", expires_in: 157680000}` — about 5 years. Save the token securely. **No refresh token is issued**; if a 401 arrives before that li… - [Get Last Activities](https://api.simkl.org/api-reference/simkl/get-activities.md): Returns the most recent update timestamps for each of the user's lists. **Always call this first** when syncing — compare against your last-saved timestamps and pull only the lists that have moved. This is the cheapest call in the API. - [Get all items of one type in one status bucket](https://api.simkl.org/api-reference/simkl/get-all-items.md): > ## ⚠️ For continuous sync, do NOT call `/sync/all-items` on a timer > > The correct loop, every time you want to check for changes: > > 1. **Call [`GET /sync/activities`](/api-reference/simkl/get-activities) first.** It returns a tiny JSON of `last-modified` timestamps per category — costs almost… - [Anime details](https://api.simkl.org/api-reference/simkl/get-anime.md): Full detail record for one anime — title, overview, year, runtime, network, status, genres, studios (list of `{id, name}`), related titles, ratings, posters, fanart, external IDs, alternate titles, trailers, episode count, AniDB-mapped TVDB seasons, user recommendations. The default response is alre… - [Anime airing today, tomorrow, or on a specific date](https://api.simkl.org/api-reference/simkl/get-anime-airing.md): Currently airing anime — same data that powers the [Simkl anime calendar](https://simkl.com/anime/airing/). No `access_token` required. - [List episodes for an anime](https://api.simkl.org/api-reference/simkl/get-anime-episodes.md): Returns the full episode list for a Simkl anime ID, including specials. For anime, season is omitted in regular episodes (anime is treated as a single canonical season per AniDB); specials use `type: "special"` and lack a `season`/`episode` pair. - [Anime by genre](https://api.simkl.org/api-reference/simkl/get-anime-genres.md): **Not for TV / console / 10-foot apps.** The V1 genre-browse endpoints return a thin per-item shape (`title`, `year`, `poster`, `ids`, `ratings`, `rank`). Building a TV-app grid that shows overview text, full ratings, networks, runtimes, recommendations, or trailers would force one per-ite… - [Anime premieres (new + upcoming)](https://api.simkl.org/api-reference/simkl/get-anime-premieres.md): Anime premieres — recently aired or upcoming new anime. Mirrors the [Simkl Anime Premieres](https://simkl.com/anime/premieres/) page. No `access_token` required. - [Top-rated anime](https://api.simkl.org/api-reference/simkl/get-best-anime.md): Top-rated anime. Mirrors the [Simkl Best Anime](https://simkl.com/anime/best-anime/) pages. No `access_token` required. - [Top-rated TV shows](https://api.simkl.org/api-reference/simkl/get-best-tv.md): Top-rated TV shows. Mirrors the [Simkl Best TV](https://simkl.com/tv/best-shows/) pages. No `access_token` required. - [Recently changed catalog items](https://api.simkl.org/api-reference/simkl/get-changes.md): Returns Simkl catalog IDs whose metadata changed in the last **N** days, grouped by type. Use it to keep the items already on a user's watchlist fresh — when a show airs a new episode, an upcoming title starts airing, or a movie's metadata is updated, the corresponding ID appears here. - [Movie details](https://api.simkl.org/api-reference/simkl/get-movie.md): Full detail record for one movie — title, overview, year, runtime, country, language, certification, genres, director, ratings, posters, fanart, external IDs, alternate titles, release-date list per region, budget, revenue, trailers, similar-movie recommendations. The default response is already com… - [Movies by genre](https://api.simkl.org/api-reference/simkl/get-movies-genres.md): **Not for TV / console / 10-foot apps.** The V1 genre-browse endpoints return a thin per-item shape (`title`, `year`, `poster`, `ids`, `ratings`, `rank`). Building a TV-app grid that shows overview text, full ratings, networks, runtimes, recommendations, or trailers would force one per-ite… - [Request a PIN code](https://api.simkl.org/api-reference/simkl/get-pin.md): Step 1 of the **PIN flow** (also called the device flow). Best for TVs, consoles, smart watches, CLI tools — anywhere typing a URL is hard. You don't need `client_secret` for this flow. - [Get paused playback sessions for one type](https://api.simkl.org/api-reference/simkl/get-playback-sessions.md): Returns the user's saved paused playbacks — created by `/scrobble/pause` or `/scrobble/stop` with progress < 80%. The `{type}` segment is optional: - [Redirect to a user's last-watched cover image](https://api.simkl.org/api-reference/simkl/get-recently-watched-image.md): Pulls metadata about the user's most recently watched item — useful for "Now Watching" widgets, dashboard backgrounds, and embedded user-cards. - [TV shows airing today, tomorrow, or on a specific date](https://api.simkl.org/api-reference/simkl/get-tv-airing.md): Currently airing TV shows — same data that powers the [Simkl TV calendar](https://simkl.com/tv/airing/). No `access_token` required. - [List episodes for a TV show](https://api.simkl.org/api-reference/simkl/get-tv-episodes.md): Returns the full episode list for a Simkl TV show ID. Items include `season`, `episode`, `title`, `description`, `aired` (boolean), `img`, `date` (timezone-shifted), and `ids.simkl_id`. Specials appear with `type: "special"` after the regular episodes. - [TV by genre](https://api.simkl.org/api-reference/simkl/get-tv-genres.md): **Not for TV / console / 10-foot apps.** The V1 genre-browse endpoints return a thin per-item shape (`title`, `year`, `poster`, `ids`, `ratings`, `rank`). Building a TV-app grid that shows overview text, full ratings, networks, runtimes, recommendations, or trailers would force one per-ite… - [TV premieres (new + upcoming)](https://api.simkl.org/api-reference/simkl/get-tv-premieres.md): TV premieres — recently aired or upcoming new shows. Mirrors the [Simkl TV Premieres](https://simkl.com/tv/premieres/) page. No `access_token` required. - [TV show details](https://api.simkl.org/api-reference/simkl/get-tv-show.md): Full detail record for one TV show — title, overview, year, runtime, country, certification, network, genres, status, first/last-aired dates, total episodes, airs schedule, ratings, posters, fanart, external IDs, trailers, user recommendations. The default response is already complete; no flags need… - [Get the user's rated items, filtered by type and rating](https://api.simkl.org/api-reference/simkl/get-user-ratings.md): Returns the items **the user has rated themselves** — filtered to one type (movies, shows, or anime) and one or more rating values. - [Get the authenticated user's settings](https://api.simkl.org/api-reference/simkl/get-user-settings.md): Returns the authenticated user's profile (name, avatar, bio, location, age) and account settings (timezone, plan type). `POST` for historical reasons — no body. - [Get a user's watch statistics](https://api.simkl.org/api-reference/simkl/get-user-stats.md): **The most expensive call in the Simkl API. Only fire it on an explicit user action.** - [Look up watched status for items](https://api.simkl.org/api-reference/simkl/get-watched.md): POST an array of items you already know about; Simkl returns a parallel array telling you, **per item**, whether it's in the user's library, its current status, last-watched timestamp, and (optionally) per-episode breakdown. - [Community ratings for items in the user's watchlist](https://api.simkl.org/api-reference/simkl/get-watchlist-ratings.md): **This endpoint returns Simkl's *community* ratings** (the public average + droprate + vote counts) for every item in the user's watchlist — not the user's own 1-10 scores. If you want **the user's own ratings**, every [`GET /sync/all-items`](/api-reference/simkl/get-all-items) response alrea… - [Resolve any ID and redirect to Simkl](https://api.simkl.org/api-reference/simkl/redirect.md): A passive helper endpoint that **`301`-redirects** to a Simkl page (or an action) given any combination of IDs or a title. - [Remove from History](https://api.simkl.org/api-reference/simkl/remove-from-history.md): Removes items from the user's watched history. **Body shape is identical to [`POST /sync/history`](/api-reference/simkl/add-to-history)** — the same `movies[]`, `shows[]`, and granularity rules apply. - [Remove Ratings](https://api.simkl.org/api-reference/simkl/remove-ratings.md): Clears the user's ratings on the listed items. **Body shape is identical to [`POST /sync/ratings`](/api-reference/simkl/add-ratings) minus the `rating` field** — the IDs alone are enough to identify which entries to un-rate. - [Check-in](https://api.simkl.org/api-reference/simkl/scrobble-checkin.md): A **fire-and-forget version of [`/scrobble/start`](/api-reference/simkl/scrobble-start)**. Same effect on the user's [dashboard](https://simkl.com/) — the title appears in the **"Watching now"** widget with an animated, runtime-extrapolated progress bar — but you don't need to follow up with `pause`… - [Pause](https://api.simkl.org/api-reference/simkl/scrobble-pause.md): Saves the current `progress` as a **resumable playback** that any signed-in device can fetch via [`GET /sync/playback/{type}`](/api-reference/simkl/get-playback-sessions) and resume with [`/scrobble/start`](/api-reference/simkl/scrobble-start). This is how Simkl powers cross-device "Continue Watchin… - [Start](https://api.simkl.org/api-reference/simkl/scrobble-start.md): Creates or replaces the user's active "watching now" session for the given item. Call this when playback begins, or to resume a previously paused session. - [Stop](https://api.simkl.org/api-reference/simkl/scrobble-stop.md): Finalizes the user's playback session. The `action` field in the response tells you what Simkl did: - [Find an item by file name](https://api.simkl.org/api-reference/simkl/search-by-file.md): Identify a single video file the user just opened. Pass one filename and Simkl returns the matched movie, or the show + the specific episode the filename names. Built for desktop scrobblers and player overlays that need to recognize what the user is currently watching — apps that don't already have… - [Find items by external ID](https://api.simkl.org/api-reference/simkl/search-by-id.md): > ## ⚠️ Prefer [`GET /redirect`](/api-reference/redirect) + a cached detail endpoint over `/search/id` for almost every external-ID lookup > > The recommended two-step flow is materially cheaper, faster, and edge-cached: > > **Step 1 — Resolve the external ID to a Simkl ID.** Call [`GET /redirect?to… - [Search by text query](https://api.simkl.org/api-reference/simkl/search-by-text.md): Full-text search over the Simkl catalog. Pick a type (`movie`, `tv`, or `anime`) and pass a search term like `john wick` or `john wick 2014`. - [Random pick](https://api.simkl.org/api-reference/simkl/search-random.md): Returns a random title — perfect for "What should I watch?" features, daily-pick widgets, or seeding recommendation flows. Optionally filter by type, genre, year range, rating, popularity rank, or streaming service availability. - [Sync](https://api.simkl.org/api-reference/sync.md): Read and write the user's watch history, watchlists, ratings, and playbacks. - [Trending data files](https://api.simkl.org/api-reference/trending.md): Pre-built JSON for Simkl's Most Watched lists — Today, Week, Month — for Movies, TV, and Anime. No API key required. - [About TV](https://api.simkl.org/api-reference/tv.md): Look up TV shows, browse what's airing or premiering, and pull episode lists. - [About Users](https://api.simkl.org/api-reference/users.md): Read public user data, fetch recently-watched art, and update user settings. - [API rules](https://api.simkl.org/api-rules.md): Read this before you ship. The short list of what's required, what's free, and when you need a commercial license. - [Authentication](https://api.simkl.org/authentication.md): Three flows — OAuth 2.0 for server-side web apps, Public PKCE for mobile and SPAs, PIN for TVs and CLIs. Pick one and you're 5 minutes from your first authenticated call. - [Changelog](https://api.simkl.org/changelog.md): What's new across the Simkl API and these docs. - [CORS](https://api.simkl.org/conventions/cors.md): Cross-origin request support on api.simkl.com. - [Dates and timezones](https://api.simkl.org/conventions/dates.md): How Simkl returns dates and what to do in your app. - [Errors and status codes](https://api.simkl.org/conventions/errors.md): Every HTTP status code Simkl returns, what it means, and how to handle it. - [Extended info](https://api.simkl.org/conventions/extended-info.md): Which endpoints return rich data by default and which ones still take an `extended` query parameter. - [Headers and required parameters](https://api.simkl.org/conventions/headers.md): Required URL parameters and HTTP headers for every Simkl API request. - [Images](https://api.simkl.org/conventions/images.md): How to fetch poster, fanart, episode, and avatar images, with all available sizes — with live previews of each. - [Watchlist statuses](https://api.simkl.org/conventions/list-statuses.md): The watchlist statuses Simkl uses — and the per-type rules. Movies don't have watching or hold; TV and anime do. - [Null and missing values](https://api.simkl.org/conventions/null-values.md): Five different things a missing value can mean in the Simkl API, and how to handle each one. - [Pagination](https://api.simkl.org/conventions/pagination.md): How paginated endpoints work — request size, page numbers, and the response headers Simkl returns. - [Standard media objects](https://api.simkl.org/conventions/standard-media-objects.md): The shape of Movie, Show, Anime, and Episode objects every endpoint accepts and returns. - [API Analytics](https://api.simkl.org/debug/api-analytics.md): Live per-app request log — see exactly what your code sends to api.simkl.com, filter it, export it. - [Handling anime](https://api.simkl.org/guides/anime.md): Learn how to sync and interact with Simkl's anime catalog. Whether your app is TMDB-primary or Anime-native, this guide covers the mapping, payloads, and edge cases. - [Deep-linking to Simkl](https://api.simkl.org/guides/deep-linking.md): Link from your app, newsletter, or extension straight to the right Simkl page — even when you don't have a Simkl ID. Use external IDs (IMDb, TMDB, MAL, …) or title + year as the entry point. - [Mark as watched](https://api.simkl.org/guides/mark-as-watched.md): The fastest way to record that a user finished a movie, episode, or season — without scrobbling. - [Rewatches](https://api.simkl.org/guides/rewatches.md): Track separate viewing sessions for items the user already finished — mirror what simkl.com displays on a movie / show / anime detail page. - [Scrobbling playback](https://api.simkl.org/guides/scrobble.md): Report real-time playback to Simkl with start, pause, stop, and checkin. Auto-mark items watched at 80% (stop) or 100% (checkin). - [Search and discover](https://api.simkl.org/guides/search.md): Find movies, shows, and anime by ID, text query, file name, or randomly. - [Sync — watchlists, history, and ratings](https://api.simkl.org/guides/sync.md): Two-phase sync model: a one-time initial pull, then incremental deltas via /sync/activities + date_from. Keeps your app fast and Simkl's servers happy. - [Simkl API](https://api.simkl.org/index.md): Build apps that track Movies, TV Shows, and Anime — scrobble playback, sync watchlists in seconds (not minutes), and pull rich metadata. - [Quickstart](https://api.simkl.org/quickstart.md): From zero to writing user data in 5 minutes — see real data, get an access_token, read a watchlist, and mark a movie as watched. - [Full docs for LLMs](https://api.simkl.org/resources/llms-full.md) - [LLM index (llms.txt)](https://api.simkl.org/resources/llms-index.md) - [OpenAPI spec (JSON)](https://api.simkl.org/resources/openapi-spec.md) - [Rate limits](https://api.simkl.org/resources/rate-limits.md): How Simkl applies request limits and what to do when you hit one. - [Support](https://api.simkl.org/support.md): Where to ask questions, report bugs, request features, and check the status of the Simkl API. ## OpenAPI Specs - [openapi](https://api.simkl.org/openapi.json)