Skip to content

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).

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-2c6d0f5e9b14
Authorization: Bearer rfk_…
Content-Type: application/json
{ "status": "on_hold" }
  • PUT /v1/library/{id} adds a title with a status, or moves it there. planned is the watchlist; completed on 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 answers IN_LIBRARY and 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 optional visibility. A rating needs no watch. DELETE on 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; DELETE removes it. PUT /v1/lists/{id}/order puts 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}/play its play time and progress (the whole play time so far, not a delta), PUT /v1/ratings/games/{id} its rating, and PUT /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.

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, answers IN_LIBRARY and is left alone.
  • DELETE /v1/history/movies/{id} removes one movie play, by the id GET /v1/history/movies serves. Removing a rewatch keeps the first watch. The first watch goes once it is the last play: before that, the answer is CONFLICT with detail remove_rewatches_first. A 204 always means the play is gone.
  • DELETE /v1/history/rewatches/{id} removes one episode rewatch, by the id GET /v1/history/rewatches serves. 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: CONFLICT with detail remove_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 needs history:write and ratings:write on top of library:write.
  • DELETE /v1/lists/{id} deletes a list and its items.

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/movies
Authorization: Bearer rfk_…
Content-Type: application/json
Idempotency-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: result is watched or rewatched, with the play added.
  • 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: result is duplicate and nothing is added. Further apart, it is a rewatch.

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/rewatches
Authorization: Bearer rfk_…
Content-Type: application/json
Idempotency-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 CONFLICT with detail not_watched: mark its first watch with PUT first.
  • When the member is rewatching the show (revisit on the library item) and the episode belongs to that rewatch, it is ticked there too, as in the app: revisit_ticked is true, 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: result is duplicate and 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.

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.