Add Ratings

Apply user ratings (1-10) to movies, shows, or anime. Same auth model and batching rules as the rest of the Sync API. Ratings come back on every GET /sync/all-items item as user_rating, so reading them needs no extra request — see Read side below.

Body shape

Top-level keys per media type, each carrying an array of items:

{
 "movies": [
 {
 "rating": 8,
 "ids": {
 "simkl": 53536
 }
 }
 ],
 "shows": [
 {
 "rating": 9,
 "ids": {
 "tmdb": "1399"
 }
 }
 ],
 "anime": [
 {
 "rating": 10,
 "ids": {
 "mal": "11757"
 },
 "rated_at": "2026-05-15T20:00:00Z"
 }
 ]
}

Per-item fields:

Re-rating an item overwrites the prior value — no need to call /sync/ratings/remove first.

Auto-move side effect

Rating an item that’s not yet on the user’s list auto-files it based on airing status:

The corresponding list timestamp on /sync/activities bumps, so a rated item shows up in the next date_from delta even though the user only rated it. Treat the delta as authoritative.

Response (201 Created)

{
 "added": {
 "movies": 1,
 "shows": 1,
 "statuses": [
 {
 "request": {
 "rating": 8,
 "ids": {
 "simkl": 53536
 }
 },
 "response": {
 "status": "completed"
 }
 }
 ]
 },
 "not_found": {
 "movies": [],
 "shows": []
 }
}

added.anime does NOT exist. Anime items are folded into the shows counter — apps must not look for a separate anime slot in added or not_found. If you need to know which items landed, walk added.statuses[] (the request.ids echo back what you sent).

response.status per item is the watchlist status the auto-move applied (completed, watching, plantowatch, etc.) — useful for updating local UI without a follow-up /sync/activities poll.

Out-of-range ratings

Any rating outside 1-10 (including 0, 11, -1, 100) is silently rejected — the item lands in not_found.<type> and the HTTP status is still 201. No 400 is returned; the rejection is reported in the response body, not the status code. Clients must validate client-side; never trust that a 2xx response means the rating was applied. Always inspect added.statuses[] (or not_found) to confirm.

Read side

No separate read is needed during sync. Every item from GET /sync/all-items already carries user_rating and user_rated_at. GET /sync/ratings returns those same watchlist rows, keyed by media type — call it only when rated_at moved in GET /sync/activities, or to have the server filter by score:

{
 "movies": [ {..., "user_rating": 8, "user_rated_at": "2026-05-13T..." } ],
 "shows": [ {..., "user_rating": 9,... } ],
 "anime": [ {..., "user_rating": 10,... } ]
}

Each item carries the standard watchlist record (status, episode counts, dates) plus user_rating (int 1-10 or null) and user_rated_at (ISO-8601 UTC or null).

To filter by score, use GET /sync/ratings/:type/:rating. For public catalog ratings (the community average + IMDb/MAL score for any title, no token required), the rating data is in the per-title detail endpoints — GET /movies/:id, GET /tv/:id, GET /anime/:id — under the ratings field. Resolve external IDs first via GET /redirect.

Removing a rating

Use POST /sync/ratings/remove with the same body shape minus the rating field (the value is ignored on remove). Removing the rating does not remove the item from the user’s watchlist — only the score is cleared.

Rate alongside a watch event

If you’re recording a watch event and want to attach a rating in the same call, use POST /sync/history — it accepts a rating field per item. One round-trip instead of two.