curl --request POST \
  --url 'https://api.simkl.com/sync/ratings/remove?client_id=' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: <user-agent>' \
  --data '{}'

{
  "deleted": {
    "movies": 1,
    "shows": 0
  },
  "not_found": {
    "movies": [],
    "shows": []
  }
}

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).

POST

sync

ratings

remove

curl --request POST \
  --url 'https://api.simkl.com/sync/ratings/remove?client_id=' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: <user-agent>' \
  --data '{}'

{
  "deleted": {
    "movies": 1,
    "shows": 0
  },
  "not_found": {
    "movies": [],
    "shows": []
  }
}

Authorizations

client_id

string

query

default:YOUR_CLIENT_ID

required

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.

Authorization

string

header

default:YOUR_ACCESS_TOKEN

required

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

User-Agent

string

required

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

client_id

string

required

Your client_id from your Simkl developer settings. Required on every request.

app-name

string

required

Short, lowercase identifier for your app (e.g. plex-scrobbler, kodi-bridge). Helps Simkl identify which apps are using the API.

app-version

string

required

Your app's current version (e.g. 1.0, 2.4.1). Helps Simkl debug issues you report.

Body

application/json

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.

movies

object[]

Hide child attributes

movies.rating

integer

required

Required range: 1 <= x <= 10

movies.ids

object

required

External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.

Hide child attributes

movies.ids.simkl

integer

Simkl internal ID. Most reliable.

Example:

53536

movies.ids.slug

string

URL-safe slug returned in responses.

Example:

"attack-on-titan"

movies.ids.imdb

string

IMDb ID.

Example:

"tt0181852"

movies.ids.tmdb

string

TMDb ID.

Example:

"296"

movies.ids.tvdb

TVDB ID or slug.

Example:

153021

movies.ids.mal

string

MyAnimeList ID.

Example:

"4246"

movies.ids.anidb

string

AniDB ID. Specifying just this is enough for anime lookups.

Example:

"10846"

movies.ids.anilist

string

AniList ID.

Example:

"21"

movies.ids.kitsu

string

Kitsu ID.

Example:

"12"

movies.ids.anisearch

string

aniSearch ID.

Example:

"2227"

movies.ids.animeplanet

string

Anime-Planet slug.

Example:

"one-piece"

movies.ids.livechart

string

LiveChart ID.

Example:

"321"

movies.ids.letterboxd

string

Letterboxd slug.

Example:

"the-truman-show"

movies.ids.netflix

string

Netflix movie ID.

Example:

"70210890"

movies.ids.hulu

string

Hulu episode ID.

movies.ids.crunchyroll

string

Crunchyroll episode ID.

movies.ids.traktslug

string

Trakt slug.

Example:

"john-wick-chapter-4-2023"

Example:

{
  "simkl": 53536,
  "imdb": "tt0181852",
  "tmdb": 296
}

movies.rated_at

string<date-time>

shows

object[]

Hide child attributes

shows.rating

integer

required

Required range: 1 <= x <= 10

shows.ids

object

required

External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.

Hide child attributes

shows.ids.simkl

integer

Simkl internal ID. Most reliable.

Example:

53536

shows.ids.slug

string

URL-safe slug returned in responses.

Example:

"attack-on-titan"

shows.ids.imdb

string

IMDb ID.

Example:

"tt0181852"

shows.ids.tmdb

string

TMDb ID.

Example:

"296"

shows.ids.tvdb

TVDB ID or slug.

Example:

153021

shows.ids.mal

string

MyAnimeList ID.

Example:

"4246"

shows.ids.anidb

string

AniDB ID. Specifying just this is enough for anime lookups.

Example:

"10846"

shows.ids.anilist

string

AniList ID.

Example:

"21"

shows.ids.kitsu

string

Kitsu ID.

Example:

"12"

shows.ids.anisearch

string

aniSearch ID.

Example:

"2227"

shows.ids.animeplanet

string

Anime-Planet slug.

Example:

"one-piece"

shows.ids.livechart

string

LiveChart ID.

Example:

"321"

shows.ids.letterboxd

string

Letterboxd slug.

Example:

"the-truman-show"

shows.ids.netflix

string

Netflix movie ID.

Example:

"70210890"

shows.ids.hulu

string

Hulu episode ID.

shows.ids.crunchyroll

string

Crunchyroll episode ID.

shows.ids.traktslug

string

Trakt slug.

Example:

"john-wick-chapter-4-2023"

Example:

{
  "simkl": 53536,
  "imdb": "tt0181852",
  "tmdb": 296
}

shows.rated_at

string<date-time>

anime

object[]

Array of anime entries (same shape as shows[]).

Hide child attributes

anime.rating

integer

required

Required range: 1 <= x <= 10

anime.ids

object

required

External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.

Hide child attributes

anime.ids.simkl

integer

Simkl internal ID. Most reliable.

Example:

53536

anime.ids.slug

string

URL-safe slug returned in responses.

Example:

"attack-on-titan"

anime.ids.imdb

string

IMDb ID.

Example:

"tt0181852"

anime.ids.tmdb

string

TMDb ID.

Example:

"296"

anime.ids.tvdb

TVDB ID or slug.

Example:

153021

anime.ids.mal

string

MyAnimeList ID.

Example:

"4246"

anime.ids.anidb

string

AniDB ID. Specifying just this is enough for anime lookups.

Example:

"10846"

anime.ids.anilist

string

AniList ID.

Example:

"21"

anime.ids.kitsu

string

Kitsu ID.

Example:

"12"

anime.ids.anisearch

string

aniSearch ID.

Example:

"2227"

anime.ids.animeplanet

string

Anime-Planet slug.

Example:

"one-piece"

anime.ids.livechart

string

LiveChart ID.

Example:

"321"

anime.ids.letterboxd

string

Letterboxd slug.

Example:

"the-truman-show"

anime.ids.netflix

string

Netflix movie ID.

Example:

"70210890"

anime.ids.hulu

string

Hulu episode ID.

anime.ids.crunchyroll

string

Crunchyroll episode ID.

anime.ids.traktslug

string

Trakt slug.

Example:

"john-wick-chapter-4-2023"

Example:

{
  "simkl": 53536,
  "imdb": "tt0181852",
  "tmdb": 296
}

anime.rated_at

string<date-time>

Response

Counts of items affected, plus any IDs Simkl could not match.

Counts of ratings cleared plus any IDs Simkl could not match.

deleted

object

required

Hide child attributes

deleted.movies

integer

required

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).

Example:

1

deleted.shows

integer

required

Number of shows or anime for which a rating was cleared. Anime is folded under shows (same as on POST /sync/ratings).

Example:

0

not_found

object

required

Per-type lists of input items Simkl could not match. No anime key — anime is folded under shows.

Hide child attributes

not_found.movies

object[]

required

Input movie objects Simkl could not match.

not_found.shows

object[]

required

Input show/anime objects Simkl could not match.

Add Ratings

Get the user's rated items, filtered by type and rating

⌘I