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
Section titled “First sync”- Take a cursor first.
GET /v1/changes/headreturns{ "cursor": "…" }. Store it before anything else. - Read the lists you keep, page by page:
/v1/library,/v1/history/episodes,/v1/history/movies,/v1/history/rewatches,/v1/ratings. - 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
Section titled “Reading changes”GET /v1/changes?cursor=…&limit=100Authorization: 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: storeitem, 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_itemof 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_cursoronce the page is applied, then ask again with it: right away whenhas_moreistrue, later when it isfalse. A page can be short, even empty, whilehas_moreistrue. - Skip
typevalues 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, ratingsratings:read. The feed itself needslibrary:read. - Lists and their titles are not in the feed yet. Re-read
/v1/listswhen you need them. - Games come only with
include=games: see Syncing games. Without it, changes to games are skipped.
When to sync again from scratch
Section titled “When to sync again from scratch”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.
Polling
Section titled “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; one request a minute per member is
plenty for a background sync.
A complete example
Section titled “A complete example”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.