> ## 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.
# Community ratings for items in the user's watchlist
>
**This endpoint returns Simkl's *community* ratings** (the public average + droprate + vote counts) for every item in the user's watchlist — not the user's own 1-10 scores. If you want **the user's own ratings**, every [`GET /sync/all-items`](/api-reference/simkl/get-all-items) response already carries `user_rating` (1-10 or `null`) per item — filter that client-side. For server-side filtering by score (e.g. "give me only items I rated 9 or 10"), see [`GET /sync/ratings/:type/:rating`](/api-reference/simkl/get-user-ratings).
Bulk Simkl-rating lookup for items across the user's watchlist. Useful for ranking the user's library against community ratings (e.g. "what's the highest-community-rated movie in my Plan-to-Watch?").
Returns an array of `{id, simkl: {rating, votes, droprate}}` for every item in the requested watchlist statuses. Pair with [`GET /movies/{id}`](/api-reference/simkl/get-movie) / [`GET /tv/{id}`](/api-reference/simkl/get-tv-show) / [`GET /anime/{id}`](/api-reference/simkl/get-anime) (Cloudflare-cached) when you need the full record for any individual item.
#### Path
| Segment | Values | Notes |
|---|---|---|
| `type` | `movies`, `tv`, `anime`, `all` | Required. Use `/ratings/all` to get every type in one response. |
#### Query
| Param | Required | Notes |
|---|---|---|
| `user_watchlist` | yes | Comma-separated list of watchlist statuses to include. Any of `watching`, `plantowatch`, `hold`, `completed`, `dropped`. Use `1` (or any non-empty value) as a shorthand for "all statuses". Without this param the request silently falls through to a different code path and returns `200 null` — always supply it. |
| `fields` | no | Comma-separated extra blocks to include alongside the default `simkl` block. See the *Fields values* table below. |
#### Fields values
| `fields` value | Adds |
|---|---|
| `simkl` *(default)* | `simkl: {rating, votes, droprate}` per item. |
| `ext` | `imdb: {rating, votes}` and/or `mal: {rating, votes, rank}` (only the providers Simkl has on file for the title). |
| `rank` | `rank` integer — Simkl's catalog rank for the item. |
| `release_status` | Human-readable release status (e.g. `Ended`, `Continuing`). |
| `year` | `release_year` integer. |
| `link` | Canonical Simkl URL for the item. |
Combine multiple with commas: `fields=simkl,ext,year,rank`. Unknown values (including `reactions` and `has_trailer`, which are valid on the hidden single-item rating endpoint but **not** here) are silently ignored.
#### Auth
Requires `Authorization: Bearer ` plus the standard `client_id` / `app-name` / `app-version` URL params.
For the user's **own** ratings (the 1-10 scores they've assigned), use [`GET /sync/ratings/:type/:rating`](/api-reference/simkl/get-user-ratings) instead — that's the user-rated-by-them endpoint, this one is community-rating-of-everything-in-their-list.
**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 /ratings/{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:
/ratings/{type}:
get:
tags:
- Ratings
summary: Community ratings for items in the user's watchlist
description: >-
**This endpoint returns Simkl's *community* ratings** (the public
average + droprate + vote counts) for every item in the user's watchlist
— not the user's own 1-10 scores. If you want **the user's own
ratings**, every [`GET
/sync/all-items`](/api-reference/simkl/get-all-items) response already
carries `user_rating` (1-10 or `null`) per item — filter that
client-side. For server-side filtering by score (e.g. "give me only
items I rated 9 or 10"), see [`GET
/sync/ratings/:type/:rating`](/api-reference/simkl/get-user-ratings).
Bulk Simkl-rating lookup for items across the user's watchlist. Useful
for ranking the user's library against community ratings (e.g. "what's
the highest-community-rated movie in my Plan-to-Watch?").
Returns an array of `{id, simkl: {rating, votes, droprate}}` for every
item in the requested watchlist statuses. Pair with [`GET
/movies/{id}`](/api-reference/simkl/get-movie) / [`GET
/tv/{id}`](/api-reference/simkl/get-tv-show) / [`GET
/anime/{id}`](/api-reference/simkl/get-anime) (Cloudflare-cached) when
you need the full record for any individual item.
#### Path
| Segment | Values | Notes |
|---|---|---|
| `type` | `movies`, `tv`, `anime`, `all` | Required. Use
`/ratings/all` to get every type in one response. |
#### Query
| Param | Required | Notes |
|---|---|---|
| `user_watchlist` | yes | Comma-separated list of watchlist statuses to
include. Any of `watching`, `plantowatch`, `hold`, `completed`,
`dropped`. Use `1` (or any non-empty value) as a shorthand for "all
statuses". Without this param the request silently falls through to a
different code path and returns `200 null` — always supply it. |
| `fields` | no | Comma-separated extra blocks to include alongside the
default `simkl` block. See the *Fields values* table below. |
#### Fields values
| `fields` value | Adds |
|---|---|
| `simkl` *(default)* | `simkl: {rating, votes, droprate}` per item. |
| `ext` | `imdb: {rating, votes}` and/or `mal: {rating,
votes, rank}` (only the providers Simkl has on file for the title). |
| `rank` | `rank` integer — Simkl's catalog rank for the
item. |
| `release_status` | Human-readable release status (e.g. `Ended`,
`Continuing`). |
| `year` | `release_year` integer. |
| `link` | Canonical Simkl URL for the item. |
Combine multiple with commas: `fields=simkl,ext,year,rank`. Unknown
values (including `reactions` and `has_trailer`, which are valid on the
hidden single-item rating endpoint but **not** here) are silently
ignored.
#### Auth
Requires `Authorization: Bearer ` plus the standard
`client_id` / `app-name` / `app-version` URL params.
For the user's **own** ratings (the 1-10 scores they've assigned), use
[`GET
/sync/ratings/:type/:rating`](/api-reference/simkl/get-user-ratings)
instead — that's the user-rated-by-them endpoint, this one is
community-rating-of-everything-in-their-list.
**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-ratings-type
parameters:
- name: type
in: path
description: >-
Media-type slice. Use `all` to fetch every type in one response —
this is the canonical "I don't care which type" form. The path
segment is required because OpenAPI 3.1 does not permit optional
path parameters.
schema:
type: string
enum:
- movies
- tv
- anime
- all
example: all
required: true
examples:
default_all_types:
summary: 'Default: every type, every status'
value: all
movies_watching_returns_null:
summary: >-
Sentinel: movies+watching returns null (movies have no
`watching` bucket)
value: movies
tv_plan_to_watch:
summary: TV shows the user plans to watch
value: tv
anime_completed:
summary: Anime the user has finished
value: anime
active_library_csv:
summary: 'Active library only (CSV: plantowatch + watching + completed)'
value: all
with_imdb_and_mal_ratings:
summary: Add external ratings (IMDb + MAL) via `fields=ext`
value: all
full_metadata_bundle:
summary: 'Full metadata: every optional field at once'
value: all
- name: user_watchlist
in: query
description: ''
required: true
schema:
type: string
default: all
enum:
- all
- watching
- plantowatch
- completed
- dropped
- hold
example: '1'
examples:
default_all_types:
summary: 'Default: every type, every status'
value: '1'
movies_watching_returns_null:
summary: >-
Sentinel: movies+watching returns null (movies have no
`watching` bucket)
value: watching
tv_plan_to_watch:
summary: TV shows the user plans to watch
value: plantowatch
anime_completed:
summary: Anime the user has finished
value: completed
active_library_csv:
summary: 'Active library only (CSV: plantowatch + watching + completed)'
value: plantowatch,watching,completed
with_imdb_and_mal_ratings:
summary: Add external ratings (IMDb + MAL) via `fields=ext`
value: '1'
full_metadata_bundle:
summary: 'Full metadata: every optional field at once'
value: '1'
- name: fields
in: query
description: >-
- A comma-separated list of additional fields to include in the
response.
- `simkl` – returns the Simkl rating and votes.
- `ext` – includes external ratings such as IMDB or MAL if available.
- `rank` – returns the rank within the Simkl service for that media type (movie, tv, anime).
- `release_status` – includes the release status of the item.
- `year` – includes the year of release.
- Example: `fields=rank,droprate,simkl,ext,year`
schema:
type: string
enum:
- simkl
- ext
- rank
- release_status
- year
- link
examples:
default_all_types:
summary: 'Default: every type, every status'
value: simkl
movies_watching_returns_null:
summary: >-
Sentinel: movies+watching returns null (movies have no
`watching` bucket)
value: simkl
tv_plan_to_watch:
summary: TV shows the user plans to watch
value: simkl
anime_completed:
summary: Anime the user has finished
value: simkl
active_library_csv:
summary: 'Active library only (CSV: plantowatch + watching + completed)'
value: simkl
with_imdb_and_mal_ratings:
summary: Add external ratings (IMDb + MAL) via `fields=ext`
value: simkl,ext
full_metadata_bundle:
summary: 'Full metadata: every optional field at once'
value: simkl,ext,year,rank,droprate,link,release_status
- $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:
type: array
items:
type: object
properties:
id:
type: number
type:
type: string
link:
type: string
release_status:
type: string
release_year:
type: number
rank:
type: number
simkl:
type: object
properties:
rating:
type: number
votes:
type: number
droprate:
type: string
imdb:
$ref: '#/components/schemas/ExternalRating'
mal:
$ref: '#/components/schemas/RankedExternalRating'
required:
- id
- type
- link
- release_status
- release_year
- rank
- simkl
example:
- id: 268470
type: movie
link: >-
https://simkl.com/movies/268470/tinker-bell-and-the-pirate-fairy
release_status: released
release_year: 2014
rank: 10628
simkl:
rating: 7.1
votes: 151
droprate: 1%
imdb:
rating: 6.6
votes: 15119
- id: 2331788
type: anime
link: >-
https://simkl.com/anime/2331788/kamonohashi-ron-no-kindan-suiri-2nd-season
release_status: ongoing
release_year: 2024
rank: 1561
simkl:
rating: 7
votes: 19
droprate: 3.9%
mal:
rating: 7.6
votes: 4132
rank: 1693
examples:
default_all_types:
summary: 'Default: every type, every status'
description: >-
`GET /ratings/all?user_watchlist=1`
The simplest call — `?user_watchlist=1` is shorthand for
"all five statuses". Each item carries the default `simkl:
{rating, votes, droprate}` block.
value:
- id: 297
type: tv
simkl:
rating: 7.4
votes: 717
droprate: 3%
- id: 1218
type: tv
simkl:
rating: 8.2
votes: 2207
droprate: 7.4%
- id: 1698
type: tv
simkl:
rating: 7.2
votes: 70
droprate: 5.1%
movies_watching_returns_null:
summary: >-
Sentinel: movies+watching returns null (movies have no
`watching` bucket)
description: >-
`GET /ratings/movies?user_watchlist=watching`
Per [list-status rules](/conventions/list-statuses), movies
skip `watching` and `hold`. Asking for them returns `200
null` (Type 3 — empty result) — this is normal, not an
error. Pinned here as a known-shape sentinel so client
parsers handle it cleanly.
value: null
tv_plan_to_watch:
summary: TV shows the user plans to watch
description: >-
`GET /ratings/tv?user_watchlist=plantowatch`
The classic "what should I watch next" use case — community
ratings for items in the user's Plan-to-Watch list, sortable
client-side by `simkl.rating` desc.
value:
- id: 297
simkl:
rating: 7.4
votes: 717
droprate: 3%
- id: 1218
simkl:
rating: 8.2
votes: 2207
droprate: 7.4%
- id: 1698
simkl:
rating: 7.2
votes: 70
droprate: 5.1%
anime_completed:
summary: Anime the user has finished
description: >-
`GET /ratings/anime?user_watchlist=completed`
Per-type, per-status filter. Useful for retrospective
analysis — how the user's completed library ranks against
the wider community.
value:
- id: 37089
simkl:
rating: 8.6
votes: 4606
droprate: 2.1%
- id: 439744
simkl:
rating: 8.6
votes: 9124
droprate: 0.4%
- id: 694485
simkl:
rating: 8.7
votes: 8150
droprate: 0.4%
active_library_csv:
summary: >-
Active library only (CSV: plantowatch + watching +
completed)
description: >-
`GET
/ratings/all?user_watchlist=plantowatch,watching,completed`
`user_watchlist` accepts a comma-separated list of statuses.
This combo is the active library — everything the user is
engaging with right now, excluding `hold` and `dropped`.
value:
- id: 297
type: tv
simkl:
rating: 7.4
votes: 717
droprate: 3%
- id: 1218
type: tv
simkl:
rating: 8.2
votes: 2207
droprate: 7.4%
- id: 1698
type: tv
simkl:
rating: 7.2
votes: 70
droprate: 5.1%
with_imdb_and_mal_ratings:
summary: Add external ratings (IMDb + MAL) via `fields=ext`
description: >-
`GET /ratings/all?user_watchlist=1&fields=simkl,ext`
`fields=ext` adds `imdb: {rating, votes}` and/or `mal:
{rating, votes, rank}` blocks per item — only the providers
Simkl has on file. Live-action titles typically carry `simkl
+ imdb`; modern anime carry `simkl + mal`; classic anime
sometimes carry all three.
value:
- id: 297
type: tv
simkl:
rating: 7.4
votes: 717
droprate: 3%
imdb:
rating: 7.2
votes: 98744
- id: 1218
type: tv
simkl:
rating: 8.2
votes: 2207
droprate: 7.4%
imdb:
rating: 8.6
votes: 468647
- id: 1698
type: tv
simkl:
rating: 7.2
votes: 70
droprate: 5.1%
imdb:
rating: 6.5
votes: 18350
full_metadata_bundle:
summary: 'Full metadata: every optional field at once'
description: >-
`GET
/ratings/all?user_watchlist=1&fields=simkl,ext,year,rank,droprate,link,release_status`
Every supported `fields=` value at once: `simkl`, `ext`
(imdb/mal), `year` (release_year), `rank`, `droprate`,
`link` (canonical Simkl URL), `release_status`
(human-readable e.g. `Ended`, `Continuing`). Useful for
one-shot UIs that render the full row without a follow-up
detail call.
value:
- id: 297
type: tv
link: https://simkl.com/tv/297/charmed
release_status: ended
release_year: 1998
rank: 5508
simkl:
rating: 7.4
votes: 717
droprate: 3%
imdb:
rating: 7.2
votes: 98744
- id: 1218
type: tv
link: https://simkl.com/tv/1218/the-simpsons
release_status: returning series
release_year: 1989
rank: 273
simkl:
rating: 8.2
votes: 2207
droprate: 7.4%
imdb:
rating: 8.6
votes: 468647
- id: 1698
type: tv
link: https://simkl.com/tv/1698/the-ellen-degeneres-show
release_status: ended
release_year: 2003
rank: 9664
simkl:
rating: 7.2
votes: 70
droprate: 5.1%
imdb:
rating: 6.5
votes: 18350
'401':
$ref: '#/components/responses/Unauthorized'
'412':
$ref: '#/components/responses/ClientIdFailed'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
security:
- clientId: []
bearerAuth: []
- simklApiKey: []
bearerAuth: []
x-codeSamples:
- lang: curl
label: default_all_types
source: >-
curl
'https://api.simkl.com/ratings/all?user_watchlist=1&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0'
\
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'User-Agent: my-app-name/1.0'
- lang: curl
label: movies_watching_returns_null
source: >-
curl
'https://api.simkl.com/ratings/movies?user_watchlist=watching&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0'
\
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'User-Agent: my-app-name/1.0'
- lang: curl
label: tv_plan_to_watch
source: >-
curl
'https://api.simkl.com/ratings/tv?user_watchlist=plantowatch&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0'
\
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'User-Agent: my-app-name/1.0'
- lang: curl
label: anime_completed
source: >-
curl
'https://api.simkl.com/ratings/anime?user_watchlist=completed&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0'
\
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'User-Agent: my-app-name/1.0'
- lang: curl
label: active_library_csv
source: >-
curl
'https://api.simkl.com/ratings/all?user_watchlist=plantowatch,watching,completed&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0'
\
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'User-Agent: my-app-name/1.0'
- lang: curl
label: with_imdb_and_mal_ratings
source: >-
curl
'https://api.simkl.com/ratings/all?user_watchlist=1&fields=simkl,ext&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0'
\
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'User-Agent: my-app-name/1.0'
- lang: curl
label: full_metadata_bundle
source: >-
curl
'https://api.simkl.com/ratings/all?user_watchlist=1&fields=simkl,ext,year,rank,droprate,link,release_status&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0'
\
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'User-Agent: my-app-name/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:
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:
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
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
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
````