Writing data
Writes go through the same rules as the Refract app: marking an episode from your app updates the member’s progress,
diary, streak and stats exactly as a tap on their phone does. Each write needs a :write scope the member approved
(library:write, history:write, ratings:write, lists:write).
Setting state: PUT and DELETE
Section titled “Setting state: PUT and DELETE”Most writes set a state, so retrying them is always safe: a PUT that changes nothing writes nothing.
PUT /v1/library/8b0e5c1a-4f2d-4b7e-9a31-2c6d0f5e9b14Authorization: Bearer rfk_…Content-Type: application/json
{ "status": "on_hold" }PUT /v1/library/{id}adds a title with a status, or moves it there.plannedis the watchlist;completedon a movie logs its first watch.PUT /v1/watchlist/{id}adds a title to the watchlist. A title the member already tracks with another status answersIN_LIBRARYand is left alone.PUT /v1/history/episodes/{id}/{season}/{number}marks an episode watched, adding the show to the library when needed. Send{ "watched_at": "2026-10-30T21:40:00+01:00" }for a past viewing; without it, now. An episode already watched is left as it is, date included.DELETE /v1/history/episodes/{id}/{season}/{number}marks it not watched. Not watched already: 204 as well.PUT /v1/ratings/shows/{id},/v1/ratings/movies/{id}and/v1/ratings/episodes/{id}/{season}/{number}set a rating from 1 to 10,{ "value": 8 }, with an optionalvisibility. A rating needs no watch.DELETEon the same path removes it and leaves the review alone.PUT /v1/lists/{id}/items/{item_id}adds a title at the end of a list;DELETEremoves it.PUT /v1/lists/{id}/orderputs every title of the list in a new order,{ "ids": [ … ] }.PATCH /v1/lists/{id}renames a list or changes its description or visibility.- Games:
PUT /v1/games/library/{id}sets a game’s status,PUT /v1/games/library/{id}/playits play time and progress (the whole play time so far, not a delta),PUT /v1/ratings/games/{id}its rating, andPUT /v1/lists/{id}/games/{game_id}adds it to a list. See Games.
A 201 means something was created, a 200 that it already was as you asked. Every answer carries the thing as
GET serves it.
Removing
Section titled “Removing”A DELETE answers 204, also when there was nothing to remove, so a retry is always safe.
DELETE /v1/watchlist/{id}takes a title off the watchlist. A title the member tracks with another status, or that carries a rating, a review or a play, answersIN_LIBRARYand is left alone.DELETE /v1/history/movies/{id}removes one movie play, by theidGET /v1/history/moviesserves. Removing a rewatch keeps the first watch. The first watch goes once it is the last play: before that, the answer isCONFLICTwithdetailremove_rewatches_first. A204always means the play is gone.DELETE /v1/history/rewatches/{id}removes one episode rewatch, by theidGET /v1/history/rewatchesserves. The first watch and the other rewatches stay. A season or whole-show rewatch counts on every episode it covered, so the member removes it in the app:CONFLICTwithdetailremove_in_app.DELETE /v1/library/{id}removes a title and everything the member recorded about it: status, episode watches, plays, rating and review, as “Remove from library” does in the app. It cannot be undone, so it needshistory:writeandratings:writeon top oflibrary:write.DELETE /v1/lists/{id}deletes a list and its items.
Appending: POST with an Idempotency-Key
Section titled “Appending: POST with an Idempotency-Key”Logging a movie play adds to the history: sent twice, it would log two plays. So POST /v1/history/movies requires an
Idempotency-Key header, a new
unique value per play. Logging an episode rewatch, POST /v1/history/rewatches, and creating a list,
POST /v1/lists, need one too:
POST /v1/history/moviesAuthorization: Bearer rfk_…Content-Type: application/jsonIdempotency-Key: "8e03978e-40d5-43e8-bc93-6894a57f9324"
{ "movie_id": "3c51…", "watched_at": "2026-10-30T18:00:00Z" }- The first play of a movie is its first watch; later ones are rewatches. The answer says which:
resultiswatchedorrewatched, with theplayadded. - Retry with the same key when a request timed out or failed on the network: you get the first answer back, with
Idempotent-Replayed: true, and nothing is logged twice. - A key is kept 24 hours. Reused for another request, it answers
IDEMPOTENCY_KEY_MISMATCH; retried while the first request still runs,IDEMPOTENCY_KEY_IN_USE. - A play reported again under a new key, within 30 minutes of a play already logged (before or after it), is the
same viewing:
resultisduplicateand nothing is added. Further apart, it is a rewatch.
Episode rewatches
Section titled “Episode rewatches”An episode’s first watch is state: PUT /v1/history/episodes/{id}/{season}/{number} sets it, and sending it again
changes nothing. Watching it again is a new viewing, logged with POST /v1/history/rewatches and an
Idempotency-Key:
POST /v1/history/rewatchesAuthorization: Bearer rfk_…Content-Type: application/jsonIdempotency-Key: "0b6f1c1e-7a5e-4c8e-9f0e-2d1b5d0c9a47"
{ "show_id": "9f12…", "season": 1, "number": 4, "watched_at": "2026-11-03T20:15:00Z" }- The episode must be watched already; otherwise the answer is
CONFLICTwithdetailnot_watched: mark its first watch withPUTfirst. - When the member is rewatching the show (
revisiton the library item) and the episode belongs to that rewatch, it is ticked there too, as in the app:revisit_tickedistrue, and up next moves on. - Reported again within 30 minutes of the episode’s last viewing, first watch or rewatch, it is the same viewing:
resultisduplicateand nothing is added.
Send the instant the member watched, in RFC 3339 with an offset or Z. Refract records it on the member’s own calendar,
in their time zone, and serves it back as a calendar fact { local, tz } (Conventions).
A watch more than a day in the future is refused.
What you will see in the feed
Section titled “What you will see in the feed”Your writes to the library, the history and ratings appear in the change feed like any other
change. Shows also move between in_progress, up_to_date and completed by themselves as episodes air; those moves
are changes too. Lists are not in the feed: read them again with GET /v1/lists.