> ## 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.
# Find an item by file name
> Identify a single video file the user just opened. Pass one filename and Simkl returns the matched movie, or the show + the specific episode the filename names. Built for desktop scrobblers and player overlays that need to recognize what the user is currently watching — apps that don't already have parsed metadata from a media server.
**Not for library scraping.** Calling `/search/file` for every file in a user's library is against the rate limits and will get the integration throttled. If you already have a media server (Plex, Kodi, Jellyfin, Emby, …) it already has parsed metadata for every file — use that. This endpoint is for ad-hoc, one-file-at-a-time identification.
The server normalizes the filename (release tags, resolution, codec markers, group names) and matches it against the Simkl catalog — so messy real-world filenames like `Stranger.Things.S01E03.1080p.WEB.x264-GROUP.mkv` work fine.
#### Body fields
| Field | Required | Notes |
|---|---|---|
| `file` | yes | The file name or `/path/to/folder/file.mkv`. The alias `File` (capital F) is also accepted for legacy clients. |
| `part` | no | 1-based part index for multi-part files (`S01E01E02.mkv` is two episodes — pass `part: 2` for the second). Default `1`. |
| `process` | no | Optional pre-processing hint forwarded to the parser. Most clients can omit. |
| `hash` | no | Optional file hash for additional disambiguation. |
#### Response shape — discriminated by `type`
The top-level `type` field tells you which variant you got:
| `type` | When | Top-level blocks present |
|---|---|---|
| `"movie"` | Filename matched a movie | `movie` |
| `"show"` | Filename matched a TV/anime show but no specific episode | `show` |
| `"episode"` | Filename matched a TV/anime episode | `show` + `episode` |
Movies and shows carry an `ids` block populated by Simkl's link database — typically `simkl` + several external IDs (`imdb`, `tmdb`/`tmdbtv`, `tvdb`, anime sources like `mal` / `anidb` / `anilist` / `kitsu` / `crunchyroll`, plus slugs for Letterboxd / Trakt / TVDB). Anime episodes return as `type: "episode"` with the standard show+episode blocks — the file parser doesn't distinguish anime from TV at the top level.
#### Edge responses (status 200)
| Body | Meaning |
|---|---|
| `null` | Empty or malformed request body — no `file` field present. |
| `[]` | Parser ran but couldn't match the filename to anything in the database. |
Both are 200 — there's no 404 or 400 for these cases. Treat both as "no match" in client code.
**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 /search/file
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:
/search/file:
post:
tags:
- Search
summary: Find an item by file name
description: >-
Identify a single video file the user just opened. Pass one filename and
Simkl returns the matched movie, or the show + the specific episode the
filename names. Built for desktop scrobblers and player overlays that
need to recognize what the user is currently watching — apps that don't
already have parsed metadata from a media server.
**Not for library scraping.** Calling `/search/file` for every file in a
user's library is against the rate limits and will get the integration
throttled. If you already have a media server (Plex, Kodi, Jellyfin,
Emby, …) it already has parsed metadata for every file — use that. This
endpoint is for ad-hoc, one-file-at-a-time identification.
The server normalizes the filename (release tags, resolution, codec
markers, group names) and matches it against the Simkl catalog — so
messy real-world filenames like
`Stranger.Things.S01E03.1080p.WEB.x264-GROUP.mkv` work fine.
#### Body fields
| Field | Required | Notes |
|---|---|---|
| `file` | yes | The file name or `/path/to/folder/file.mkv`. The alias
`File` (capital F) is also accepted for legacy clients. |
| `part` | no | 1-based part index for multi-part files (`S01E01E02.mkv`
is two episodes — pass `part: 2` for the second). Default `1`. |
| `process` | no | Optional pre-processing hint forwarded to the parser.
Most clients can omit. |
| `hash` | no | Optional file hash for additional disambiguation. |
#### Response shape — discriminated by `type`
The top-level `type` field tells you which variant you got:
| `type` | When | Top-level blocks present |
|---|---|---|
| `"movie"` | Filename matched a movie | `movie` |
| `"show"` | Filename matched a TV/anime show but no specific episode |
`show` |
| `"episode"` | Filename matched a TV/anime episode | `show` + `episode`
|
Movies and shows carry an `ids` block populated by Simkl's link database
— typically `simkl` + several external IDs (`imdb`, `tmdb`/`tmdbtv`,
`tvdb`, anime sources like `mal` / `anidb` / `anilist` / `kitsu` /
`crunchyroll`, plus slugs for Letterboxd / Trakt / TVDB). Anime episodes
return as `type: "episode"` with the standard show+episode blocks — the
file parser doesn't distinguish anime from TV at the top level.
#### Edge responses (status 200)
| Body | Meaning |
|---|---|
| `null` | Empty or malformed request body — no `file` field present. |
| `[]` | Parser ran but couldn't match the filename to anything in the
database. |
Both are 200 — there's no 404 or 400 for these cases. Treat both as "no
match" in client code.
**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-search-file
parameters:
- $ref: '#/components/parameters/ClientIdQuery'
- $ref: '#/components/parameters/AppNameQuery'
- $ref: '#/components/parameters/AppVersionQuery'
- $ref: '#/components/parameters/UserAgentHeader'
requestBody:
content:
application/json:
examples:
tv_episode_stranger_things:
summary: TV episode match — Stranger Things S01E03
value:
file: Stranger.Things.S01E03.1080p.WEB.x264.mkv
movie_inception:
summary: Movie match — Inception 2010
value:
file: Inception.2010.1080p.BluRay.x264.mkv
movie_path_form:
summary: Path form — /Movies/.../file.mkv
value:
file: /Movies/The Matrix (1999)/The.Matrix.1999.BluRay.mkv
anime_episode_demon_slayer:
summary: >-
Anime episode — folds under type:"episode" (show.ids carries
mal, anidb, anilist, etc.)
value:
file: Kimetsu.no.Yaiba.E01.1080p.mkv
multipart_second_episode:
summary: Multipart filename — part=2 selects the second episode
value:
file: Were.The.Fugawis.S01E01E02.WS.DSR.x264-NY2.mkv
part: 2
legacy_capital_File_alias:
summary: Legacy `File` (capital F) alias — accepted server-side
value:
File: The.Office.S04E01.HDTV.x264-LOL.mkv
no_match_returns_empty_array:
summary: Parser ran but no match — empty array (NOT 404)
value:
file: ZZZ_no_such_show_QQQ_S99E99.mkv
empty_body_returns_null:
summary: Empty request body or missing `file` — null (NOT 400)
value: {}
schema:
type: object
required:
- file
properties:
file:
type: string
description: >-
Filename or path (with folders) to match against the Simkl
catalog. Both bare filenames and `/path/to/show/SxxEyy.mkv`
style paths are accepted. The alias `File` (capital F) is
also accepted for legacy clients.
examples:
- Were.The.Fugawis.S01E01E02.WS.DSR.x264-NY2.mkv
- /series/The Office/Season 4/The Office [401] Fun Run.avi
part:
type: integer
minimum: 1
description: >-
For multi-part filenames (e.g. `S01E01E02` = two episodes in
one file), the 1-based part index you want metadata for.
Default `1`.
example: 1
hash:
type: string
description: >-
Optional file hash for additional disambiguation. Pass
through if your scrobble integration computes one; safe to
omit.
process:
type: string
description: >-
Optional pre-processing hint for the filename parser. Most
clients can omit.
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/SearchByFileEpisodeMatch'
- $ref: '#/components/schemas/SearchByFileShowMatch'
- $ref: '#/components/schemas/SearchByFileMovieMatch'
- type: array
maxItems: 0
description: Empty array — parser ran but found no match.
- type: 'null'
description: Null — request body was empty or missing `file`.
discriminator:
propertyName: type
mapping:
episode:
$ref: '#/components/schemas/SearchByFileEpisodeMatch'
show:
$ref: '#/components/schemas/SearchByFileShowMatch'
movie:
$ref: '#/components/schemas/SearchByFileMovieMatch'
examples:
tv_episode_stranger_things:
summary: TV episode match — Stranger Things S01E03
value:
type: episode
episode:
title: 'Chapter Three: Holly, Jolly'
season: 1
episode: 3
multipart: false
ids:
simkl: 1865356
show:
title: Stranger Things
year: 2016
ids:
simkl: 548312
tvdbslug: stranger-things
tmdbtv: '66732'
imdb: tt4574334
trakttvslug: stranger-things
tvdb: '305288'
movie_inception:
summary: Movie match — Inception 2010
value:
type: movie
movie:
title: Inception
year: 2010
ids:
simkl: 472214
imdb: tt1375666
letterslug: inception
tvdbmslug: inception
tvdbm: '113'
boxd: 1skk
traktmslug: inception-2010
moviedb: '27205'
movie_path_form:
summary: Path form — /Movies/.../file.mkv
value:
type: movie
movie:
title: The Matrix
year: 1999
ids:
simkl: 53992
imdb: tt0133093
letterslug: the-matrix
tvdbmslug: the-matrix
tvdbm: '169'
boxd: 2a1m
traktmslug: the-matrix-1999
moviedb: '603'
anime_episode_demon_slayer:
summary: >-
Anime episode — folds under type:"episode" (show.ids carries
mal, anidb, anilist, etc.)
value:
type: episode
episode:
title: Cruelty
season: 1
episode: 1
multipart: false
ids:
simkl: 4170591
show:
title: Kimetsu no Yaiba
year: 2019
ids:
simkl: 831411
crunchyroll: GY5P48XEY
tmdbtv: '85937'
mal: '38000'
imdb: tt9335498
tvdbslug: demon-slayer-kimetsu-no-yaiba
anilist: '101922'
animeplanet: demon-slayer-kimetsu-no-yaiba
anisearch: '13658'
kitsu: '41370'
livechart: '3311'
trakttvslug: demon-slayer-kimetsu-no-yaiba
anidb: '14107'
tvdb: '348545'
multipart_second_episode:
summary: Multipart filename — part=2 selects the second episode
value:
type: episode
episode:
title: Fastest and Furious
season: 1
episode: 2
multipart: false
ids:
simkl: 967218
show:
title: We're the Fugawis
year: 2013
ids:
simkl: 43283
tmdbtv: '57690'
tvdbslug: were-the-fugawis
imdb: tt3108490
trakttvslug: we-re-the-fugawis-2013
tvdb: '272581'
legacy_capital_File_alias:
summary: Legacy `File` (capital F) alias — accepted server-side
value:
type: show
show:
title: The Office
year: 2005
ids:
simkl: 39823
imdb: tt0386676
tmdbtv: '2316'
tvdbslug: the-office-us
tvdb: '73244'
no_match_returns_empty_array:
summary: Parser ran but no match — empty array (NOT 404)
value: []
empty_body_returns_null:
summary: Empty request body or missing `file` — null (NOT 400)
value: null
'412':
$ref: '#/components/responses/ClientIdFailed'
'500':
$ref: '#/components/responses/ServerError'
security:
- clientId: []
x-codeSamples:
- lang: Shell
label: tv_episode_stranger_things
source: |-
curl -X POST -H "User-Agent: my-app-name/1.0" \
-H "Content-Type: application/json" \
-d '{"file":"Stranger.Things.S01E03.1080p.WEB.x264.mkv"}' \
"https://api.simkl.com/search/file?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
- lang: Shell
label: movie_inception
source: |-
curl -X POST -H "User-Agent: my-app-name/1.0" \
-H "Content-Type: application/json" \
-d '{"file":"Inception.2010.1080p.BluRay.x264.mkv"}' \
"https://api.simkl.com/search/file?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
- lang: Shell
label: movie_path_form
source: |-
curl -X POST -H "User-Agent: my-app-name/1.0" \
-H "Content-Type: application/json" \
-d '{"file":"/Movies/The Matrix (1999)/The.Matrix.1999.BluRay.mkv"}' \
"https://api.simkl.com/search/file?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
- lang: Shell
label: anime_episode_demon_slayer
source: |-
curl -X POST -H "User-Agent: my-app-name/1.0" \
-H "Content-Type: application/json" \
-d '{"file":"Kimetsu.no.Yaiba.E01.1080p.mkv"}' \
"https://api.simkl.com/search/file?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
- lang: Shell
label: multipart_second_episode
source: |-
curl -X POST -H "User-Agent: my-app-name/1.0" \
-H "Content-Type: application/json" \
-d '{"file":"Were.The.Fugawis.S01E01E02.WS.DSR.x264-NY2.mkv","part":2}' \
"https://api.simkl.com/search/file?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
- lang: Shell
label: legacy_capital_File_alias
source: |-
curl -X POST -H "User-Agent: my-app-name/1.0" \
-H "Content-Type: application/json" \
-d '{"File":"The.Office.S04E01.HDTV.x264-LOL.mkv"}' \
"https://api.simkl.com/search/file?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
- lang: Shell
label: no_match_returns_empty_array
source: |-
curl -X POST -H "User-Agent: my-app-name/1.0" \
-H "Content-Type: application/json" \
-d '{"file":"ZZZ_no_such_show_QQQ_S99E99.mkv"}' \
"https://api.simkl.com/search/file?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
- lang: Shell
label: empty_body_returns_null
source: |-
curl -X POST -H "User-Agent: my-app-name/1.0" \
-H "Content-Type: application/json" \
-d '{}' \
"https://api.simkl.com/search/file?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
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:
SearchByFileEpisodeMatch:
title: Episode match
type: object
description: >-
Filename matched a TV/anime episode. Carries both the show (parent) and
the specific matched episode.
properties:
type:
type: string
enum:
- episode
description: Discriminator — pinned to `"episode"` for this variant.
episode:
$ref: '#/components/schemas/SearchByFileEpisodeBlock'
show:
$ref: '#/components/schemas/SearchByFileShowBlock'
required:
- type
- episode
- show
SearchByFileShowMatch:
title: Show match
type: object
description: >-
Filename matched a show but no specific episode could be identified
(rare — usually parser confidence dropped).
properties:
type:
type: string
enum:
- show
description: Discriminator — pinned to `"show"` for this variant.
show:
$ref: '#/components/schemas/SearchByFileShowBlock'
required:
- type
- show
SearchByFileMovieMatch:
title: Movie match
type: object
description: Filename matched a movie.
properties:
type:
type: string
enum:
- movie
description: Discriminator — pinned to `"movie"` for this variant.
movie:
$ref: '#/components/schemas/SearchByFileMovieBlock'
required:
- type
- movie
SearchByFileEpisodeBlock:
type: object
description: 'Matched episode metadata. Present only on `type: "episode"` responses.'
properties:
title:
type: string
description: Episode title.
season:
type: integer
description: Season number.
episode:
type: integer
description: Episode number within the season.
multipart:
type: boolean
description: >-
`true` when the input filename was multi-part and `part > 1`
selected this episode.
ids:
$ref: '#/components/schemas/SearchByFileEpisodeIds'
required:
- title
- season
- episode
- multipart
- ids
SearchByFileShowBlock:
type: object
description: Show metadata (TV or anime).
properties:
title:
type: string
year:
type: integer
ids:
$ref: '#/components/schemas/SearchByFileShowIds'
required:
- title
- year
- ids
SearchByFileMovieBlock:
type: object
description: Movie metadata.
properties:
title:
type: string
year:
type: integer
ids:
$ref: '#/components/schemas/SearchByFileShowIds'
required:
- title
- year
- 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
SearchByFileEpisodeIds:
type: object
description: >-
Episode IDs — just the Simkl episode ID. Cross-source IDs sit on the
parent show.
properties:
simkl:
type: integer
description: >-
Simkl episode ID. Use with `/tv/episodes/{id}` or
`/anime/episodes/{id}`.
required:
- simkl
SearchByFileShowIds:
type: object
additionalProperties: true
description: >-
Show / movie IDs returned by Simkl's link database. `simkl` is always
present; other keys appear when a link record exists. Common keys:
`imdb`, `tmdb`/`tmdbtv`, `tvdb`/`tvdbslug`, `trakttvslug`/`traktmslug`,
plus anime-specific `mal`, `anidb`, `anilist`, `kitsu`, `crunchyroll`,
`animeplanet`, `anisearch`, `livechart`. Movies also see `letterslug`
(Letterboxd), `tvdbm`/`tvdbmslug`, `boxd`, `moviedb`. See [Supported ID
keys](/conventions/standard-media-objects#supported-id-keys).
properties:
simkl:
type: integer
description: Canonical Simkl ID.
required:
- simkl
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
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
````