> ## 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.
# Start
> 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.
#### Body shape
Send `progress` plus exactly one of `movie`, `show`+`episode`, or `anime`+`episode`. See [Standard media objects](/conventions/standard-media-objects).
| Field | Type | Notes |
|---|---|---|
| `progress` | float | 0–100, max 2 decimals. Response normalizes to `75` not `75.00`. |
| `movie` / `show` / `anime` | object | Title + year + ids. `simkl` ID alone is enough. |
| `episode` | object | `season` + `number`, or `ids`. Required for shows/anime. |
#### Behavior
- Replaces any existing session for this item and clears prior pauses.
- Auto-expires after the calculated remaining runtime.
- If a previous start/checkin reached **≥ 80 %** before this call, it is **auto-scrobbled** (marked watched) before the new session starts.
- Response shape: `id`, `action`, `progress`, plus the media object with `ids` (incl. external links Simkl knows about) and an `episode` block. For anime, the response includes both AniDB-canonical `season`/`number` and original `tvdb_season`/`tvdb_number`.
#### Seek and scrub behavior
Don't call `/scrobble/start` on a seek event. Only call it when playback actually begins or resumes (typically the player's `play` event). When a user scrubs to a different position before pressing play, just update your local progress; the eventual `play` event fires the call with the new value.
#### Errors
| Code | When |
|---|---|
| `400empty_field` | No `movie`, `show`, or `anime` in the body. |
| `400RATE_LIMIT` | A 20-second per-user lock collision — another scrobble write for this user landed within the window. Note: HTTP `400`, **not** `429` — the lock failure is treated as a malformed request from a duplicate-fire client. |
| `401user_token_failed` | Missing / invalid bearer token. |
| `404id_err` | Item could not be matched. |
Real-time playback tracking — `/start`, `/pause`, `/stop` lifecycle, paused-playback resumption across devices, when scrobble auto-completes, and the difference between `/scrobble/checkin` (fire-and-forget) and `/scrobble/start` (active tracking).
Alternative to `episode.season` + `episode.number`: pass `episode.ids` with `tvdb` or `anidb` to identify the exact episode by external episode ID. Useful for Plex / media-server integrations that have a TVDB or AniDB episode ID but not the season/number mapping. (Episode-level `imdb` and `tmdb` IDs are **not** accepted — those exist only at the show/movie level. Use the `show`/`anime` object's `ids` for those.) If both forms are sent, `episode.ids` takes precedence.
**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 post /scrobble/start
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:
/scrobble/start:
post:
tags:
- Scrobble
summary: Start
description: >-
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.
#### Body shape
Send `progress` plus exactly one of `movie`, `show`+`episode`, or
`anime`+`episode`. See [Standard media
objects](/conventions/standard-media-objects).
| Field | Type | Notes |
|---|---|---|
| `progress` | float | 0–100, max 2 decimals. Response normalizes to
`75` not `75.00`. |
| `movie` / `show` / `anime` | object | Title + year + ids. `simkl` ID
alone is enough. |
| `episode` | object | `season` + `number`, or `ids`. Required for
shows/anime. |
#### Behavior
- Replaces any existing session for this item and clears prior pauses.
- Auto-expires after the calculated remaining runtime.
- If a previous start/checkin reached **≥ 80 %** before this call, it is
**auto-scrobbled** (marked watched) before the new session starts.
- Response shape: `id`, `action`, `progress`, plus the media object with
`ids` (incl. external links Simkl knows about) and an `episode` block.
For anime, the response includes both AniDB-canonical `season`/`number`
and original `tvdb_season`/`tvdb_number`.
#### Seek and scrub behavior
Don't call `/scrobble/start` on a seek event. Only call it when playback
actually begins or resumes (typically the player's `play` event). When a
user scrubs to a different position before pressing play, just update
your local progress; the eventual `play` event fires the call with the
new value.
#### Errors
| Code | When |
|---|---|
| `400empty_field` | No `movie`, `show`, or `anime` in the body. |
| `400RATE_LIMIT` | A 20-second per-user lock collision — another
scrobble write for this user landed within the window. Note: HTTP `400`,
**not** `429` — the lock failure is treated as a malformed request from
a duplicate-fire client. |
| `401user_token_failed` | Missing / invalid bearer token. |
| `404id_err` | Item could not be matched. |
Real-time playback tracking — `/start`, `/pause`, `/stop` lifecycle, paused-playback resumption across devices, when scrobble auto-completes, and the difference between `/scrobble/checkin` (fire-and-forget) and `/scrobble/start` (active tracking).
Alternative to `episode.season` + `episode.number`: pass `episode.ids`
with `tvdb` or `anidb` to identify the exact episode by external episode
ID. Useful for Plex / media-server integrations that have a TVDB or
AniDB episode ID but not the season/number mapping. (Episode-level
`imdb` and `tmdb` IDs are **not** accepted — those exist only at the
show/movie level. Use the `show`/`anime` object's `ids` for those.) If
both forms are sent, `episode.ids` takes precedence.
**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: post-scrobble-start
parameters:
- $ref: '#/components/parameters/ClientIdQuery'
- $ref: '#/components/parameters/AppNameQuery'
- $ref: '#/components/parameters/AppVersionQuery'
- $ref: '#/components/parameters/UserAgentHeader'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ScrobbleBody'
examples:
negative_scrobble_empty_body:
summary: 'REJECTED: empty body returns 400 empty_field'
description: >-
Unlike `POST /sync/history` (which accepts `{}` and returns
201 with zero counts), the scrobble endpoints REQUIRE a
media_type + ids in the body. Empty body returns the standard
400 envelope with `error: "empty_field"`.
value: {}
negative_scrobble_unknown_id:
summary: 'REJECTED: unknown Simkl ID returns 404 id_err'
description: >-
Scrobble endpoints validate the `ids.simkl` against the
catalog before recording the event. Unlike detail endpoints
(which return `200 []` for unknown IDs — Type 3 null), the
scrobble endpoints 404 with `error: "id_err"`.
value:
movie:
ids:
simkl: 999999999
progress: 25
scrobble_start_anime_episode:
summary: Begin scrobbling an anime episode (episode 1)
description: >-
Anime scrobble bodies use `anime:` (not `show:`) at the outer
level — different from /sync/all-items where anime entries
wrap in `show:` for cross-catalog compat. The `episode.season`
is `1` for AniDB-numbered anime; multi-season anime use
explicit seasons here.
value:
anime:
ids:
simkl: 831411
mal: 38000
anidb: 14116
anilist: 101922
episode:
season: 1
number: 1
progress: 25
scrobble_start_movie:
summary: Begin scrobbling a movie at 10% progress
description: >-
Tells Simkl that playback has started. The user appears as
'currently watching' on their profile. Update via /pause or
finalize via /stop. `progress` is a 0-100 integer.
value:
movie:
ids:
simkl: 472214
progress: 10
scrobble_start_show_episode:
summary: Begin scrobbling a TV episode (S01E01)
description: >-
TV scrobbles need both `show.ids` AND `episode.season` +
`episode.number`. The episode is the unit of playback for
scrobble; the show ID resolves the parent record. Anime use
the same shape — see the next example.
value:
show:
ids:
simkl: 2090
episode:
season: 1
number: 1
progress: 25
responses:
'201':
description: Created
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ScrobbleResponse'
examples:
scrobble_start_anime_episode:
summary: Begin scrobbling an anime episode (episode 1)
description: >-
Anime scrobble bodies use `anime:` (not `show:`) at the
outer level — different from /sync/all-items where anime
entries wrap in `show:` for cross-catalog compat. The
`episode.season` is `1` for AniDB-numbered anime;
multi-season anime use explicit seasons here.
value:
id: 0
action: start
progress: 25
episode:
season: 1
number: 1
title: Cruelty
tvdb_season: 1
tvdb_number: 1
anime:
title: Kimetsu no Yaiba
year: 2019
anime_type: tv
ids:
simkl: 831411
slug: kimetsu-no-yaiba
imdb: tt9335498
mal: '38000'
tvdbslug: demon-slayer-kimetsu-no-yaiba
anilist: '101922'
kitsu: '41370'
trakttvslug: demon-slayer-kimetsu-no-yaiba
anidb: '14107'
tvdb: '348545'
tmdb: '85937'
scrobble_start_movie:
summary: Begin scrobbling a movie at 10% progress
description: >-
Tells Simkl that playback has started. The user appears as
'currently watching' on their profile. Update via /pause or
finalize via /stop. `progress` is a 0-100 integer.
value:
id: 0
action: start
progress: 10
movie:
title: Inception
year: 2010
ids:
simkl: 472214
slug: inception
imdb: tt1375666
letterslug: inception
traktmslug: inception-2010
tmdb: '27205'
tvdbslug: inception
tvdb: '113'
scrobble_start_show_episode:
summary: Begin scrobbling a TV episode (S01E01)
description: >-
TV scrobbles need both `show.ids` AND `episode.season` +
`episode.number`. The episode is the unit of playback for
scrobble; the show ID resolves the parent record. Anime use
the same shape — see the next example.
value:
id: 0
action: start
progress: 25
episode:
season: 1
number: 1
title: Days Gone Bye
show:
title: The Walking Dead
year: 2010
ids:
simkl: 2090
slug: the-walking-dead
imdb: tt1520211
tvdbslug: the-walking-dead
trakttvslug: the-walking-dead
tvdb: '153021'
tmdb: '1402'
'400':
$ref: '#/components/responses/BadRequest'
content:
application/json:
examples:
negative_scrobble_empty_body:
summary: 'REJECTED: empty body returns 400 empty_field'
description: >-
Unlike `POST /sync/history` (which accepts `{}` and returns
201 with zero counts), the scrobble endpoints REQUIRE a
media_type + ids in the body. Empty body returns the
standard 400 envelope with `error: "empty_field"`.
value:
error: empty_field
code: 400
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
content:
application/json:
examples:
negative_scrobble_unknown_id:
summary: 'REJECTED: unknown Simkl ID returns 404 id_err'
description: >-
Scrobble endpoints validate the `ids.simkl` against the
catalog before recording the event. Unlike detail endpoints
(which return `200 []` for unknown IDs — Type 3 null), the
scrobble endpoints 404 with `error: "id_err"`.
value:
error: id_err
code: 404
'412':
$ref: '#/components/responses/ClientIdFailed'
'500':
$ref: '#/components/responses/ServerError'
security:
- clientId: []
bearerAuth: []
- simklApiKey: []
bearerAuth: []
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
schemas:
ScrobbleBody:
type: object
description: >-
Request body for the four scrobble endpoints. Send exactly one of
`movie`, `show`+`episode`, or `anime`+`episode` — all keys are singular
objects (one item per request). For batch sync writes the keys are
plural arrays: see
[`/sync/history`](/api-reference/simkl/add-to-history) etc. `progress`
is required for `/scrobble/start`, `/scrobble/pause`, and
`/scrobble/stop`; on `/scrobble/checkin` it is optional and ignored
server-side.
**Anime under `show`?** Yes — if you don't know whether a title is anime
(e.g. you only have TMDB/TVDB data), send it under `show` and Simkl
resolves it to the correct catalog automatically. The `anime` key is
only needed when you want to pass `anidb` / `mal` / `anilist` IDs that
don't exist at the TV-show level.
oneOf:
- title: Movie
required:
- movie
- title: TV episode
required:
- show
- episode
- title: Anime episode
required:
- anime
- episode
properties:
progress:
type: number
format: float
minimum: 0
maximum: 100
description: >-
Playback percentage 0-100. Up to 2 decimals. Required for
`/scrobble/start`, `/scrobble/pause`, `/scrobble/stop`. Optional
(and ignored) for `/scrobble/checkin`.
movie:
type: object
description: >-
Movie reference. Use `ids` (any one external ID) and optionally
`title` / `year`. Movies have no `episode` block.
properties:
title:
type: string
example: Inception
year:
type: integer
example: 2010
ids:
$ref: '#/components/schemas/MovieIds'
required:
- ids
show:
type: object
description: TV show reference (must be paired with `episode`).
properties:
title:
type: string
example: Stranger Things
year:
type: integer
example: 2016
ids:
$ref: '#/components/schemas/ShowIds'
required:
- ids
anime:
type: object
description: >-
Anime reference. Pair with `episode` for series; an `anime` alone
(no `episode`) is treated as an anime movie / OVA.
properties:
title:
type: string
example: Shingeki no Kyojin
year:
type: integer
example: 2013
ids:
$ref: '#/components/schemas/AnimeIds'
required:
- ids
episode:
type: object
description: >-
Episode identifier. Use `season` + `number`, OR `ids` with a `tvdb`
/ `anidb` episode ID. If both are sent, `episode.ids` takes
precedence (matches Plex-style integrations that have an episode ID
but no season/number mapping).
oneOf:
- required:
- season
- number
title: By season + number
- required:
- ids
title: By episode ID
properties:
season:
type: integer
minimum: 0
example: 1
description: Season number. `0` is the specials season.
number:
type: integer
minimum: 1
example: 3
description: Episode number within the season.
ids:
$ref: '#/components/schemas/EpisodeIds'
ScrobbleResponse:
type: object
description: Response for `/scrobble/start`, `/scrobble/pause`, and `/scrobble/stop`.
properties:
action:
type: string
enum:
- start
- pause
- scrobble
description: >-
`start` for /start, `pause` for /pause and for /stop with
progress<80, `scrobble` for /stop with progress≥80 (item marked
watched).
progress:
type: number
description: Echo of the request progress, normalized.
sid:
type: string
description: Internal session ID.
movie:
$ref: '#/components/schemas/Movie'
show:
$ref: '#/components/schemas/Show'
anime:
$ref: '#/components/schemas/Anime'
episode:
$ref: '#/components/schemas/Episode'
tvdb_season:
type: integer
description: 'For anime: original TVDB season number when AniDB mapping differs.'
tvdb_number:
type: integer
description: 'For anime: original TVDB episode number when AniDB mapping differs.'
MovieIds:
type: object
description: >-
External IDs for a movie. Pass any one or more — Simkl resolves the
canonical record by walking these in priority order. `simkl` is the most
reliable when you have it.
properties:
simkl:
type: integer
description: Simkl movie ID.
example: 472214
slug:
type: string
description: Simkl URL slug (echoed back in responses).
example: inception
imdb:
type: string
description: IMDb ID, e.g. `tt1375666`.
example: tt1375666
tmdb:
type: integer
description: TMDb movie ID.
example: 27205
netflix:
type: integer
description: Netflix movie ID.
traktslug:
type: string
description: Trakt movie slug, e.g. `inception-2010`.
letterboxd:
type: string
description: Letterboxd slug, e.g. `inception`.
boxd:
type: string
description: Letterboxd numeric ID (alternative to `letterboxd`).
additionalProperties: true
ShowIds:
type: object
description: External IDs for a TV show. Pass any one or more.
properties:
simkl:
type: integer
description: Simkl show ID.
example: 548312
slug:
type: string
description: Simkl URL slug (echoed back in responses).
example: stranger-things
imdb:
type: string
description: IMDb ID, e.g. `tt4574334`.
example: tt4574334
tmdb:
type: integer
description: TMDb show ID.
example: 66732
tvdb:
description: TVDB show ID (integer) or slug (string).
oneOf:
- type: integer
- type: string
example: 305288
netflix:
type: integer
description: Netflix show ID.
hulu:
type: integer
description: Hulu show ID.
traktslug:
type: string
description: Trakt show slug.
zap2it:
type: string
description: Zap2it ID.
tvcom:
type: string
description: TV.com ID.
mdl:
type: string
description: MyDramaList slug or ID.
additionalProperties: true
AnimeIds:
type: object
description: >-
External IDs for an anime. Any one is enough; `mal` / `anidb` /
`anilist` / `kitsu` are most useful for anime-only sources, while
`simkl`, `imdb`, `tmdb`, and `tvdb` work for the cross-domain mapping.
properties:
simkl:
type: integer
description: Simkl anime ID.
example: 39687
slug:
type: string
description: Simkl URL slug.
example: shingeki-no-kyojin
imdb:
type: string
description: IMDb ID.
example: tt2560140
tmdb:
type: integer
description: TMDb show or movie ID (depending on anime_type).
example: 1429
tvdb:
description: TVDB show ID (integer) or slug (string).
oneOf:
- type: integer
- type: string
example: 267440
mal:
type: integer
description: MyAnimeList ID.
example: 16498
anidb:
type: integer
description: AniDB ID. Specifying just this is enough for anime lookups.
example: 9541
anilist:
type: integer
description: AniList ID.
example: 16498
kitsu:
type: integer
description: Kitsu ID.
example: 7442
anisearch:
type: integer
description: aniSearch ID.
animeplanet:
type: string
description: Anime-Planet slug.
livechart:
type: integer
description: LiveChart ID.
anfo:
type: integer
description: AnimeNewsNetwork-style anfo ID.
ann:
type: integer
description: AnimeNewsNetwork ID.
additionalProperties: true
EpisodeIds:
type: object
description: >-
External IDs for an episode. Only `tvdb` and `anidb` are accepted as
scrobble episode-ID lookups. Pass either; if both are sent, `tvdb` is
tried first.
properties:
tvdb:
type: integer
description: TVDB episode ID.
example: 4274616
anidb:
type: integer
description: AniDB episode ID.
example: 142278
additionalProperties: false
Movie:
type: object
description: >-
Standard movie object. See the [Standard Media
Objects](/conventions/standard-media-objects) guide.
properties:
title:
type: string
example: 'Terminator 3: Rise of the Machines'
year:
type: integer
example: 2003
ids:
$ref: '#/components/schemas/Ids'
required:
- ids
Show:
type: object
description: >-
Standard show object. May include nested seasons/episodes for partial
sync.
properties:
title:
type: string
example: The Walking Dead
year:
type: integer
example: 2010
ids:
$ref: '#/components/schemas/Ids'
seasons:
type: array
items:
type: object
properties:
number:
type: integer
episodes:
type: array
items:
$ref: '#/components/schemas/Episode'
required:
- ids
Anime:
type: object
description: >-
Standard anime object. Like Show, but may include `anime_type`. Episode
numbering follows AniDB.
properties:
title:
type: string
example: Attack on Titan
year:
type: integer
example: 2013
anime_type:
$ref: '#/components/schemas/AnimeFormat'
ids:
$ref: '#/components/schemas/Ids'
episodes:
type: array
items:
$ref: '#/components/schemas/Episode'
required:
- ids
Episode:
type: object
description: Episode reference. Use `season` + `number`, or `ids`.
properties:
season:
type: integer
minimum: 0
example: 1
number:
type: integer
minimum: 1
example: 2
watched_at:
type: string
format: date-time
example: '2014-09-01T09:10:11Z'
description: ISO-8601 GMT timestamp.
ids:
$ref: '#/components/schemas/Ids'
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
Ids:
type: object
description: >-
External and internal identifiers for an item. Pass as many as you have
— Simkl resolves to the canonical record.
properties:
simkl:
type: integer
description: Simkl internal ID. Most reliable.
example: 53536
slug:
type: string
description: URL-safe slug returned in responses.
example: attack-on-titan
imdb:
type: string
description: IMDb ID.
example: tt0181852
tmdb:
type: string
description: TMDb ID.
example: '296'
tvdb:
oneOf:
- type: integer
- type: string
description: TVDB ID or slug.
example: 153021
mal:
type: string
description: MyAnimeList ID.
example: '4246'
anidb:
type: string
description: AniDB ID. Specifying just this is enough for anime lookups.
example: '10846'
anilist:
type: string
description: AniList ID.
example: '21'
kitsu:
type: string
description: Kitsu ID.
example: '12'
anisearch:
type: string
description: aniSearch ID.
example: '2227'
animeplanet:
type: string
description: Anime-Planet slug.
example: one-piece
livechart:
type: string
description: LiveChart ID.
example: '321'
letterboxd:
type: string
description: Letterboxd slug.
example: the-truman-show
netflix:
type: string
description: Netflix movie ID.
example: '70210890'
hulu:
type: string
description: Hulu episode ID.
crunchyroll:
type: string
description: Crunchyroll episode ID.
traktslug:
type: string
description: Trakt slug.
example: john-wick-chapter-4-2023
additionalProperties: true
example:
simkl: 53536
imdb: tt0181852
tmdb: 296
AnimeFormat:
type: string
enum:
- tv
- movie
- special
- ova
- ona
- music video
description: >-
Anime production format. `tv` is the common case; movies, OVAs, ONAs,
and music videos all surface through the `/anime/*` endpoints with the
same response shape.
responses:
BadRequest:
description: Bad request — a required field is missing or has the wrong shape.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: empty_field
code: 400
message: Missed "to" parameter
Unauthorized:
description: >-
Missing or invalid user access token. Provide a valid `Authorization:
Bearer ` header.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: user_token_failed
code: 401
NotFound:
description: The requested item ID or URL does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: id_err
code: 404
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
ServerError:
description: >-
Something is broken on Simkl's side. Retry after a short delay. If it
persists, report on the [Simkl Discord](https://discord.gg/MJsWNE4).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: internal
code: 500
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
bearerAuth:
type: http
scheme: bearer
description: >-
OAuth 2.0 or PIN-flow `access_token`. Required for endpoints that read
or modify the user's library, scrobble session, ratings, settings, or
playbacks. See [Authentication](/authentication).
x-default: YOUR_ACCESS_TOKEN
````