> ## 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.
# All endpoints
> Every endpoint Simkl exposes, grouped by category. Use this page as a skim/grep index — each row links to the full reference.
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 ` on top of `client_id`. **CDN** = served from `data.simkl.in`; no auth.
## Trending
[**Trending overview →**](/api-reference/trending) · Pre-built JSON, no auth. Mirrors Simkl's [Most Watched](https://simkl.com/movies/best-movies/most-watched/) pages.
| Method | Endpoint | Description |
| ------ | ------------------------------------------------------------------ | ---------------------------------------------------------------- |
| `GET` | [`/discover/trending/{file}.json`](/api-reference/trending) | **CDN.** Combined trending: movies + TV + anime in one response. |
| `GET` | [`/discover/trending/{type}/{file}.json`](/api-reference/trending) | **CDN.** Per-category trending: movies, TV, or anime separately. |
| `GET` | [`/discover/dvd/{file}.json`](/api-reference/trending) | **CDN.** Latest popular DVD / Blu-ray releases (movies). |
## Calendar
[**Calendar overview →**](/api-reference/calendar) · CDN-hosted upcoming-episode and movie-release schedules.
| Method | Endpoint | Description |
| ------ | ----------------------------------------------------------------- | ---------------------------------------------------------------- |
| `GET` | [`/calendar/{type}.json`](/api-reference/calendar) | **CDN.** Rolling 33-day calendar — TV, anime, or movie releases. |
| `GET` | [`/calendar/{year}/{month}/{type}.json`](/api-reference/calendar) | **CDN.** Monthly archive — same shape, specific month. |
## Redirect
[**Redirect overview →**](/api-reference/redirect)
| Method | Endpoint | Description |
| ------ | -------------------------------------------- | ---------------------------------------------------------------------------- |
| `GET` | [`/redirect`](/api-reference/simkl/redirect) | Resolve a Simkl-canonical URL from a TMDB / IMDB / trailer / Twitter handle. |
## Auth
[**Auth overview →**](/api-reference/auth) · Browser and PIN flows for getting an `access_token`. See the [Authentication](/authentication) guide for which flow fits your platform.
| Method | Endpoint | Description |
| ------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `GET` | [`/oauth/authorize`](/api-reference/simkl/authorize) | Send the user to Simkl's consent screen. Browser flow (web / mobile / desktop). |
| `POST` | [`/oauth/token`](/api-reference/simkl/exchange-token) | Exchange the authorization `code` (or PKCE verifier) for an `access_token`. |
| `GET` | [`/oauth/pin`](/api-reference/simkl/get-pin) | Request a short PIN code for TVs / consoles / CLIs that can't open a browser. |
| `GET` | [`/oauth/pin/{user_code}`](/api-reference/simkl/check-pin) | Poll until the user enters the PIN at `simkl.com/pin`. |
## Scrobble
[**Scrobble overview →**](/api-reference/scrobble) · Real-time playback tracking. All four require **Bearer**. See the [Scrobble guide](/guides/scrobble) for the lifecycle.
| Method | Endpoint | Description |
| ------ | ------------------------------------------------------------ | ------------------------------------------------------------------------ |
| `POST` | [`/scrobble/checkin`](/api-reference/simkl/scrobble-checkin) | **Bearer.** Fire-and-forget — Simkl auto-completes when runtime elapses. |
| `POST` | [`/scrobble/pause`](/api-reference/simkl/scrobble-pause) | **Bearer.** Save current progress as a resumable playback. |
| `POST` | [`/scrobble/start`](/api-reference/simkl/scrobble-start) | **Bearer.** Begin / resume a playback session; shows "Watching now". |
| `POST` | [`/scrobble/stop`](/api-reference/simkl/scrobble-stop) | **Bearer.** End a session — ≥80% marks watched, below saves as playback. |
## Playback
[**Playback overview →**](/api-reference/playback) · Cross-device resume points saved by `/scrobble/pause` and `/scrobble/stop`.
| Method | Endpoint | Description |
| -------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `GET` | [`/sync/playback/{type}`](/api-reference/simkl/get-playback-sessions) | **Bearer.** List saved paused playbacks for cross-device resume. |
| `DELETE` | [`/sync/playback/{id}`](/api-reference/simkl/delete-playback) | **Bearer.** Remove a saved playback. |
## Sync
[**Sync overview →**](/api-reference/sync) · Read and write watch history, watchlists, and ratings. All require **Bearer**. See the [Sync guide](/guides/sync) for the activities-driven refresh strategy.
| Method | Endpoint | Description |
| ------ | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `GET` | [`/sync/activities`](/api-reference/simkl/get-activities) | **Bearer.** Last-modified timestamps per category — the "is anything new?" gate before re-syncing. |
| `POST` | [`/sync/add-to-list`](/api-reference/simkl/add-to-list) | **Bearer.** Move titles between watchlist statuses (watching, plantowatch, completed, hold, dropped). |
| `GET` | [`/sync/all-items/{type}/{status}`](/api-reference/simkl/get-all-items) | **Bearer.** Read a user's library, filtered by type and status. Pair with `date_from` for deltas. |
| `POST` | [`/sync/history`](/api-reference/simkl/add-to-history) | **Bearer.** Mark items watched. Top-level `movies` / `shows` / `episodes` arrays. |
| `POST` | [`/sync/history/remove`](/api-reference/simkl/remove-from-history) | **Bearer.** Un-mark items watched. |
| `POST` | [`/sync/ratings`](/api-reference/simkl/add-ratings) | **Bearer.** Rate items 1–10. |
| `POST` | [`/sync/ratings/remove`](/api-reference/simkl/remove-ratings) | **Bearer.** Clear user-set ratings. |
| `GET` | [`/sync/ratings/{type}/{rating}`](/api-reference/simkl/get-user-ratings) | **Bearer.** List items the user has rated, optionally filtered by rating value. |
| `POST` | [`/sync/watched`](/api-reference/simkl/get-watched) | **Bearer.** Bulk "have I watched these?" lookup, by IDs or per-episode. |
## Search
[**Search overview →**](/api-reference/search) · 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`](/api-reference/simkl/search-by-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`](/api-reference/simkl/search-by-id) | Legacy external-ID lookup. **Use [`/redirect`](/api-reference/redirect) instead** — header-only, Cloudflare-cached, and the canonical resolver. |
| `POST` | [`/search/random`](/api-reference/simkl/search-random) | Random pick with filters (genre, year, country, service). Optional bearer skips already-watched titles. |
| `GET` | [`/search/{type}`](/api-reference/simkl/search-by-text) | Free-text search across movies, TV, or anime. Paginated. |
## TV
[**TV overview →**](/api-reference/tv)
| Method | Endpoint | Description |
| ------ | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET` | [`/tv/airing`](/api-reference/simkl/get-tv-airing) | What's airing today / tomorrow / on a specific date. |
| `GET` | [`/tv/best/{filter}`](/api-reference/simkl/get-best-tv) | Top-rated / most-watched / most-voted TV shows. |
| `GET` | [`/tv/episodes/{id}`](/api-reference/simkl/get-tv-episodes) | Full episode list for a show, including specials. |
| `GET` | [`/tv/genres/...`](/api-reference/simkl/get-tv-genres) | TV by genre × type × country × network × year × sort. Paginated. |
| `GET` | [`/tv/premieres/{param}`](/api-reference/simkl/get-tv-premieres) | New premieres (`new`) or upcoming ones (`soon`). |
| `GET` | [`/tv/{id}`](/api-reference/simkl/get-tv-show) | Single show record — overview, network, runtime, status, genres, episode count, ratings, trailers, external IDs. Full record is returned by default. |
## Anime
[**Anime overview →**](/api-reference/anime)
| Method | Endpoint | Description |
| ------ | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `GET` | [`/anime/airing`](/api-reference/simkl/get-anime-airing) | Today / tomorrow / specific-date anime airings. |
| `GET` | [`/anime/best/{filter}`](/api-reference/simkl/get-best-anime) | Top-rated / most-watched / most-voted anime. |
| `GET` | [`/anime/episodes/{id}`](/api-reference/simkl/get-anime-episodes) | Episode list with AniDB / TVDB cross-references. |
| `GET` | [`/anime/genres/...`](/api-reference/simkl/get-anime-genres) | Anime by genre × type × network × year × sort. Paginated. |
| `GET` | [`/anime/premieres/{param}`](/api-reference/simkl/get-anime-premieres) | Recent or upcoming anime premieres. |
| `GET` | [`/anime/{id}`](/api-reference/simkl/get-anime) | Single anime record. `extended=full_anime_seasons` adds mapped TVDB seasons. |
## Movies
[**Movies overview →**](/api-reference/movies)
| Method | Endpoint | Description |
| ------ | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET` | [`/movies/genres/...`](/api-reference/simkl/get-movies-genres) | Movies by genre × type × country × year × sort. Paginated. |
| `GET` | [`/movies/{id}`](/api-reference/simkl/get-movie) | 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 →**](/api-reference/ratings) · **Per-title ratings live inside the [detail endpoints](/api-reference/simkl/get-movie) (`/movies/{id}` · `/tv/{id}` · `/anime/{id}`)** under their `ratings` field. Use [`GET /redirect`](/api-reference/simkl/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}`](/api-reference/simkl/get-watchlist-ratings) | **Bearer.** Simkl community rating + droprate for every item in the user's watchlist (`?user_watchlist=watching,plantowatch,...` selects which bucket). |
## Users
[**Users overview →**](/api-reference/users)
| Method | Endpoint | Description |
| ------ | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `GET` | [`/users/recently-watched-background/{user_id}`](/api-reference/simkl/get-recently-watched-image) | Auto-generated cover image (PNG) from a user's recently-watched titles. No auth. |
| `POST` | [`/users/settings`](/api-reference/simkl/get-user-settings) | **Bearer.** The authenticated user's profile + privacy settings. |
| `POST` | [`/users/{user_id}/stats`](/api-reference/simkl/get-user-stats) | **Bearer.** Aggregated watch-stats for a Simkl user. |
## Changes
| Method | Endpoint | Description |
| ------ | ---------------------------------------------- | ----------------------------------------------------------------------------- |
| `GET` | [`/changes`](/api-reference/simkl/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.