Skip to content

Syncing

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.

  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.

GET /v1/changes?cursor=…&limit=100
Authorization: Bearer rfk_…
{
"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. Without it, changes to games are skipped.

The feed answers 410 with 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.

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; one request a minute per member is plenty for a background sync.

The reference client, 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.