> ## 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

> Read and write the user's watch history, watchlists, ratings, and playbacks.

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:

<Card title="Sync guide — full walkthrough" icon="arrows-rotate" href="/guides/sync" horizontal>
  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.
</Card>

## Common request parameters

Every Sync endpoint shares the same auth + identification surface. See [Headers and required parameters](/conventions/headers) 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 the `ids` object. See the full key list (with types and examples) in [Standard media objects → Supported ID keys](/conventions/standard-media-objects#supported-id-keys).

<Note>
  **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[]`](/conventions/standard-media-objects#anime).
</Note>

## Endpoints

<CardGroup cols={2}>
  <Card title="Activities" icon="clock" href="/api-reference/simkl/get-activities">
    `GET /sync/activities` — last-modified timestamps per category. The "is anything new?" gate.
  </Card>

  <Card title="All items" icon="list" href="/api-reference/simkl/get-all-items">
    `GET /sync/all-items/{type}/{status}` — both segments optional. Library reads (full or delta).
  </Card>

  <Card title="Add to history" icon="plus" href="/api-reference/simkl/add-to-history">
    `POST /sync/history` — mark items watched.
  </Card>

  <Card title="Remove history" icon="minus" href="/api-reference/simkl/remove-from-history">
    `POST /sync/history/remove` — un-mark watched.
  </Card>

  <Card title="Add to watchlist" icon="bookmark" href="/api-reference/simkl/add-to-list">
    `POST /sync/add-to-list` — move between watchlist statuses.
  </Card>

  <Card title="Mark watched" icon="circle-check" href="/api-reference/simkl/get-watched">
    `POST /sync/watched` — bulk legacy "watched" write.
  </Card>

  <Card title="Rate items" icon="star" href="/api-reference/simkl/add-ratings">
    `POST /sync/ratings` — 1–10 user rating per item.
  </Card>

  <Card title="Remove ratings" icon="star-half-stroke" href="/api-reference/simkl/remove-ratings">
    `POST /sync/ratings/remove` — clear user-set ratings.
  </Card>

  <Card title="Filter ratings" icon="filter" href="/api-reference/simkl/get-user-ratings">
    `GET /sync/ratings/{type}/{rating}` — list rated items filtered by type and one or more rating values.
  </Card>

  <Card title="Get playbacks" icon="play" href="/api-reference/simkl/get-playback-sessions">
    `GET /sync/playback` — list saved paused playbacks (optionally narrow with `/{type}` where `{type}` is `episodes` or `movies`).
  </Card>

  <Card title="Delete playback" icon="trash" href="/api-reference/simkl/delete-playback">
    `DELETE /sync/playback/{id}` — clear a single saved session.
  </Card>
</CardGroup>