Skip to main content

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.

​
Single-title ratings — use the detail endpoint

Per-title ratings (Simkl community average + votes, IMDb rating, MAL rating + rank) are returned as part of the catalog detail endpoints. There’s no separate read-only “ratings by ID” endpoint — the same data lives inside the ratings field of every detail response.
HaveUse
A Simkl IDGET /movies/{id} · GET /tv/{id} · GET /anime/{id}. All three are Cloudflare-cached, so repeat reads are near-free.
An external ID (IMDb / TMDB / TVDB / MAL / AniDB / …)First resolve to a Simkl ID via GET /redirect (returns a 301 with the canonical Simkl URL), then call the detail endpoint above. The redirect itself is a tiny 301 with no body; the detail call hits the CDN cache.
The ratings block on every detail response looks like: 
{
  "ratings": {
    "simkl": { "rating": 8.6, "votes": 11487 },
    "imdb":  { "rating": 8.8, "votes": 2817264 },
    "mal":   { "rating": 8.6, "votes": 3007340, "rank": 99 }
  }
}
Each provider key is present only when Simkl has data on file. Live-action titles typically carry simkl + imdb; modern anime carry simkl + mal; classic anime sometimes carry all three.

​
Bulk ratings for a user’s watchlist

If you need the Simkl community rating + drop rate for every title in the user’s watchlist (one type at a time), use:

GET /ratings/{type}

?user_watchlist=watching (or plantowatch, hold, completed, dropped, comma-separated, or 1 for all). Returns an array of {id, simkl: {rating, votes, droprate}} for every item in those watchlist buckets. Requires a Bearer token. Useful for “decide what to watch next from my plantowatch list” UIs.
For the user’s own ratings (the 1-10 scores they’ve personally assigned), use the Sync endpoints under /sync/ratings.

​
Aggregate ratings on simkl.com

Public catalog pages on simkl.com (e.g. /movies/472214/inception) render the same ratings block plus the user’s reactions and reviews. If your app wants to deep-link rather than render, see the Deep-linking guide.