# Syncing

> Keep a local copy of a member's library, history and ratings up to date with the change feed.

An app that keeps its own copy of a member's data (a media center, a backup tool, another tracker) does a full sync
once, then reads only what changed. Refract gives it a starting cursor and a feed of changes after it.

## First sync

1. **Take a cursor first.** `GET /v1/changes/head` returns `{ "cursor": "…" }`. Store it before anything else.
2. **Read the lists you keep**, page by page: `/v1/library`, `/v1/history/episodes`, `/v1/history/movies`,
   `/v1/history/rewatches`, `/v1/ratings`.
3. **Read the changes from that cursor** (below). Whatever changed while you were reading the lists arrives in the
   feed, so nothing is lost.

Taking the cursor first matters: a change made while you read the lists then reaches you twice (in a list and in the
feed), never zero times.

## Reading changes

```http
GET /v1/changes?cursor=…&limit=100
Authorization: Bearer rfk_…
```

```json
{
  "data": [
    {
      "type": "episode_watch",
      "action": "upsert",
      "changed_at": "2026-10-30T20:41:55.120Z",
      "show": { "refract": "8b0e5c1a-…", "tmdb": 95396, "imdb": "tt11280740", "tvdb": null },
      "episode": { "season": 2, "number": 4 },
      "item": { "show": { … }, "episode": { "season": 2, "number": 4 }, "watched_at": { "local": "2026-10-30T21:41:00.000000+01:00", "tz": "Europe/Paris" }, … }
    },
    {
      "type": "library_item",
      "action": "delete",
      "changed_at": "2026-10-30T20:43:02.004Z",
      "ids": { "refract": "3c51…", "tmdb": 693134, "imdb": null, "tvdb": null },
      "item": null
    }
  ],
  "next_cursor": "djEuMTI0…",
  "has_more": false
}
```

- **Each change is the current state** of what changed, in the same shape as the list endpoint that serves it
  (`library_item` → `/v1/library`, `episode_watch` → `/v1/history/episodes`, `movie_play` → `/v1/history/movies`,
  `show_rewatch` → `/v1/history/rewatches`, `rating` → `/v1/ratings`). `upsert`: store `item`, replacing what you hold under the same keys. `delete`: remove
  what the keys name.
- **A watch brings its title along.** An episode watch or a movie play is followed by the `library_item` of its
  title, so the progress, rewatch count and rewatch in progress you keep stay current. Starting or ending a rewatch
  without watching anything shows up with the title's next change.
- **Apply changes idempotently.** The same thing can appear more than once, on the same page or a later one. Applying
  a change twice must leave the same result as applying it once.
- **Store `next_cursor` once the page is applied**, then ask again with it: right away when `has_more` is `true`,
  later when it is `false`. A page can be short, even empty, while `has_more` is `true`.
- **Skip `type` values you do not know.** New kinds of change will appear.
- What the credential cannot read is left out: episode watches, movie plays and show rewatches need `history:read`, ratings
  `ratings:read`. The feed itself needs `library:read`.
- Lists and their titles are not in the feed yet. Re-read `/v1/lists` when you need them.
- Games come only with `include=games`: see [Syncing games](/developers/games#syncing-games). Without it, changes to
  games are skipped.

## When to sync again from scratch

The feed answers `410` with [`SYNC_RESET_REQUIRED`](/developers/errors/sync-reset-required) when it cannot bring your
copy up to date from your cursor:

- the cursor was not used for too long. Read the feed at least once a week and it never expires;
- the member's data changed in bulk in a way the feed does not describe change by change: a file import, a library
  wipe, or Refract merging a title that TMDB replaced with another.

Throw away your copy and run the first sync again from a new `GET /v1/changes/head`.

## Polling

Poll with the last `next_cursor` whenever your app needs fresh data: on launch, when the member opens a screen, or on a
timer. Every request counts against the [rate limit](/developers/rate-limits); one request a minute per member is
plenty for a background sync.

## A complete example

The [reference client](/developers/examples/refract-sync.mjs), a single file for Node.js 20 or later with no dependencies, signs in with the device flow or PKCE,
refreshes and revokes its tokens, and keeps a local copy with exactly the steps above, deletions and resets
included.
