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
Section titled “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
Section titled “A game”{ "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.refractis Refract’s id: every games endpoint takes it.ids.rmdbis 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
Section titled “Finding a game”GET /v1/search/igdb/1942?type=gameGET /v1/search/steam/292030?type=gameGET /v1/search/rmdb/9ff8970c-3d02-4c45-bd24-43891467470b?type=gameThe 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.
The games library
Section titled “The games library”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:plannedis want to play,in_progressplaying,completedplayed;on_holdanddroppedas for a show. A game is neverup_to_date.owned: the member’s collection holds a copy (their own, a store sync, an import).ratingis present only when the credential holdsratings:read;nullwhen the game is not rated.playis the current playthrough: the replay under way, else the latest one the member did not stop.nulluntil a play is logged.platformslists each platform once, as the app’s Stats and library filter show it:keyis the catalogue entry, so PC appears once whatever RMDB ids the play names.idsholds those ids, in the play’s order, and is whatplatform_idstakes on a write. An id Refract cannot identify yet comes on its own, withkeyandnamenull.started_onandfinished_onare 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
Section titled “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 with detail not_in_library).
PUT /v1/games/library/5d7c1e2a-0b3f-4c8d-9e61-7a2f4b9c0d35/playAuthorization: Bearer rfk_…Content-Type: application/json
{ "playtime_minutes": 2800, "progress_percent": 70, "platform_ids": ["052a4690-4e20-4a04-988e-c0454b92fbfa"] }playtime_minutesis 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 noIdempotency-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_minutesand 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_entryis read only on a game with no play time yet. platform_idsreplaces the list: to keep a platform, send theidsyou read on it.run_numberpicks another playthrough; a number the member never played answersCONFLICTwithdetailunknown_run. Bringing a replay to 100 %, or giving it afinished_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
Section titled “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 isactive; a replay isactivewhile under way,completedonce finished,stoppedwhen the member stopped it. Start and stop replays in the app.GET /v1/games/sessions: the play history, oldest first. Each session carriesplayed_aton the member’s calendar and theminutesdated then;sourceislogged(the member logged it, in the app or through the API) orplatform(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 itsplaytime_minutes: Refract never makes up a day for it.
Ratings and lists
Section titled “Ratings and lists”GET /v1/ratings/games, andPUTorDELETE /v1/ratings/games/{id}with{ "value": 9 }, as for a movie.GET /v1/lists/{id}/gameslists a list’s games in its order;PUTorDELETE /v1/lists/{id}/games/{game_id}adds or removes one.PUT /v1/lists/{id}/orderorders the list’s shows and movies; its games keep their place after them. A list’sitem_countcounts every item, games included.
Syncing games
Section titled “Syncing games”Add include=games to the change feed:
GET /v1/changes?cursor=…&include=gamestype |
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.