Skip to content

Games

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.

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.

{
"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.
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. When the game catalogue cannot be reached, the answer is UNAVAILABLE with a Retry-After.

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

{
"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.

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 with detail not_in_library).

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.

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

Add include=games to the change feed:

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

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

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