# Games

> Read and update a member's games, playthroughs, play sessions, game ratings and the games in their lists.

Refract tracks video games beside shows and movies. Games have endpoints of their own, so an app written for shows and
movies never meets one by surprise: no `data` array that already existed ever carries a game.

## Where a game can appear

A game appears only where you ask for one:

| Where | How |
|---|---|
| The games library, playthroughs, play sessions | `/v1/games/library`, `/v1/games/playthroughs`, `/v1/games/sessions` |
| Ratings of games | `/v1/ratings/games` |
| The games in a list | `/v1/lists/{id}/games` |
| Finding a game by another service's id | `GET /v1/search/{id_type}/{id}?type=game`, with `igdb`, `steam` or `rmdb` |
| The change feed | `GET /v1/changes?include=games` |
| The calendar and the stats | their own `games` field |

Everything else (`/v1/library`, `/v1/watchlist`, `/v1/history/…`, `/v1/ratings`, `/v1/lists/{id}/items`, `/v1/up-next`)
serves shows and movies only, and answers `404` to a game's id.

The member's choice to hide games in the app's display settings changes only the app: the API serves and writes
their games either way, the calendar and the stats included.

## A game

```json
{
  "type": "game",
  "ids": { "refract": "5d7c1e2a-0b3f-4c8d-9e61-7a2f4b9c0d35", "rmdb": "9ff8970c-3d02-4c45-bd24-43891467470b" },
  "title": "The Witcher 3: Wild Hunt",
  "original_title": "The Witcher 3: Wild Hunt",
  "year": 2015
}
```

- `ids.refract` is Refract's id: every games endpoint takes it.
- `ids.rmdb` is the game's id in RMDB, Refract's game catalogue.
- Refract does not store a game's IGDB or Steam id. Find a game by them with search.

## Finding a game

```http
GET /v1/search/igdb/1942?type=game
GET /v1/search/steam/292030?type=game
GET /v1/search/rmdb/9ff8970c-3d02-4c45-bd24-43891467470b?type=game
```

The answer's `data` holds the game, or nothing when the catalogue does not know the id. A Steam app id of a DLC finds
the DLC itself. `type=game` goes with these three id types and only with them: either half alone answers
[`INVALID_REQUEST`](/developers/errors/invalid-request). When the game catalogue cannot be reached, the answer is
[`UNAVAILABLE`](/developers/errors/unavailable) with a `Retry-After`.

## The games library

`GET /v1/games/library` lists the member's games (filter with `status`), `GET /v1/games/library/{id}` one of them:

```json
{
  "type": "game",
  "ids": { "refract": "5d7c…", "rmdb": "9ff8…" },
  "title": "The Witcher 3: Wild Hunt",
  "original_title": "The Witcher 3: Wild Hunt",
  "year": 2015,
  "status": "in_progress",
  "owned": true,
  "rating": 9,
  "replay_count": 0,
  "added_at": "2026-11-02T18:04:11.000Z",
  "updated_at": "2026-11-02T18:04:11.000Z",
  "last_played_at": "2026-11-15T21:30:02.000Z",
  "play": {
    "run_number": 1,
    "state": "active",
    "playtime_minutes": 2710,
    "progress_percent": 64,
    "target": "normally",
    "ownership": "owned",
    "edition_id": null,
    "platforms": [
      {
        "key": "rmdb:platform:pc",
        "name": "PC (Microsoft Windows)",
        "abbreviation": "PC",
        "family": "pc",
        "ids": ["052a4690-4e20-4a04-988e-c0454b92fbfa"]
      }
    ],
    "started_on": { "local": "2026-11-02", "tz": null },
    "finished_on": null,
    "updated_at": "2026-11-15T21:30:02.000Z"
  },
  "replay": null
}
```

- `status`: `planned` is want to play, `in_progress` playing, `completed` played; `on_hold` and `dropped` as for a
  show. A game is never `up_to_date`.
- `owned`: the member's collection holds a copy (their own, a store sync, an import).
- `rating` is present only when the credential holds `ratings:read`; `null` when the game is not rated.
- `play` is the current playthrough: the replay under way, else the latest one the member did not stop. `null` until
  a play is logged.
- `platforms` lists each platform once, as the app's Stats and library filter show it: `key` is the catalogue entry,
  so PC appears once whatever RMDB ids the play names. `ids` holds those ids, in the play's order, and is what
  `platform_ids` takes on a write. An id Refract cannot identify yet comes on its own, with `key` and `name` `null`.
- `started_on` and `finished_on` are days with no time zone.

`PUT /v1/games/library/{id}` with `{ "status": "planned" }` adds a game or moves it, as the app's status picker does.
`DELETE /v1/games/library/{id}` removes the game with its playthroughs, sessions, rating and review; like removing a
title, it needs `library:write`, `history:write` and `ratings:write`.

## Logging play

`PUT /v1/games/library/{id}/play` sets the current playthrough's play, as the app's Log progress and Play details do.
Fields left out keep their value. It needs `history:write`, and the game must be in the library (otherwise
[`CONFLICT`](/developers/errors/conflict) with `detail` `not_in_library`).

```http
PUT /v1/games/library/5d7c1e2a-0b3f-4c8d-9e61-7a2f4b9c0d35/play
Authorization: Bearer rfk_…
Content-Type: application/json

{ "playtime_minutes": 2800, "progress_percent": 70, "platform_ids": ["052a4690-4e20-4a04-988e-c0454b92fbfa"] }
```

- **`playtime_minutes` is the whole play time so far**, never the time just played: add your session to the value you
  read. A retry of the same body changes nothing, so it needs no `Idempotency-Key`.
- **Refract dates play time the way the app does.** When play time or progress grows, a session is logged, dated only
  for what could have been played since the game's previous play, and never more than a day of play in any 24 hours.
  The rest is play time without a date: it counts in `playtime_minutes` and in the stats, never on a day.
- **A game's first play time is the total so far** unless you say otherwise: send `"first_entry": "session"` when it
  was played today. It is then dated now, within what today has had. `first_entry` is read only on a game with no play
  time yet.
- `platform_ids` replaces the list: to keep a platform, send the `ids` you read on it.
- `run_number` picks another playthrough; a number the member never played answers `CONFLICT` with `detail`
  `unknown_run`. Bringing a replay to 100 %, or giving it a `finished_on`, finishes it (`replay_finished: true`).
- `ownership: "owned"` also puts a copy in the member's collection.

The answer is `{ "play": … , "replay_finished": false }`, the playthrough as `GET /v1/games/playthroughs` serves it:
`201` for the playthrough's first play, `200` otherwise.

## Playthroughs and play history

- `GET /v1/games/playthroughs`: every playthrough of every game in the library, replays included, by game then
  playthrough. The first playthrough is `active`; a replay is `active` while under way, `completed` once finished,
  `stopped` when the member stopped it. Start and stop replays in the app.
- `GET /v1/games/sessions`: the play history, oldest first. Each session carries `played_at` on the member's calendar
  and the `minutes` dated then; `source` is `logged` (the member logged it, in the app or through the API) or
  `platform` (Steam or Xbox reported it). Play time without a date is in no session, so a game's sessions can add up to
  less than its `playtime_minutes`: Refract never makes up a day for it.

## Ratings and lists

- `GET /v1/ratings/games`, and `PUT` or `DELETE /v1/ratings/games/{id}` with `{ "value": 9 }`, as for a movie.
- `GET /v1/lists/{id}/games` lists a list's games in its order; `PUT` or `DELETE /v1/lists/{id}/games/{game_id}` adds
  or removes one. `PUT /v1/lists/{id}/order` orders the list's shows and movies; its games keep their place after
  them. A list's `item_count` counts every item, games included.

## Syncing games

Add `include=games` to the change feed:

```http
GET /v1/changes?cursor=…&include=games
```

| `type` | Key | Same shape as | Scope |
|---|---|---|---|
| `game_library_item` | `ids` | `/v1/games/library` | `library:read` |
| `game_playthrough` | `game` and `run_number` | `/v1/games/playthroughs` | `history:read` |
| `game_session` | `session_id` | `/v1/games/sessions` | `history:read` |
| `game_rating` | `ids` | `/v1/ratings/games` | `ratings:read` |

Every game change brings the game's `game_library_item` along, since it carries the current play, the rating and
last played. A session left holding play time without a date is a `delete`: it is no longer listed. For a full
sync, read the games endpoints after taking the cursor, as in [Syncing](/developers/sync). Not in the feed until the
game's next change: the member marking a copy owned outside a play, and a replay started or stopped. Without
`include=games`, changes to games are skipped.

## Stats

`GET /v1/stats` has a `games` block, counted as the member's profile counts it:

```json
"games": { "play_minutes": 41250, "played": 37, "finished": 21 }
```

`play_minutes` is the play time of the games in the library, every playthrough, play time without a date included.
It is not part of `watch_time`: the profile's Time Spent is `watch_time.total_minutes + games.play_minutes`.
