> ## 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.
# Anime details
> 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 already complete; no flags needed.
Responses are **Cloudflare-cached by Simkl ID**, so repeat lookups of popular titles are near-free. Parallel requests against this endpoint are explicitly allowed (see [Rate limits → Parallel requests](/resources/rate-limits#parallel-requests--when-allowed)).
**Cache invalidation is automatic.** When Simkl updates the underlying record (admin edits, automated metadata refresh, image swap, related-titles change, etc.), the corresponding Cloudflare cache entry is purged server-side. The next call to this endpoint returns the fresh data — there's no TTL to wait out and no client-side cache-busting needed. Your own app-level cache, if any, still has to be invalidated by your client.
Use a Simkl ID for the lookup. If you only have an external ID, resolve it via [`GET /redirect`](/api-reference/redirect) first.
**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 /anime/{id}
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:
/anime/{id}:
get:
tags:
- Anime
summary: Anime details
description: >-
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 already complete; no flags needed.
Responses are **Cloudflare-cached by Simkl ID**, so repeat lookups of
popular titles are near-free. Parallel requests against this endpoint
are explicitly allowed (see [Rate limits → Parallel
requests](/resources/rate-limits#parallel-requests--when-allowed)).
**Cache invalidation is automatic.** When Simkl updates the underlying
record (admin edits, automated metadata refresh, image swap,
related-titles change, etc.), the corresponding Cloudflare cache entry
is purged server-side. The next call to this endpoint returns the fresh
data — there's no TTL to wait out and no client-side cache-busting
needed. Your own app-level cache, if any, still has to be invalidated by
your client.
Use a Simkl ID for the lookup. If you only have an external ID, resolve
it via [`GET /redirect`](/api-reference/redirect) first.
**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: get-anime-id
parameters:
- name: id
in: path
description: >-
**Simkl ID** for the item. Simkl IDs are stable, unambiguous, and
the response is Cloudflare-cached by Simkl ID, so repeat lookups are
very fast.
**If you only have an external ID** (IMDb, TMDB, TVDB, MAL, AniDB,
etc.), resolve it to a Simkl ID first via [`GET
/redirect`](/api-reference/redirect) — it returns the Simkl ID in
the `Location` header without a JSON payload, and the follow-up
detail call is Cloudflare-cached.
required: true
schema:
type: string
example: '831411'
- $ref: '#/components/parameters/ClientIdQuery'
- $ref: '#/components/parameters/AppNameQuery'
- $ref: '#/components/parameters/AppVersionQuery'
- $ref: '#/components/parameters/UserAgentHeader'
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/AnimeDetail'
- type: array
items: {}
maxItems: 0
title: Empty (unknown Simkl ID)
description: Empty array `[]` — see `unknown_id_empty` example below.
examples:
demon_slayer:
summary: Modern shounen (Demon Slayer, simkl 831411)
description: >-
Modern ongoing anime. Has the canonical anime ID set (`mal`,
`anidb`, `anilist`, `kitsu`) alongside the shared external
IDs. Ratings carry `simkl` + `mal` but **no `imdb`** — most
modern anime aren't catalogued there. Exercises `anime_type:
tv`, `studios`, `mapped_tvdb_seasons`.
value:
title: Kimetsu no Yaiba
en_title: 'Demon Slayer: Kimetsu no Yaiba'
year: 2019
type: anime
anime_type: tv
ids:
simkl: 831411
slug: kimetsu-no-yaiba
imdb: tt9335498
mal: '38000'
tvdb: '348545'
tvdbslug: demon-slayer-kimetsu-no-yaiba
tmdb: '85937'
anilist: '101922'
kitsu: '41370'
trakttvslug: demon-slayer-kimetsu-no-yaiba
anidb: '14107'
rank: 14
droprate: 0.8%
poster: 10/108215c95bbe0c40c
fanart: 11/11108654def22b4f7
runtime: 25
certification: TV-MA
country: JP
overview: >-
It is the Taisho Period in Japan. Tanjiro, a kindhearted
boy who sells charcoal for a living, finds his family
slaughtered by a demon. To make matters worse, his younger
sister Nezuko, the sole survivor, has been transformed
into a demon herself.
genres:
- Action
- Adventure
- Fantasy
network: Fuji TV
status: ended
first_aired: '2019-04-06'
last_aired: '2024-06-30'
airs:
day: Sunday
time: '23:15'
timezone: Asia/Tokyo
total_episodes: 55
year_start_end: 2019-
season_name_year: Spring 2019
mapped_tvdb_seasons:
- 1
studios:
- name: ufotable
relations: {}
alt_titles:
- name: 'Demon Slayer: Kimetsu no Yaiba'
lang: 22
type: official
- name: 鬼滅の刃
lang: 25
type: original
ratings:
simkl:
rating: 8.7
votes: 1850
mal:
rating: 8.6
votes: 1620000
trailers:
- name: PV
youtube: VQGCKyvzIM4
size: 1080
users_recommendations:
- title: Jujutsu Kaisen
year: 2020
poster: 73/73892ec77b6c7e9d
type: anime
ids:
simkl: 1110742
slug: jujutsu-kaisen
classic_with_triple_ratings:
summary: >-
Classic anime with imdb+mal+simkl ratings (Death Note, simkl
40190)
description: >-
Established classic that pre-dates the MAL-only era of
recent anime catalogs. Has the **rare triple-rating**
(`simkl` + `mal` + `imdb`). Demonstrates `en_title` as an
empty string — Type 4 null (data not on file in that exact
slot, but a non-null fallback was returned for back-compat).
Use this to test code that handles both `null` and
empty-string for the same semantic.
value:
title: Death Note
en_title: null
year: 2006
type: anime
anime_type: tv
ids:
simkl: 40190
slug: death-note
imdb: tt0877057
mal: '1535'
tvdb: '79481'
tvdbslug: death-note
tmdb: '13916'
anilist: '1535'
kitsu: '1376'
anidb: '4563'
rank: 5
poster: 60/60822040ab21d22b
runtime: 25
country: JP
genres:
- Mystery
- Psychological
- Supernatural
- Thriller
network: Nippon TV
status: Ended
first_aired: '2006-10-04'
last_aired: '2007-06-27'
total_episodes: 37
year_start_end: 2006-2007
season_name_year: Fall 2006
studios:
- name: Madhouse
ratings:
simkl:
rating: 9
votes: 4200
mal:
rating: 8.6
votes: 3700000
imdb:
rating: 9
votes: 410000
unknown_id_empty:
summary: Unknown Simkl ID — empty array (Type 3 null)
description: >-
When the path Simkl ID is well-formed (numeric) but no
catalog record exists at that ID, the response is `200 []`,
not `404`. Treat as 'not found' — see [Null and missing
values · Type 3](/conventions/null-values#type-3).
value: []
'412':
$ref: '#/components/responses/ClientIdFailed'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
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
schemas:
AnimeDetail:
type: object
description: >-
Full anime record returned by `GET /anime/{id}`. Shares most fields with
`ShowDetail` and adds anime-specific keys: `anime_type`, `en_title`,
`studios`, `relations`, `season_name_year`, `mapped_tvdb_seasons`, plus
extra `ids` (`mal`, `anidb`, `anilist`, `kitsu`). Cloudflare-cached by
Simkl ID. The `extended` query param is a legacy no-op here. The anime
detail handler is `include`d from the TV detail handler ( → `include
''`), so the response shape is identical to `ShowDetail` plus the
anime-specific fields below.
required:
- title
- year
- type
- ids
- anime_type
properties:
title:
type: string
description: Original-language title (often romanized Japanese for anime).
en_title:
type:
- string
- 'null'
description: >-
Localized English title when available. Type 4 null when no English
title is on file (e.g. older classics like Death Note return an
empty string here).
year:
type: integer
type:
type: string
enum:
- anime
description: Always `anime` on this endpoint.
anime_type:
$ref: '#/components/schemas/AnimeFormat'
ids:
$ref: '#/components/schemas/Ids'
rank:
type:
- integer
- 'null'
description: >-
Type 4 null — data not on file in that field's slot. See [Null and
missing values](/conventions/null-values).
droprate:
type:
- string
- 'null'
description: >-
Type 4 null — data not on file in that field's slot. See [Null and
missing values](/conventions/null-values).
poster:
type:
- string
- 'null'
description: >-
Type 4 null — data not on file in that field's slot. See [Null and
missing values](/conventions/null-values).
fanart:
type:
- string
- 'null'
description: >-
Type 4 null — data not on file in that field's slot. See [Null and
missing values](/conventions/null-values).
runtime:
type:
- integer
- 'null'
description: >-
Type 4 null — data not on file in that field's slot. See [Null and
missing values](/conventions/null-values). Episode runtime in
minutes.
certification:
type:
- string
- 'null'
description: >-
Type 4 null — data not on file in that field's slot. See [Null and
missing values](/conventions/null-values).
country:
type:
- string
- 'null'
description: Almost always `JP` for anime. Type 4 null on rare productions.
overview:
type:
- string
- 'null'
description: >-
Type 4 null — data not on file in that field's slot. See [Null and
missing values](/conventions/null-values).
genres:
type: array
items:
type: string
network:
type:
- string
- 'null'
description: >-
Type 4 null — data not on file in that field's slot. See [Null and
missing values](/conventions/null-values). Originating TV station /
streamer.
status:
type:
- string
- 'null'
description: >-
Type 4 null — data not on file in that field's slot. See [Null and
missing values](/conventions/null-values). Production lifecycle
bucket. **Closed set** of three values; the value is computed from
the catalog's `Status` column plus the next-release timestamp at
request time:
- `tba` — air date is in the future (next-release timestamp > now)
- `ended` — catalog status is `Ended`
- `airing` — everything else (currently releasing, ongoing, hiatus)
Note this is the **detail-endpoint** status. Listing endpoints
(/anime/airing, /anime/best, etc.) use a wider enum from `::`
(`returning series`, `ongoing`, `released`, `canceled`, `planned`,
`in production`, `post production`, `rumored`, `upcoming`) —
different shape, document separately.
enum:
- tba
- ended
- airing
- null
first_aired:
type:
- string
- 'null'
format: date
description: >-
Type 4 null — data not on file in that field's slot. See [Null and
missing values](/conventions/null-values).
last_aired:
type:
- string
- 'null'
format: date
description: >-
Type 4 null — data not on file in that field's slot. See [Null and
missing values](/conventions/null-values).
airs:
type:
- object
- 'null'
additionalProperties: true
description: >-
Type 4 null — data not on file in that field's slot. See [Null and
missing values](/conventions/null-values).
total_episodes:
type:
- integer
- 'null'
description: >-
Type 4 null — data not on file in that field's slot. See [Null and
missing values](/conventions/null-values).
year_start_end:
type:
- string
- 'null'
description: >-
Type 4 null — data not on file in that field's slot. See [Null and
missing values](/conventions/null-values).
season_name_year:
type:
- string
- 'null'
description: >-
Type 4 null — data not on file in that field's slot. See [Null and
missing values](/conventions/null-values). Display string like
`Spring 2019` indicating the broadcasting cour.
mapped_tvdb_seasons:
type: array
items:
type: integer
description: >-
AniDB/Simkl season numbers mapped onto the corresponding TVDB season
numbers (anime catalogues split seasons differently between
databases).
studios:
type: array
items:
type: object
additionalProperties: true
description: >-
Production studios. Each entry typically carries a `name` and other
identifiers.
relations:
type: array
description: >-
Related-titles graph: prequels, sequels, side stories, alternate
versions. Each entry carries a small media-object plus a
`relation_type` and `is_direct` flag indicating the relation.
items:
type: object
additionalProperties: true
properties:
title:
type: string
en_title:
type:
- string
- 'null'
description: >-
Type 4 null — data not on file in that field's slot. See [Null
and missing values](/conventions/null-values).
year:
type: integer
anime_type:
$ref: '#/components/schemas/AnimeFormat'
relation_type:
type: string
is_direct:
type: boolean
ids:
$ref: '#/components/schemas/Ids'
alt_titles:
type: array
items:
type: object
properties:
name:
type: string
lang:
type: integer
type:
$ref: '#/components/schemas/AltTitleType'
ratings:
type: object
description: >-
Ratings keyed by source. Anime always carry `simkl` and `mal`;
classic anime also include `imdb` when an IMDb entry exists.
properties:
simkl:
$ref: '#/components/schemas/ExternalRating'
mal:
$ref: '#/components/schemas/ExternalRating'
imdb:
$ref: '#/components/schemas/ExternalRating'
additionalProperties:
$ref: '#/components/schemas/ExternalRating'
trailers:
type:
- array
- 'null'
items:
type: object
properties:
name:
type:
- string
- 'null'
description: >-
Type 4 null — data not on file in that field's slot. See [Null
and missing values](/conventions/null-values).
youtube:
type: string
size:
type:
- integer
- 'null'
description: >-
Type 4 null — data not on file in that field's slot. See [Null
and missing values](/conventions/null-values).
description: >-
Type 4 null — data not on file in that field's slot. See [Null and
missing values](/conventions/null-values).
users_recommendations:
type: array
items:
type: object
properties:
title:
type: string
year:
type:
- integer
- 'null'
description: >-
Type 4 null — data not on file in that field's slot. See [Null
and missing values](/conventions/null-values).
poster:
type:
- string
- 'null'
description: >-
Type 4 null — data not on file in that field's slot. See [Null
and missing values](/conventions/null-values).
type:
type: string
ids:
type: object
properties:
simkl:
type: integer
slug:
type: string
additionalProperties: true
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.
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
AltTitleType:
type: string
enum:
- official
- short
- synonym
- original
description: >-
Classification of an entry in `alt_titles`. `official` =
broadcaster/distributor-supplied localization, `short` = shortened form,
`synonym` = community-supplied alias, `original` = original-language
title (typically Japanese for anime).
ExternalRating:
type: object
description: External-source rating.
properties:
rating:
type: number
minimum: 0
maximum: 10
description: Rating value (0–10).
votes:
type: integer
description: Number of votes contributing to the rating.
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
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
RateLimited:
description: >-
Too many requests in too short a window. Back off and retry with
exponential backoff — see [Rate limits](/resources/rate-limits) for the
playbook.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: rate_limit
code: 429
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
````