The Sync API keeps a user’s library in step with Simkl across every device and app — watch history, watchlists (Watching / Plan to Watch / Hold / Dropped / Completed), per-item ratings, and paused playbacks. This page is a reference index. The strategy and walkthroughs live in the Sync guide: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.
Sync guide — full walkthrough
Two-phase model end-to-end — Phase 1 sequential pull, Phase 2
/sync/activities + date_from delta loop, deletion reconciliation, when to actually run sync, useful query params, and a Node + Python reference implementation.Common request parameters
Every Sync endpoint shares the same auth + identification surface. See Headers and required parameters for the full reference.| Param | Where | Notes |
|---|---|---|
client_id | URL query | Your app’s client_id. |
app-name | URL query | Lowercase identifier (e.g. my-app-name). |
app-version | URL query | App version string (e.g. 1.0). |
User-Agent | header | <app-name>/<app-version>. |
Authorization | header | Bearer <access_token> — required for every Sync endpoint. |
Supported ID keys
Every Sync write endpoint matches items by theids object. See the full key list (with types and examples) in Standard media objects → Supported ID keys.
Anime works under either
shows[] or anime[]. All Sync write endpoints accept movies[], shows[], anime[], and episodes[] as top-level arrays. Anime entries are resolved by ids regardless of which wrapper you use — match the field to your data type when known, fall back to shows[] when you only have TMDB / TVDB IDs. Caveat: not_found.shows carries any unresolved anime entries too (no separate not_found.anime bucket). See Anime in shows[] or anime[].Endpoints
Activities
GET /sync/activities — last-modified timestamps per category. The “is anything new?” gate.All items
GET /sync/all-items/{type}/{status} — both segments optional. Library reads (full or delta).Add to history
POST /sync/history — mark items watched.Remove history
POST /sync/history/remove — un-mark watched.Add to watchlist
POST /sync/add-to-list — move between watchlist statuses.Mark watched
POST /sync/watched — bulk legacy “watched” write.Rate items
POST /sync/ratings — 1–10 user rating per item.Remove ratings
POST /sync/ratings/remove — clear user-set ratings.Filter ratings
GET /sync/ratings/{type}/{rating} — list rated items filtered by type and one or more rating values.Get playbacks
GET /sync/playback — list saved paused playbacks (optionally narrow with /{type} where {type} is episodes or movies).Delete playback
DELETE /sync/playback/{id} — clear a single saved session.