> ## 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.
# Search by text query
> Full-text search over the Simkl catalog. Pick a type (`movie`, `tv`, or `anime`) and pass a search term like `john wick` or `john wick 2014`.
**Heads up: `movie` becomes `"movies"` in the response.**
You call `/search/movie` (no `s`) but each item in the response has `endpoint_type: "movies"` (with an `s`). TV and anime don't change.
| You call | Each item's `endpoint_type` is |
|---|---|
| `/search/movie` | `"movies"` ← note the extra `s` |
| `/search/tv` | `"tv"` |
| `/search/anime` | `"anime"` |
Every item in a single response has the same `endpoint_type` — you never get a mixed list back.
#### Path parameter
| Param | Values |
|---|---|
| `type` | `movie`, `tv`, `anime` |
#### Query parameters
| Param | Default | Notes |
|---|---|---|
| `q` | — | **Required.** Text query (matches `title` and `all_titles[]`). For external-ID lookups (IMDb / TMDB / TVDB / etc.), use [`/redirect`](/api-reference/redirect) or [`/search/id`](/api-reference/simkl/search-by-id) instead. |
| `page` | `1` | Hard-capped server-side at `20`. Higher values silently clamp. |
| `limit` | `10` | Hard-capped server-side at `50`. Higher values silently clamp. |
| `extended` | `simple` | `full` adds `all_titles[]`, `url`, `ep_count` (TV/anime), `rank` (nullable), `status` (TV/anime), and a `ratings` block. |
Returns paginated results with `X-Pagination-*` headers — see [Pagination](/api-reference/pagination) for the standard paginator pattern.
#### Per-item fields by mode
| Field | `simple` | `extended=full` | Notes |
|---|---|---|---|
| `title` | ✓ | ✓ | Display title in the user's locale. |
| `title_en` | — | — | **Anime only**, optional even on anime — only when an English-localized title is on file. |
| `title_romaji` | anime only | anime only | **Anime only**, always present on anime items. Currently mirrors `title` for the romaji slot. |
| `year` | ✓ | ✓ | Premiere year. |
| `endpoint_type` | ✓ | ✓ | `"movies"` / `"tv"` / `"anime"`. Same value on every item in one response. |
| `type` | anime only | anime only | **Anime only**: `tv`, `movie`, `ova`, `ona`, `special`, `music`. |
| `poster` | ✓ | ✓ | Image path fragment — see [Image conventions](/conventions/images) for the full URL pattern (`https://wsrv.nl/?url=https://simkl.in/posters/{poster}_m.webp&q=90`). |
| `ids` | ✓ | ✓ | `{ simkl_id, slug, tmdb? }`. `tmdb` only present when a TMDB link is on file. |
| `all_titles` | — | movies/anime | Aliases / localized variants. Anime sees the most entries. TV items typically don't carry this even on `extended=full`. |
| `url` | — | ✓ | Relative simkl.com URL (with slug). |
| `ep_count` | — | TV/anime | Total episode count when known. |
| `rank` | — | ✓ | Simkl popularity rank. **Nullable** — see below. |
| `status` | — | TV/anime | Closed enum: `tba`, `ended`, `airing`. |
| `ratings.simkl` | — | ✓ | `{ rating, votes }` — only present when votes > 0. |
| `ratings.imdb` | — | ✓ | `{ rating, votes }` — only present when an IMDb rating record exists. |
| `ratings.mal` | — | anime only | `{ rating, votes, rank }` — anime only, only when a MAL record exists. |
#### Nulls — what they mean
| Field | When null | Type |
|---|---|---|
| `rank` | Item not yet ranked, or rank value ≥ 999999 sentinel | [Type 4](/conventions/null-values#type-4) |
| `ep_count` | TV/anime item with no episode count on file yet | [Type 4](/conventions/null-values#type-4) |
| `poster` | No poster image on file | [Type 4](/conventions/null-values#type-4) |
#### Error responses
| Status | When |
|---|---|
| `412 client_id_failed` | Missing or invalid `client_id` |
| `500` | Server error |
No `400` — invalid `page` / `limit` silently clamp to the server caps. No `404` — empty result is `[]` with status `200`.
**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 /search/{type}
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/{type}:
get:
tags:
- Search
summary: Search by text query
description: >
Full-text search over the Simkl catalog. Pick a type (`movie`, `tv`, or
`anime`) and pass a search term like `john wick` or `john wick 2014`.
**Heads up: `movie` becomes `"movies"` in the response.**
You call `/search/movie` (no `s`) but each item in the response has
`endpoint_type: "movies"` (with an `s`). TV and anime don't change.
| You call | Each item's `endpoint_type` is |
|---|---|
| `/search/movie` | `"movies"` ← note the extra `s` |
| `/search/tv` | `"tv"` |
| `/search/anime` | `"anime"` |
Every item in a single response has the same `endpoint_type` — you never
get a mixed list back.
#### Path parameter
| Param | Values |
|---|---|
| `type` | `movie`, `tv`, `anime` |
#### Query parameters
| Param | Default | Notes |
|---|---|---|
| `q` | — | **Required.** Text query (matches `title` and
`all_titles[]`). For external-ID lookups (IMDb / TMDB / TVDB / etc.),
use [`/redirect`](/api-reference/redirect) or
[`/search/id`](/api-reference/simkl/search-by-id) instead. |
| `page` | `1` | Hard-capped server-side at `20`. Higher values silently
clamp. |
| `limit` | `10` | Hard-capped server-side at `50`. Higher values
silently clamp. |
| `extended` | `simple` | `full` adds `all_titles[]`, `url`, `ep_count`
(TV/anime), `rank` (nullable), `status` (TV/anime), and a `ratings`
block. |
Returns paginated results with `X-Pagination-*` headers — see
[Pagination](/api-reference/pagination) for the standard paginator
pattern.
#### Per-item fields by mode
| Field | `simple` | `extended=full` | Notes |
|---|---|---|---|
| `title` | ✓ | ✓ | Display title in the user's locale. |
| `title_en` | — | — | **Anime only**, optional even on anime — only
when an English-localized title is on file. |
| `title_romaji` | anime only | anime only | **Anime only**, always
present on anime items. Currently mirrors `title` for the romaji slot. |
| `year` | ✓ | ✓ | Premiere year. |
| `endpoint_type` | ✓ | ✓ | `"movies"` / `"tv"` / `"anime"`. Same value
on every item in one response. |
| `type` | anime only | anime only | **Anime only**: `tv`, `movie`,
`ova`, `ona`, `special`, `music`. |
| `poster` | ✓ | ✓ | Image path fragment — see [Image
conventions](/conventions/images) for the full URL pattern
(`https://wsrv.nl/?url=https://simkl.in/posters/{poster}_m.webp&q=90`).
|
| `ids` | ✓ | ✓ | `{ simkl_id, slug, tmdb? }`. `tmdb` only present when
a TMDB link is on file. |
| `all_titles` | — | movies/anime | Aliases / localized variants. Anime
sees the most entries. TV items typically don't carry this even on
`extended=full`. |
| `url` | — | ✓ | Relative simkl.com URL (with slug). |
| `ep_count` | — | TV/anime | Total episode count when known. |
| `rank` | — | ✓ | Simkl popularity rank. **Nullable** — see below. |
| `status` | — | TV/anime | Closed enum: `tba`, `ended`, `airing`. |
| `ratings.simkl` | — | ✓ | `{ rating, votes }` — only present when
votes > 0. |
| `ratings.imdb` | — | ✓ | `{ rating, votes }` — only present when an
IMDb rating record exists. |
| `ratings.mal` | — | anime only | `{ rating, votes, rank }` — anime
only, only when a MAL record exists. |
#### Nulls — what they mean
| Field | When null | Type |
|---|---|---|
| `rank` | Item not yet ranked, or rank value ≥ 999999 sentinel | [Type
4](/conventions/null-values#type-4) |
| `ep_count` | TV/anime item with no episode count on file yet | [Type
4](/conventions/null-values#type-4) |
| `poster` | No poster image on file | [Type
4](/conventions/null-values#type-4) |
#### Error responses
| Status | When |
|---|---|
| `412 client_id_failed` | Missing or invalid `client_id` |
| `500` | Server error |
No `400` — invalid `page` / `limit` silently clamp to the server caps.
No `404` — empty result is `[]` with status `200`.
**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-search-type
parameters:
- name: type
in: path
description: Search type.
required: true
schema:
type: string
enum:
- tv
- anime
- movie
example: movie
- name: q
in: query
description: >-
Required. The search term — matches `title` and `all_titles[]`
across the chosen catalog (movies / TV / anime).
Examples: `john wick`, `john wick 2014`, `breaking bad`, `cowboy
bebop`.
required: true
schema:
type: string
example: john wick
- $ref: '#/components/parameters/PageParam'
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 50
default: 10
description: Items per page. Capped at 50.
- name: extended
in: query
required: false
schema:
type: string
enum:
- simple
- full
description: '`full` adds overview, ratings, and genres to each match.'
- $ref: '#/components/parameters/ClientIdQuery'
- $ref: '#/components/parameters/AppNameQuery'
- $ref: '#/components/parameters/AppVersionQuery'
- $ref: '#/components/parameters/UserAgentHeader'
responses:
'200':
description: OK
headers:
X-Pagination-Page:
schema:
type: string
X-Pagination-Limit:
schema:
type: string
X-Pagination-Page-Count:
schema:
type: string
X-Pagination-Item-Count:
schema:
type: string
content:
application/json:
schema:
type: array
description: >-
Search results — always a single array. The `endpoint_type` on
each item mirrors the path's `:type` (in its plural form) and
is constant within one response, so use it as the
discriminator.
items:
oneOf:
- $ref: '#/components/schemas/SearchByTextMovieItem'
- $ref: '#/components/schemas/SearchByTextTVItem'
- $ref: '#/components/schemas/SearchByTextAnimeItem'
discriminator:
propertyName: endpoint_type
mapping:
movies:
$ref: '#/components/schemas/SearchByTextMovieItem'
tv:
$ref: '#/components/schemas/SearchByTextTVItem'
anime:
$ref: '#/components/schemas/SearchByTextAnimeItem'
examples:
movie_simple:
summary: Movies (simple) — q=john wick, limit=2
value:
- title: John Wick
year: 2014
endpoint_type: movies
poster: 30/3002370dbc564e5d8
ids:
simkl_id: 342994
slug: john-wick
tmdb: '245891'
- title: 'John Wick: Chapter 4'
year: 2023
endpoint_type: movies
poster: 13/13693559ce304eb6f6
ids:
simkl_id: 1098350
slug: john-wick-chapter-4
tmdb: '603692'
movie_extended:
summary: Movies (extended=full) — q=john wick, limit=1
value:
- title: John Wick
year: 2014
endpoint_type: movies
poster: 30/3002370dbc564e5d8
all_titles:
- John Wick
- Джон Уик
- 존 윅
- ジョン・ウィック
- 'John Wick: Chapter 1'
url: /movies/342994/john-wick
rank: 2429
ratings:
simkl:
rating: 7.8
votes: 8286
imdb:
rating: 7.5
votes: 828209
ids:
simkl_id: 342994
slug: john-wick
tmdb: '245891'
tv_simple:
summary: TV (simple) — q=breaking bad, limit=2
value:
- title: Breaking Bad
year: 2008
endpoint_type: tv
poster: 97/978343d5161a724
ids:
simkl_id: 11121
slug: breaking-bad
tmdb: '1396'
- title: Breaking Bad Fortune Teller
year: 2016
endpoint_type: tv
poster: 14/14429153ab8d3bf317
ids:
simkl_id: 1838137
slug: breaking-bad-fortune-teller
tmdb: '232533'
tv_extended:
summary: >-
TV (extended=full) — q=breaking bad, limit=2 (second item
has rank: null)
value:
- title: Breaking Bad
year: 2008
endpoint_type: tv
poster: 97/978343d5161a724
url: /tv/11121/breaking-bad
ep_count: 62
rank: 2
status: ended
ratings:
simkl:
rating: 9.2
votes: 11657
imdb:
rating: 9.5
votes: 2615761
ids:
simkl_id: 11121
slug: breaking-bad
tmdb: '1396'
- title: Breaking Bad Fortune Teller
year: 2016
endpoint_type: tv
poster: 14/14429153ab8d3bf317
url: /tv/1838137/breaking-bad-fortune-teller
ep_count: 40
rank: null
status: ended
ids:
simkl_id: 1838137
slug: breaking-bad-fortune-teller
tmdb: '232533'
anime_simple:
summary: Anime (simple) — q=cowboy bebop, limit=2
value:
- title: Cowboy Bebop
title_romaji: Cowboy Bebop
year: 1998
endpoint_type: anime
type: tv
poster: 36/36842f1bceb6b39
ids:
simkl_id: 37089
slug: cowboy-bebop
tmdb: '30991'
- title: 'Cowboy Bebop: Tengoku no Tobira'
title_en: 'Cowboy Bebop: Knockin'' on Heaven''s Door'
title_romaji: 'Cowboy Bebop: Tengoku no Tobira'
year: 2001
endpoint_type: anime
type: movie
poster: 11/113551180c5f0e82c1
ids:
simkl_id: 38382
slug: cowboy-bebop-tengoku-no-tobira
anime_extended:
summary: >-
Anime (extended=full) — q=cowboy bebop, limit=1 (ratings.mal
carries rank)
value:
- title: Cowboy Bebop
title_romaji: Cowboy Bebop
year: 1998
endpoint_type: anime
type: tv
poster: 36/36842f1bceb6b39
all_titles:
- Cowboy Bebop
- カウボーイビバップ
- 星际牛仔
- Bebop
url: /anime/37089/cowboy-bebop
ep_count: 26
rank: 46
status: ended
ratings:
simkl:
rating: 8.6
votes: 4611
imdb:
rating: 8.8
votes: 27847
mal:
rating: 8.8
votes: 1062607
rank: 49
ids:
simkl_id: 37089
slug: cowboy-bebop
tmdb: '30991'
empty_no_results:
summary: No results — empty array, status 200
value: []
'412':
$ref: '#/components/responses/ClientIdFailed'
'500':
$ref: '#/components/responses/ServerError'
security:
- clientId: []
x-codeSamples:
- lang: Shell
label: movie_simple
source: |-
curl -H "User-Agent: my-app-name/1.0" \
"https://api.simkl.com/search/movie?q=john+wick&limit=2&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
- lang: Shell
label: movie_extended
source: |-
curl -H "User-Agent: my-app-name/1.0" \
"https://api.simkl.com/search/movie?q=john+wick&extended=full&limit=1&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
- lang: Shell
label: tv_simple
source: |-
curl -H "User-Agent: my-app-name/1.0" \
"https://api.simkl.com/search/tv?q=breaking+bad&limit=2&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
- lang: Shell
label: tv_extended
source: |-
curl -H "User-Agent: my-app-name/1.0" \
"https://api.simkl.com/search/tv?q=breaking+bad&extended=full&limit=2&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
- lang: Shell
label: anime_simple
source: |-
curl -H "User-Agent: my-app-name/1.0" \
"https://api.simkl.com/search/anime?q=cowboy+bebop&limit=2&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
- lang: Shell
label: anime_extended
source: |-
curl -H "User-Agent: my-app-name/1.0" \
"https://api.simkl.com/search/anime?q=cowboy+bebop&extended=full&limit=1&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
- lang: Shell
label: empty_no_results
source: |-
curl -H "User-Agent: my-app-name/1.0" \
"https://api.simkl.com/search/movie?q=zzznoresultzzz&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
components:
parameters:
PageParam:
name: page
in: query
required: false
description: Page number for paginated endpoints (1-based).
schema:
type: integer
minimum: 1
default: 1
maximum: 20
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:
SearchByTextMovieItem:
title: Movie result
type: object
description: >-
One movie search result. `endpoint_type` is the constant `"movies"`
(plural even though the path is `/search/movie`). Extended fields
(`all_titles`, `url`, `rank`, `ratings`) only appear when the call
includes `extended=full`.
properties:
title:
type: string
year:
type: integer
endpoint_type:
type: string
enum:
- movies
description: Constant for movie search results.
poster:
type:
- string
- 'null'
description: >-
Image path fragment. Combine with the prefixes in [Image
conventions](/conventions/images) — for example
`https://wsrv.nl/?url=https://simkl.in/posters/{poster}_m.webp&q=90`.
**Type 4 null** — `null` when no poster image is on file. See [Null
and missing values](/conventions/null-values).
ids:
$ref: '#/components/schemas/SearchByTextIds'
all_titles:
type: array
items:
type: string
description: >-
Aliases / localized variants. Extended mode only, and only when the
catalog has more than one title.
url:
type: string
description: Relative simkl.com URL. Extended mode only.
rank:
type:
- integer
- 'null'
description: >-
Simkl popularity rank. **Type 4 null** — `null` when the item is not
yet ranked or the catalog sentinel value (≥ 999999) is present. See
[Null and missing values](/conventions/null-values).
ratings:
type: object
description: >-
External-source ratings block. Each sub-key is present only when the
corresponding rating record exists.
properties:
simkl:
$ref: '#/components/schemas/ExternalRating'
imdb:
$ref: '#/components/schemas/ExternalRating'
required:
- title
- year
- endpoint_type
- poster
- ids
SearchByTextTVItem:
title: TV result
type: object
description: >-
One TV search result. `endpoint_type` is the constant `"tv"`. Extended
fields (`url`, `ep_count`, `rank`, `status`, `ratings`) only appear when
the call includes `extended=full`.
properties:
title:
type: string
year:
type: integer
endpoint_type:
type: string
enum:
- tv
description: Constant for TV search results.
poster:
type:
- string
- 'null'
description: >-
Image path fragment. Combine with the prefixes in [Image
conventions](/conventions/images) — for example
`https://wsrv.nl/?url=https://simkl.in/posters/{poster}_m.webp&q=90`.
**Type 4 null** — `null` when no poster image is on file. See [Null
and missing values](/conventions/null-values).
ids:
$ref: '#/components/schemas/SearchByTextIds'
url:
type: string
description: Relative simkl.com URL. Extended mode only.
ep_count:
type:
- integer
- 'null'
description: >-
Total episode count. **Type 4 null** — `null` when no count is on
file yet. See [Null and missing values](/conventions/null-values).
rank:
type:
- integer
- 'null'
description: >-
Simkl popularity rank. **Type 4 null** — `null` when the item is not
yet ranked or the catalog sentinel value (≥ 999999) is present. See
[Null and missing values](/conventions/null-values).
status:
type: string
enum:
- tba
- ended
- airing
description: Airing status (extended mode only).
ratings:
type: object
description: >-
External-source ratings block. Each sub-key is present only when the
corresponding rating record exists.
properties:
simkl:
$ref: '#/components/schemas/ExternalRating'
imdb:
$ref: '#/components/schemas/ExternalRating'
required:
- title
- year
- endpoint_type
- poster
- ids
SearchByTextAnimeItem:
title: Anime result
type: object
description: >-
One anime search result. `endpoint_type` is the constant `"anime"`.
`title_romaji` and `type` are always present on anime items; `title_en`
is only present when an English-localized title is on file. Extended
fields (`all_titles`, `url`, `ep_count`, `rank`, `status`, `ratings`)
only appear when the call includes `extended=full`.
properties:
title:
type: string
title_en:
type: string
description: >-
English-localized title. Optional even on anime — only present when
one is on file.
title_romaji:
type: string
description: >-
Romaji title slot — currently mirrors `title` for every anime item.
Always present on anime results.
year:
type: integer
endpoint_type:
type: string
enum:
- anime
description: Constant for anime search results.
type:
type: string
enum:
- tv
- movie
- ova
- ona
- special
- music
description: Anime catalog type. Always lowercase.
poster:
type:
- string
- 'null'
description: >-
Image path fragment. Combine with the prefixes in [Image
conventions](/conventions/images) — for example
`https://wsrv.nl/?url=https://simkl.in/posters/{poster}_m.webp&q=90`.
**Type 4 null** — `null` when no poster image is on file. See [Null
and missing values](/conventions/null-values).
ids:
$ref: '#/components/schemas/SearchByTextIds'
all_titles:
type: array
items:
type: string
description: >-
Aliases / localized variants. Extended mode only, and only when the
catalog has more than one title.
url:
type: string
description: Relative simkl.com URL. Extended mode only.
ep_count:
type:
- integer
- 'null'
description: >-
Total episode count. **Type 4 null** — `null` when no count is on
file yet. See [Null and missing values](/conventions/null-values).
rank:
type:
- integer
- 'null'
description: >-
Simkl popularity rank. **Type 4 null** — `null` when the item is not
yet ranked or the catalog sentinel value (≥ 999999) is present. See
[Null and missing values](/conventions/null-values).
status:
type: string
enum:
- tba
- ended
- airing
description: Airing status (extended mode only).
ratings:
type: object
description: >-
External-source ratings block. Each sub-key is present only when the
corresponding rating record exists. `mal` carries an extra `rank`
field — see RankedExternalRating.
properties:
simkl:
$ref: '#/components/schemas/ExternalRating'
imdb:
$ref: '#/components/schemas/ExternalRating'
mal:
$ref: '#/components/schemas/RankedExternalRating'
required:
- title
- title_romaji
- year
- endpoint_type
- type
- poster
- ids
SearchByTextIds:
type: object
description: >-
ID block returned on every search result item. `simkl_id` and `slug` are
always present; `tmdb` is only present when a TMDB link record exists
for the title.
properties:
simkl_id:
type: integer
description: Canonical Simkl ID for the title.
slug:
type: string
description: >-
URL slug parsed from the simkl.com canonical URL (everything after
the last `/`). Response-only — never send on requests.
tmdb:
type: string
description: >-
TMDB ID, when a link record exists. For TV/anime this is the TMDB TV
ID; for movies it's the TMDB movie ID.
required:
- simkl_id
- slug
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.
RankedExternalRating:
allOf:
- $ref: '#/components/schemas/ExternalRating'
- type: object
properties:
rank:
type: integer
description: Rank in the source's ordering (lower = better).
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
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
````