> ## 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.
# Resolve any ID and redirect to Simkl
> A passive helper endpoint that **`301`-redirects** to a Simkl page (or an action) given any combination of IDs or a title.
It's designed for two situations:
1. **Linking to Simkl when you don't have the Simkl ID** — turn an IMDB / TMDB / TVDB / MAL / AniDB ID, or a title + year, into a clickable Simkl URL.
2. **Getting the Simkl ID with minimal info** — the cheapest way to translate an external ID into a Simkl ID. **Read the `Location` response header** and parse the `simkl_id` out of the URL path — no JSON to parse.
> ⚠️ **Do not follow the 301.** Read the `Location` header directly. Use `curl -I`, `requests.get(..., allow_redirects=False)`, `fetch(..., { redirect: 'manual' })`, or your client's equivalent. The destination is a public-facing page (simkl.com HTML, YouTube, Twitter intent, or `/oauth/authorize`) and contains no API data — following the redirect wastes bandwidth and can break (CORS, auth, destination-host rate limits). This applies to **HTTP clients, scripts, automated tools, AI agents, and LLM-driven workflows alike**.
>
> **What to do next, after reading the `Location` header:**
> - **If you only need the Simkl ID** — parse it out of the URL path (e.g. `https://simkl.com/tv/17465/...` → `17465`) and **stop**. Don't call anything else.
> - **If you also need the full record** (title, overview, poster, fanart, ratings, trailers, etc.) — pass the parsed Simkl ID to the matching Cloudflare-cached detail endpoint: [`GET /movies/{id}`](/api-reference/simkl/get-movie), [`GET /tv/{id}`](/api-reference/simkl/get-tv-show), [`GET /anime/{id}`](/api-reference/simkl/get-anime), [`GET /tv/episodes/{id}`](/api-reference/simkl/get-tv-episodes), or [`GET /anime/episodes/{id}`](/api-reference/simkl/get-anime-episodes). Popular titles come straight from edge cache.
>
> Full reference table of stop-at-301 invocations for popular HTTP clients in the [Redirect overview](/api-reference/redirect#use-case-2-resolve-an-external-id-to-a-simkl-id).
Like every Simkl endpoint, requests must include the [required URL parameters](/conventions/headers#required-url-parameters) (`client_id`, `app-name`, `app-version`) and a `User-Agent` header. No `Authorization` token is needed except for `to=watched`, which signs the user in if they aren't already.
#### `to=` action modes
| Mode | What the redirect points at |
|---|---|
| `simkl` *(default)* | The matching Simkl page (`https://simkl.com/movies/{id}/{slug}`, `tv/...`, `anime/...`). |
| `trailer` | The trailer URL (typically YouTube). |
| `twitter` | A `twitter.com/intent/tweet` URL with the title and a Simkl link prefilled. |
| `watched` | Marks the item watched on the user's account. If the user isn't signed in, Simkl redirects to `/oauth/authorize` first. |
#### Identifier parameters
Pass any combination — the more, the more accurate the match. Most can stand alone:
| Param | Notes |
|---|---|
| `simkl` | Simkl ID. |
| `imdb` | IMDB ID, or a full IMDB URL. |
| `tmdb` | TMDB ID. **Requires `type=movie` or `type=tv`** to disambiguate — TMDB has no anime type (anime shows are filed under `tv` on TMDB; Simkl routes them to its anime catalog automatically once resolved). |
| `tvdb` | TVDB ID. |
| `mal`, `anidb`, `anilist`, `kitsu`, `livechart`, `anisearch`, `animeplanet` | Anime-specific IDs. |
| `crunchyroll` | Crunchyroll show or episode ID/slug. |
| `netflix`, `hulu` | Streaming-service IDs (beta). |
| `title`, `year` | Title-based fallback. Pair with `type` for best results. |
| `season`, `episode` | Episode targeting (`season` defaults to `1`). Movies are ignored when either is set. |
| `ep_title` | Episode title used in the tweet text when `to=twitter`. |
| `type` | `movie`, `tv`, or `anime`. Required for `tmdb`; optional otherwise (`show` matches both `tv` and `anime`). |
#### Response
- Status: **`301 Moved Permanently`**
- `Location`: the resolved URL (Simkl page, YouTube, Twitter intent, or the OAuth authorize page when `to=watched` and the user isn't signed in).
- `Cache-Control: no-store` — never cache the redirect itself; cache the resolved URL on your side if you need to.
#### Why "lowest cost" for ID resolution
`GET /redirect?to=simkl&imdb=…` returns a `Location` header like `https://simkl.com/movies/472214/inception`. The number after `/movies/`, `/tv/`, or `/anime/` is the Simkl ID. Compared to `GET /search/id`:
- **No JSON parse** — read the `Location` header, regex out the ID.
- **Tiny payload** — HTTP headers only, no response body.
Use this for "I have an IMDB ID, give me the Simkl ID" lookups when you don't need the rest of the media object yet.
**Which IDs can I send/expect?** All accepted input identifiers and the keys you'll see echoed back in responses are listed at [**Standard media objects → Supported ID keys**](/conventions/standard-media-objects#supported-id-keys). Send every ID you have on writes — Simkl picks the first that resolves and ignores the rest. Reminder: `slug` is **response-only** (never send it on a request).
## OpenAPI
````yaml /openapi.json get /redirect
openapi: 3.1.0
info:
title: Simkl API
version: 1.0.0
description: >-
The **Simkl API** lets you build apps that track Movies, TV Shows, and Anime
— scrobble playback, sync watch history, and pull rich metadata.
All requests use HTTPS and return JSON. The base URL is
`https://api.simkl.com`.
**Every request needs three URL parameters and a `User-Agent` header:**
```
/endpoint?client_id=YOUR_CLIENT_ID&app-name=my-app&app-version=1.0
```
See [Headers and required parameters](/conventions/headers) for the full
reference. Endpoints that read or modify a user's data also need an
`Authorization: Bearer ` header — see [OAuth
2.0](/api-reference/oauth) or the [PIN flow](/api-reference/pin).
> ⚠️ **About the auto-rendered cURL examples on each endpoint page:** they
omit `?client_id=…&app-name=…&app-version=…` from the URL for brevity. **You
must add them yourself when copy-pasting**, or use the interactive **"Try
it"** playground (it fills them in for you). This is a Mintlify rendering
convention — every Mintlify-built API doc behaves the same way.
**Get started**
- [Quickstart](/quickstart) — first request in 60 seconds
- [API rules](/api-rules) — what's allowed, what isn't
- [Standard media objects](/conventions/standard-media-objects) — the shapes
every endpoint speaks
- [Errors](/conventions/errors) — every status code Simkl returns
contact:
name: Simkl Developer Support
url: https://support.simkl.com
termsOfService: https://simkl.com/about/policies/terms/
license:
name: Simkl API Terms of Use
url: https://simkl.com/about/policies/terms/
x-logo:
url: https://i.simkl.com/img_tv/apiary_logo_api.png
backgroundColor: '#0E5DAB'
altText: Simkl
servers:
- url: https://api.simkl.com
description: Production API
- url: https://data.simkl.in
description: CDN for static, public data files (Calendar + Trending). No auth required.
security:
- clientId: []
- simklApiKey: []
tags:
- name: OAuth 2.0
description: >-
OAuth 2.0 authorization-code flow for web and mobile apps. The user is
redirected to Simkl, signs in, approves your app, and is redirected back
with a `code` you exchange for an `access_token`. Long-lived tokens — no
refresh-token flow needed.
externalDocs:
description: OAuth 2.0 walkthrough
url: https://api.simkl.org/api-reference/oauth
- name: PIN
description: >-
Device flow for TVs, consoles, smart watches, CLI tools — anywhere typing
a URL is hard. Show a 5-character code; user enters it on simkl.com/pin;
you poll for the access token. **No `client_secret` required.**
externalDocs:
description: PIN flow walkthrough
url: https://api.simkl.org/api-reference/pin
- name: Redirect
description: >-
Helper redirects for one-click "mark as watched", trailers, sharing, and
more.
- name: Search
description: Find shows, movies, and anime by ID, text query, file name, or randomly.
externalDocs:
description: Search guide
url: https://api.simkl.org/guides/search
- name: Movies
description: >-
Browse the Simkl movies catalog: details, premieres, top-of-best, and
genre filters.
- name: TV
description: >-
Browse the Simkl TV catalog: details, episodes, what's airing, premieres,
top-of-best, and genre filters.
- name: Anime
description: >-
Browse the Simkl anime catalog: details, episodes, what's airing,
premieres, top-of-best, and genre filters.
- name: Ratings
description: >-
Read Simkl's average community rating, rank, drop rate, and external
ratings (IMDB, MAL) for any item, or for every item in a user's lists.
- name: Scrobble
description: >-
Report real-time playback to Simkl with `start`, `pause`, and `stop`. At ≥
80 % progress Simkl marks the item as watched automatically; below 80 %
the session is saved as a paused playback the user can resume from any
device.
See [Standard media objects](/conventions/standard-media-objects) for the
supported ID keys.
### Supported ID keys
Inside any `ids` object, pass as many of these as you have. Simkl resolves
to the canonical record.
| ID key | Type | Example |
|---|---|---|
| `simkl` | integer | `49108`. Simkl's canonical ID. Most reliable. |
| `imdb` | string | `tt1520211` |
| `tmdb` | integer | `76757` (for TV, specify `type`) |
| `tvdb` | int / string | `153021` or `the-walking-dead` |
| `mal` | integer | `4246` (MyAnimeList) |
| `anidb` | integer | `10846`. Specifying just this is enough for anime
lookups. |
| `anilist` | integer | `21` |
| `kitsu` | integer | `12` |
| `anisearch` | integer | `2227` |
| `animeplanet` | string | `one-piece` |
| `livechart` | integer | `321` |
| `letterboxd` | string | `the-truman-show` |
| `netflix` | integer | `70210890` (movie ID) |
| `traktslug` | string | `john-wick-chapter-4-2023` |
> 📖 Full reference: [Standard media
objects](/conventions/standard-media-objects)
externalDocs:
description: Scrobble guide
url: https://api.simkl.org/guides/scrobble
- name: Sync
description: >-
Use Simkl as a cloud backup for the user's watch history and lists
(Watching, Plan to Watch, On Hold, Dropped, Completed). **Always check
[`/sync/activities`](/api-reference/simkl/get-activities) first** and sync
only the lists that have moved.
All write endpoints accept arrays — batch aggressively. See [Standard
media objects](/conventions/standard-media-objects) for the supported ID
keys.
### Supported ID keys
Inside any `ids` object, pass as many of these as you have. Simkl resolves
to the canonical record.
| ID key | Type | Example |
|---|---|---|
| `simkl` | integer | `49108`. Simkl's canonical ID. Most reliable. |
| `imdb` | string | `tt1520211` |
| `tmdb` | integer | `76757` (for TV, specify `type`) |
| `tvdb` | int / string | `153021` or `the-walking-dead` |
| `mal` | integer | `4246` (MyAnimeList) |
| `anidb` | integer | `10846`. Specifying just this is enough for anime
lookups. |
| `anilist` | integer | `21` |
| `kitsu` | integer | `12` |
| `anisearch` | integer | `2227` |
| `animeplanet` | string | `one-piece` |
| `livechart` | integer | `321` |
| `letterboxd` | string | `the-truman-show` |
| `netflix` | integer | `70210890` (movie ID) |
| `traktslug` | string | `john-wick-chapter-4-2023` |
> 📖 Full reference: [Standard media
objects](/conventions/standard-media-objects)
externalDocs:
description: Sync guide
url: https://api.simkl.org/guides/sync
- name: Users
description: User profile, settings, and watch statistics.
externalDocs:
description: Simkl API documentation
url: https://api.simkl.org
paths:
/redirect:
get:
tags:
- Redirect
summary: Resolve any ID and redirect to Simkl
description: >-
A passive helper endpoint that **`301`-redirects** to a Simkl page (or
an action) given any combination of IDs or a title.
It's designed for two situations:
1. **Linking to Simkl when you don't have the Simkl ID** — turn an IMDB
/ TMDB / TVDB / MAL / AniDB ID, or a title + year, into a clickable
Simkl URL.
2. **Getting the Simkl ID with minimal info** — the cheapest way to
translate an external ID into a Simkl ID. **Read the `Location` response
header** and parse the `simkl_id` out of the URL path — no JSON to
parse.
> ⚠️ **Do not follow the 301.** Read the `Location` header directly. Use
`curl -I`, `requests.get(..., allow_redirects=False)`, `fetch(..., {
redirect: 'manual' })`, or your client's equivalent. The destination is
a public-facing page (simkl.com HTML, YouTube, Twitter intent, or
`/oauth/authorize`) and contains no API data — following the redirect
wastes bandwidth and can break (CORS, auth, destination-host rate
limits). This applies to **HTTP clients, scripts, automated tools, AI
agents, and LLM-driven workflows alike**.
>
> **What to do next, after reading the `Location` header:**
> - **If you only need the Simkl ID** — parse it out of the URL path
(e.g. `https://simkl.com/tv/17465/...` → `17465`) and **stop**. Don't
call anything else.
> - **If you also need the full record** (title, overview, poster,
fanart, ratings, trailers, etc.) — pass the parsed Simkl ID to the
matching Cloudflare-cached detail endpoint: [`GET
/movies/{id}`](/api-reference/simkl/get-movie), [`GET
/tv/{id}`](/api-reference/simkl/get-tv-show), [`GET
/anime/{id}`](/api-reference/simkl/get-anime), [`GET
/tv/episodes/{id}`](/api-reference/simkl/get-tv-episodes), or [`GET
/anime/episodes/{id}`](/api-reference/simkl/get-anime-episodes). Popular
titles come straight from edge cache.
>
> Full reference table of stop-at-301 invocations for popular HTTP
clients in the [Redirect
overview](/api-reference/redirect#use-case-2-resolve-an-external-id-to-a-simkl-id).
Like every Simkl endpoint, requests must include the [required URL
parameters](/conventions/headers#required-url-parameters) (`client_id`,
`app-name`, `app-version`) and a `User-Agent` header. No `Authorization`
token is needed except for `to=watched`, which signs the user in if they
aren't already.
#### `to=` action modes
| Mode | What the redirect points at |
|---|---|
| `simkl` *(default)* | The matching Simkl page
(`https://simkl.com/movies/{id}/{slug}`, `tv/...`, `anime/...`). |
| `trailer` | The trailer URL (typically YouTube). |
| `twitter` | A `twitter.com/intent/tweet` URL with the title and a
Simkl link prefilled. |
| `watched` | Marks the item watched on the user's account. If the user
isn't signed in, Simkl redirects to `/oauth/authorize` first. |
#### Identifier parameters
Pass any combination — the more, the more accurate the match. Most can
stand alone:
| Param | Notes |
|---|---|
| `simkl` | Simkl ID. |
| `imdb` | IMDB ID, or a full IMDB URL. |
| `tmdb` | TMDB ID. **Requires `type=movie` or `type=tv`** to
disambiguate — TMDB has no anime type (anime shows are filed under `tv`
on TMDB; Simkl routes them to its anime catalog automatically once
resolved). |
| `tvdb` | TVDB ID. |
| `mal`, `anidb`, `anilist`, `kitsu`, `livechart`, `anisearch`,
`animeplanet` | Anime-specific IDs. |
| `crunchyroll` | Crunchyroll show or episode ID/slug. |
| `netflix`, `hulu` | Streaming-service IDs (beta). |
| `title`, `year` | Title-based fallback. Pair with `type` for best
results. |
| `season`, `episode` | Episode targeting (`season` defaults to `1`).
Movies are ignored when either is set. |
| `ep_title` | Episode title used in the tweet text when `to=twitter`. |
| `type` | `movie`, `tv`, or `anime`. Required for `tmdb`; optional
otherwise (`show` matches both `tv` and `anime`). |
#### Response
- Status: **`301 Moved Permanently`**
- `Location`: the resolved URL (Simkl page, YouTube, Twitter intent, or
the OAuth authorize page when `to=watched` and the user isn't signed
in).
- `Cache-Control: no-store` — never cache the redirect itself; cache the
resolved URL on your side if you need to.
#### Why "lowest cost" for ID resolution
`GET /redirect?to=simkl&imdb=…` returns a `Location` header like
`https://simkl.com/movies/472214/inception`. The number after
`/movies/`, `/tv/`, or `/anime/` is the Simkl ID. Compared to `GET
/search/id`:
- **No JSON parse** — read the `Location` header, regex out the ID.
- **Tiny payload** — HTTP headers only, no response body.
Use this for "I have an IMDB ID, give me the Simkl ID" lookups when you
don't need the rest of the media object yet.
**Which IDs can I send/expect?** All accepted input identifiers and the
keys you'll see echoed back in responses are listed at [**Standard media
objects → Supported ID
keys**](/conventions/standard-media-objects#supported-id-keys). Send
every ID you have on writes — Simkl picks the first that resolves and
ignores the rest. Reminder: `slug` is **response-only** (never send it
on a request).
operationId: redirect
parameters:
- name: to
in: query
description: >-
Action mode. Determines the redirect target. Case-sensitive; must be
lowercase. Allowed values: `simkl` (search fallback), `trailer`,
`twitter`, `watched`.
required: true
schema:
type: string
enum:
- simkl
- trailer
- twitter
- watched
- name: title
in: query
description: TV show, anime, or movie title.
schema:
type: string
example: The Walking Dead
- name: year
in: query
description: release year.
schema:
type: integer
example: '2010'
- name: season
in: query
description: if set, movies will be ignored. Anime do not have seasons.
schema:
type: integer
default: 1
example: '1'
- name: episode
in: query
description: if set, movies will be ignored.
schema:
type: integer
example: '4'
- name: hulu
in: query
description: hulu_id. All other parameters can be empty if this one specified.
schema:
type: integer
example: '752375'
- name: netflix
in: query
description: Netflix `movieid`, this parameter is in beta and may not work.
schema:
type: integer
example: '70210890'
- name: mal
in: query
description: MyAnimeList `id`.
schema:
type: integer
example: '4246'
- name: tvdb
in: query
description: TVDB ID. All other parameters can be empty if this one specified.
schema:
type: integer
example: 153021, the-walking-dead
- name: type
in: query
description: Required for tmdb, if is searching for a TV Show
schema:
type: string
enum:
- show
- tv
- movie
- anime
example: show
- name: tmdb
in: query
description: >-
The Movie Database (TMDb) ID. To search TV Shows specify `type`
parameter. All other parameters can be empty if this one specified.
schema:
type: integer
example: '76757'
- name: imdb
in: query
description: >-
can be IMDB ID or full IMDB URL. All other parameters can be empty
if this one specified.
schema:
type: string
enum:
- tt1520211
- http://www.imdb.com/title/tt1520211/
example: tt1520211
- name: anidb
in: query
description: AniDB ID. All other parameters can be empty if this one specified.
schema:
type: integer
example: '10846'
- name: crunchyroll
in: query
description: Crunchyroll ID. You can pass episode ID or url ID(sword-art-online)
schema:
type: integer
example: '656641'
- name: anilist
in: query
description: AniList ID
schema:
type: integer
example: '21'
- name: kitsu
in: query
description: Kitsu ID
schema:
type: integer
example: '12'
- name: livechart
in: query
description: LiveChart ID
schema:
type: integer
example: '321'
- name: anisearch
in: query
description: aniSearch ID
schema:
type: integer
example: '2227'
- name: animeplanet
in: query
description: Anime-Planet ID
schema:
type: string
example: one-piece
- name: ep_title
in: query
required: false
schema:
type: string
description: >-
Episode title used to compose tweet text when `to=twitter`. Ignored
for other `to=` values.
- $ref: '#/components/parameters/ClientIdQuery'
- $ref: '#/components/parameters/AppNameQuery'
- $ref: '#/components/parameters/AppVersionQuery'
- $ref: '#/components/parameters/UserAgentHeader'
responses:
'301':
description: Permanent redirect to the resolved URL (the primary success path).
headers:
Location:
description: >-
Target URL chosen by the server based on the `to` mode and
inputs. Browsers (and most HTTP clients) follow this
automatically.
schema:
type: string
format: uri
example: >-
https://simkl.com/movies/53536/terminator-3-rise-of-the-machines
Cache-Control:
description: >-
Always `no-store` — the redirect resolves dynamically
per-request and must not be cached by browsers or CDNs.
schema:
type: string
example: no-store
'302':
description: >-
User will be redirected to the episode page plus
?mark=watched&client_id=***.
In this example user will be redirected to [Simkl: The Walking Dead
S01E4](https://simkl.com/tv/2090/the-walking-dead/season-1/episode-4/?mark=watched&client_id=***)
headers:
Location:
description: >-
Target URL chosen by the server based on the `to` mode and
inputs. Browsers (and most HTTP clients) follow this
automatically.
schema:
type: string
format: uri
example: >-
https://simkl.com/movies/53536/terminator-3-rise-of-the-machines
Cache-Control:
description: >-
Always `no-store` — the redirect resolves dynamically
per-request and must not be cached by browsers or CDNs.
schema:
type: string
example: no-store
content: {}
'412':
$ref: '#/components/responses/ClientIdFailed'
security:
- simklApiKey: []
components:
parameters:
ClientIdQuery:
name: client_id
in: query
required: true
description: >-
Your **`client_id`** from your [Simkl developer
settings](https://simkl.com/settings/developer/). Required on every
request.
schema:
type: string
example: YOUR_CLIENT_ID
AppNameQuery:
name: app-name
in: query
required: true
description: >-
Short, lowercase identifier for your app (e.g. `plex-scrobbler`,
`kodi-bridge`). Helps Simkl identify which apps are using the API.
schema:
type: string
example: my-app
AppVersionQuery:
name: app-version
in: query
required: true
description: >-
Your app's current version (e.g. `1.0`, `2.4.1`). Helps Simkl debug
issues you report.
schema:
type: string
example: '1.0'
UserAgentHeader:
name: User-Agent
in: header
required: true
description: >-
Descriptive identifier for your app, ideally `name/version`. Examples:
`PlexMediaServer/1.43.1.10540`, `kodi-simkl/0.9.2`, `MyApp/2.4.1
(https://myapp.com)`.
schema:
type: string
example: my-app/1.0
responses:
ClientIdFailed:
description: >-
Your `client_id` is missing, wrong, disabled, or has hit a request
limit. Verify in your [developer
settings](https://simkl.com/settings/developer/).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: client_id_failed
code: 412
message: Your client_id is wrong. Try another one
schemas:
ErrorResponse:
type: object
description: >-
Standard error envelope for 4xx and 5xx responses. Branch on `error`
(machine-readable identifier) — `message`, when present, is
human-readable guidance and is **not stable across releases**.
properties:
error:
type: string
description: >-
Machine-readable error identifier. Stable across responses — use
this for programmatic branching in client code. Examples:
`user_token_failed`, `client_id_failed`, `empty_field`,
`wrong_parameter`, `id_err`, `rate_limit`.
example: user_token_failed
code:
type: integer
description: >-
HTTP status code echoed in the body for convenience — same value as
the response status line. Always an integer.
example: 401
message:
type: string
description: >-
Human-readable error guidance. Optional — present on most errors,
but not guaranteed. May reference the specific field or value that
triggered the error. NOT stable; do not parse.
example: Your client_id is wrong. Try another one
required:
- error
- code
securitySchemes:
clientId:
type: apiKey
in: query
name: client_id
description: >-
Preferred form: your `client_id` as a URL query parameter on every
request. Self-describing in logs and curl commands. See [Headers and
required parameters](/conventions/headers).
x-default: YOUR_CLIENT_ID
simklApiKey:
type: apiKey
in: header
name: simkl-api-key
description: >-
Optional alias for the `client_id` query parameter. Simkl accepts your
`client_id` either as the `simkl-api-key` request header **or** as the
`?client_id=…` query parameter — pick one. The query-parameter form is
preferred because it makes the request fully self-describing in URL
form.
x-default: YOUR_CLIENT_ID
````