API Reference
Trending
Calendar
Redirect
Sync
Changes
Remove Ratings
Clears the user’s ratings on the listed items. Body shape is identical to POST /sync/ratings minus the rating field — the IDs alone are enough to identify which entries to un-rate.
Removing a rating does NOT remove the item from the user’s watchlist — it only clears the rating value. The item keeps its watchlist status (watching / completed / etc.) and stays in the library. To remove an item from the user’s library entirely, use POST /sync/history/remove.
Response shape
Status: 201 Created.
{
"deleted": {
"movies": <number of movies un-rated>,
"shows": <number of shows un-rated (anime included)>
},
"not_found": {
"movies": [<items Simkl could not match>],
"shows": [<items Simkl could not match>]
}
}
No anime key — anime is folded under shows on both the request and response side, same as on POST /sync/ratings. Send anime titles in shows[] with anime-only IDs (mal, anidb, anilist, kitsu) inside each item’s ids object.
deleted counts matched items, not items that actually had a rating. If you send a movie that Simkl resolves to a canonical record but the user never rated it, that movie still counts in deleted.movies. The call is idempotent — sending the same body twice has the same end state on the second call as on the first.
POST /sync/ratings
The mirror endpoint that sets ratings. Same body shape minus the rating field on each item.
Sync guide — full walkthrough
The two-phase sync model and how rating activity surfaces in /sync/activities.
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. 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).
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.
Authorizations
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.
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.
Headers
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).
Query Parameters
Your client_id from your Simkl developer settings. Required on every request.
Short, lowercase identifier for your app (e.g. plex-scrobbler, kodi-bridge). Helps Simkl identify which apps are using the API.
Your app's current version (e.g. 1.0, 2.4.1). Helps Simkl debug issues you report.
Body
Request body for removing ratings. The rating field is not needed — identify items by ids (or title + year), and Simkl clears any rating set on them. To set or change a rating, use POST /sync/ratings instead. Items go under movies[], shows[], or anime[] — Simkl resolves anime titles correctly under either shows[] or anime[], so match the field to your data type when known.
Hide child attributes
Hide child attributes
1 <= x <= 10External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.
Hide child attributes
Hide child attributes
Simkl internal ID. Most reliable.
53536
URL-safe slug returned in responses.
"attack-on-titan"
IMDb ID.
"tt0181852"
TMDb ID.
"296"
TVDB ID or slug.
153021
MyAnimeList ID.
"4246"
AniDB ID. Specifying just this is enough for anime lookups.
"10846"
AniList ID.
"21"
Kitsu ID.
"12"
aniSearch ID.
"2227"
Anime-Planet slug.
"one-piece"
LiveChart ID.
"321"
Letterboxd slug.
"the-truman-show"
Netflix movie ID.
"70210890"
Hulu episode ID.
Crunchyroll episode ID.
Trakt slug.
"john-wick-chapter-4-2023"
{
"simkl": 53536,
"imdb": "tt0181852",
"tmdb": 296
}
Hide child attributes
Hide child attributes
1 <= x <= 10External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.
Hide child attributes
Hide child attributes
Simkl internal ID. Most reliable.
53536
URL-safe slug returned in responses.
"attack-on-titan"
IMDb ID.
"tt0181852"
TMDb ID.
"296"
TVDB ID or slug.
153021
MyAnimeList ID.
"4246"
AniDB ID. Specifying just this is enough for anime lookups.
"10846"
AniList ID.
"21"
Kitsu ID.
"12"
aniSearch ID.
"2227"
Anime-Planet slug.
"one-piece"
LiveChart ID.
"321"
Letterboxd slug.
"the-truman-show"
Netflix movie ID.
"70210890"
Hulu episode ID.
Crunchyroll episode ID.
Trakt slug.
"john-wick-chapter-4-2023"
{
"simkl": 53536,
"imdb": "tt0181852",
"tmdb": 296
}
Array of anime entries (same shape as shows[]).
Hide child attributes
Hide child attributes
1 <= x <= 10External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.
Hide child attributes
Hide child attributes
Simkl internal ID. Most reliable.
53536
URL-safe slug returned in responses.
"attack-on-titan"
IMDb ID.
"tt0181852"
TMDb ID.
"296"
TVDB ID or slug.
153021
MyAnimeList ID.
"4246"
AniDB ID. Specifying just this is enough for anime lookups.
"10846"
AniList ID.
"21"
Kitsu ID.
"12"
aniSearch ID.
"2227"
Anime-Planet slug.
"one-piece"
LiveChart ID.
"321"
Letterboxd slug.
"the-truman-show"
Netflix movie ID.
"70210890"
Hulu episode ID.
Crunchyroll episode ID.
Trakt slug.
"john-wick-chapter-4-2023"
{
"simkl": 53536,
"imdb": "tt0181852",
"tmdb": 296
}
Response
Counts of items affected, plus any IDs Simkl could not match.
Counts of ratings cleared plus any IDs Simkl could not match.
Hide child attributes
Hide child attributes
Number of movies for which a rating was cleared (or that matched but had no rating to begin with — the counter increments unconditionally on successful match).
1
Number of shows or anime for which a rating was cleared. Anime is folded under shows (same as on POST /sync/ratings).
0
Was this page helpful?