# Writing data

> Change a member's library and history safely, retries included.

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

Most writes set a state, so retrying them is always safe: a `PUT` that changes nothing writes nothing.

```http
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`](/developers/errors/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](/developers/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

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`](/developers/errors/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`](/developers/errors/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`](/developers/errors/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.

## 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`](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/) 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:

```http
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`](/developers/errors/idempotency-key-mismatch); retried while the first request still
  runs, [`IDEMPOTENCY_KEY_IN_USE`](/developers/errors/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.

## 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`:

```http
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`](/developers/errors/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.

## Dates

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](/developers/conventions)).
A watch more than a day in the future is refused.

## What you will see in the feed

Your writes to the library, the history and ratings appear in the [change feed](/developers/sync) 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`.
