Back to CheckMyGames

CheckMyGames API

Read and manage your video game collection.

Base URL

https://checkmy.games/api/v1

Authentication header

Authorization: Bearer gc_…

Error shape

{ "error": { "code": "…", "message": "…" } }

Every endpoint needs an API key sent as “Authorization: Bearer gc_…”. Keys are never accepted in the query string. A key only ever sees the collection of its owner, and the write scope is required for POST, PATCH and DELETE — it is never implied by read. Errors always come back as { "error": { "code", "message" } } with English messages.

Keys are created in the panel, under Settings (up to 5 per account). Each one carries its own scopes. Limits are per person, shared by all their keys: 120 requests per minute and 5000 writes per day, answered with 429 and a Retry-After header.

games

The copies in your collection.

GET/gamesread

List the games in your collection

Cursor paginated. Follow nextCursor until it comes back null; a page may be shorter than the limit and still have a next cursor. The q parameter runs the same weighted, accent-insensitive search as the showcase, over title, edition, region, tags, developer and notes.

ParameterInDescription
platformqueryPlatform slug or id. Repeat it or comma-separate for several.
statusqueryOwnership status.
progressqueryPlay progress. Repeat it or comma-separate for several.
qqueryFree text search across the copy and the game.
tagqueryOnly copies carrying this tag.
cursorqueryOpaque cursor returned as nextCursor by the previous page.
limitqueryPage size, 50 by default.
  • 200 A page of games.
  • 400 Invalid request: bad parameter, bad cursor, or an unknown field in the body.
  • 401 Missing or invalid API key.
  • 403 The API key lacks the scope this endpoint requires.
  • 429 Rate limit exceeded. The Retry-After header says how long to wait.
  • 500 Unexpected server error.
POST/gameswrite

Add a game to your collection

Send igdbId to pull the canonical record from IGDB (cover art and screenshots download in the background), gameId to reuse a record this instance already has, or manualTitle when IGDB does not know the game. Unknown fields are rejected.

Request body: GameInput

  • 201 The copy that was created.
  • 400 Invalid request: bad parameter, bad cursor, or an unknown field in the body.
  • 401 Missing or invalid API key.
  • 403 The API key lacks the scope this endpoint requires.
  • 409 That game, platform, region and edition are already in the collection.
  • 429 Rate limit exceeded. The Retry-After header says how long to wait.
  • 500 Unexpected server error.
GET/games/{id}read

Read one copy

An id that belongs to another collection answers 404: the API never confirms that it exists.

ParameterInDescription
id requiredpathThe id of the copy.
  • 200 The copy, with the canonical game record.
  • 400 Invalid request: bad parameter, bad cursor, or an unknown field in the body.
  • 401 Missing or invalid API key.
  • 403 The API key lacks the scope this endpoint requires.
  • 404 No such game in this collection.
  • 429 Rate limit exceeded. The Retry-After header says how long to wait.
  • 500 Unexpected server error.
PATCH/games/{id}write

Change a copy

Only the fields you send change. Server-computed fields are not accepted: campaignCompleted follows from progress, and the search index and the page cache refresh on their own.

ParameterInDescription
id requiredpathThe id of the copy.

Request body: GamePatch

  • 200 The copy after the change.
  • 400 Invalid request: bad parameter, bad cursor, or an unknown field in the body.
  • 401 Missing or invalid API key.
  • 403 The API key lacks the scope this endpoint requires.
  • 404 No such game in this collection.
  • 429 Rate limit exceeded. The Retry-After header says how long to wait.
  • 500 Unexpected server error.
DELETE/games/{id}write

Remove a copy

Removes the copy and its tags. The canonical game record stays: other collections may share it.

ParameterInDescription
id requiredpathThe id of the copy.
  • 200 The copy was removed.
  • 400 Invalid request: bad parameter, bad cursor, or an unknown field in the body.
  • 401 Missing or invalid API key.
  • 403 The API key lacks the scope this endpoint requires.
  • 404 No such game in this collection.
  • 429 Rate limit exceeded. The Retry-After header says how long to wait.
  • 500 Unexpected server error.
GET/games/{id}/valuationread

What a copy is worth

The estimated second-hand value of one copy in Spain: the figure, its range, the confidence and the monthly history. Identical copies share the estimate. “value” is the one that counts: a manual value overrides the estimate.

ParameterInDescription
id requiredpath
  • 200 The valuation.
  • 400 Invalid request: bad parameter, bad cursor, or an unknown field in the body.
  • 401 Missing or invalid API key.
  • 403 The API key lacks the scope this endpoint requires.
  • 404 No copy with that id in this collection.
  • 429 Rate limit exceeded. The Retry-After header says how long to wait.
  • 500 Unexpected server error.
POST/games/{id}/valuationwrite

Refresh the valuation now

Works the estimate out again and waits for the result. Takes a few seconds. If the estimate is less than an hour old it is returned as is. Limited per person per day (429 when spent).

ParameterInDescription
id requiredpath
  • 200 The fresh valuation.
  • 400 Invalid request: bad parameter, bad cursor, or an unknown field in the body.
  • 401 Missing or invalid API key.
  • 403 The API key lacks the scope this endpoint requires.
  • 404 No copy with that id in this collection.
  • 429 Rate limit exceeded. The Retry-After header says how long to wait.
  • 500 Unexpected server error.
PATCH/games/{id}/valuationwrite

Set the value by hand

Overrides the estimate everywhere. Send manualValue: null to go back to the estimate.

ParameterInDescription
id requiredpath
  • 200 The valuation after the change.
  • 400 Invalid request: bad parameter, bad cursor, or an unknown field in the body.
  • 401 Missing or invalid API key.
  • 403 The API key lacks the scope this endpoint requires.
  • 404 No copy with that id in this collection.
  • 429 Rate limit exceeded. The Retry-After header says how long to wait.
  • 500 Unexpected server error.

catalogue

Platforms, tags and the public index.

GET/platformsread

List the platform catalogue

The seeded catalogue of the instance, plus how many copies you own on each platform.

  • 200 The catalogue.
  • 400 Invalid request: bad parameter, bad cursor, or an unknown field in the body.
  • 401 Missing or invalid API key.
  • 403 The API key lacks the scope this endpoint requires.
  • 429 Rate limit exceeded. The Retry-After header says how long to wait.
  • 500 Unexpected server error.
GET/tagsread

List your tags

Every tag in your collection with how many copies carry it.

  • 200 The tags.
  • 400 Invalid request: bad parameter, bad cursor, or an unknown field in the body.
  • 401 Missing or invalid API key.
  • 403 The API key lacks the scope this endpoint requires.
  • 429 Rate limit exceeded. The Retry-After header says how long to wait.
  • 500 Unexpected server error.
GET/collectionsread

Index of the public collections on this instance

Public collections only. Private ones do not appear, not even as a count.

  • 200 The public index.
  • 400 Invalid request: bad parameter, bad cursor, or an unknown field in the body.
  • 401 Missing or invalid API key.
  • 403 The API key lacks the scope this endpoint requires.
  • 429 Rate limit exceeded. The Retry-After header says how long to wait.
  • 500 Unexpected server error.
GET/openapi.jsonno key

This document

The only endpoint that needs no API key.

  • 200 The OpenAPI 3.1 document.

igdb

The cached IGDB proxy used to add games.

GET/catalogueread

Search the games this instance already has

Try this first when adding a game: it is instant and does not count against the daily IGDB search limit. Send the gameId of a result to POST /games. If the game is not here, use /search.

ParameterInDescription
q requiredqueryAt least two characters. English or Spanish title.
platformqueryOnly games released on this platform, by slug or id.
limitquery
  • 200 Catalogue games.
  • 400 Invalid request: bad parameter, bad cursor, or an unknown field in the body.
  • 401 Missing or invalid API key.
  • 403 The API key lacks the scope this endpoint requires.
  • 429 Rate limit exceeded. The Retry-After header says how long to wait.
  • 500 Unexpected server error.
GET/searchread

Search IGDB for a game to add

This searches IGDB, not your collection — use /games?q= for that. Try /catalogue first: new searches here count against a daily limit. Take the igdbId from a result and send it to POST /games.

ParameterInDescription
q requiredqueryAt least two characters.
platformqueryNarrow the search to one platform, by slug or id.
  • 200 Candidate games.
  • 400 Invalid request: bad parameter, bad cursor, or an unknown field in the body.
  • 401 Missing or invalid API key.
  • 403 The API key lacks the scope this endpoint requires.
  • 429 Rate limit exceeded. The Retry-After header says how long to wait.
  • 500 Unexpected server error.
  • 503 IGDB is not configured on this instance, or is not answering.

data

Statistics and export.

GET/statsread

Collection statistics

The same figures as the showcase footer, plus the breakdown per platform. Cached for ten minutes.

  • 200 The statistics.
  • 400 Invalid request: bad parameter, bad cursor, or an unknown field in the body.
  • 401 Missing or invalid API key.
  • 403 The API key lacks the scope this endpoint requires.
  • 429 Rate limit exceeded. The Retry-After header says how long to wait.
  • 500 Unexpected server error.
GET/exportread

Export the whole collection

Not paginated: this is the whole collection in one file. CSV is the only response in the API that is not JSON, because a CSV wrapped in JSON opens in no spreadsheet. Errors are still JSON.

ParameterInDescription
formatqueryjson by default.
  • 200 The export.
  • 400 Invalid request: bad parameter, bad cursor, or an unknown field in the body.
  • 401 Missing or invalid API key.
  • 403 The API key lacks the scope this endpoint requires.
  • 429 Rate limit exceeded. The Retry-After header says how long to wait.
  • 500 Unexpected server error.

schemas

The objects the endpoints send and receive. The full definition, with every constraint, is in the OpenAPI document.

Error

  • errorobjectrequired

GamePage

  • dataarrayrequired
  • limitintegerrequired
  • nextCursorstring | nullrequiredPass it back as ?cursor= for the next page. Null on the last page.

Game

  • idstringrequired
  • addedAtstring
  • updatedAtstring
  • titlestringThe title shown for this copy: localTitle if set, else the canonical game title.
  • valuationobject
  • gameobjectrequiredThe canonical record, shared by the whole instance.
  • platformobjectrequired
  • copyobjectrequiredYour copy: edition, condition, where it lives and what it cost.
  • tagsarrayrequired

GameInput

One of igdbId, gameId or manualTitle is required. Unknown fields are rejected.

  • igdbIdintegerFrom GET /search.
  • gameIdstringA canonical record this instance already has.
  • manualTitlestringFor a game IGDB does not know.
  • platformIdstringrequired
  • localTitlestring | nullThe title as printed on your copy. Shown everywhere and used for the valuation. Empty: the Spanish IGDB title when the owner uses Spanish, else the original.
  • editionstring | null
  • regionstring
  • subregionstring | nullPAL España, PAL UK…
  • formatstring
  • digitalStorestring | null
  • ownershipstring
  • completenessstring | null
  • conditionnumber | null
  • locationstring | null
  • protectiveCasestring | null
  • conservationNotestring | null
  • purchaseDatestring | null
  • purchasePricenumber | null
  • currencystring
  • storestring | null
  • isGiftboolean
  • progressstring
  • ratinginteger | null
  • hoursPlayednumber | null
  • favoriteboolean
  • visibilitystring
  • notesstring | null
  • tagsarray

GamePatch

Every field is optional; send only what changes. Unknown fields are rejected.

  • platformIdstring
  • localTitlestring | nullThe title as printed on your copy. Shown everywhere and used for the valuation. Empty: the Spanish IGDB title when the owner uses Spanish, else the original.
  • editionstring | null
  • regionstring
  • subregionstring | nullPAL España, PAL UK…
  • formatstring
  • digitalStorestring | null
  • ownershipstring
  • completenessstring | null
  • conditionnumber | null
  • locationstring | null
  • protectiveCasestring | null
  • conservationNotestring | null
  • purchaseDatestring | null
  • purchasePricenumber | null
  • currencystring
  • storestring | null
  • isGiftboolean
  • progressstring
  • ratinginteger | null
  • hoursPlayednumber | null
  • favoriteboolean
  • visibilitystring
  • notesstring | null
  • tagsarray

Platform

  • idstring
  • slugstring
  • namestring
  • shortNamestring
  • manufacturerstring
  • familystring | null
  • typestring
  • generationinteger | null
  • releaseYearinteger | null
  • igdbPlatformIdinteger | null
  • itemsOwnedinteger

CatalogueGame

  • gameIdstring
  • igdbIdinteger | null
  • titlestring
  • titleEsstring | null
  • yearinteger | null
  • developerstring | null
  • platformsarrayPlatform slugs.

SearchCandidate

  • igdbIdinteger
  • titlestring
  • yearinteger | null
  • developerstring | null
  • coverImageIdstring | null
  • platformsarray
  • kindstringgame: the game itself (also remakes, remasters, ports). extra: DLC, expansion, bundle, pack or edition of another game. fan: mod or fan fork.
  • ratingsintegerNumber of ratings on IGDB; a rough popularity signal. Results come sorted by relevance already.

ValuationSummary

Present on a copy once it has been valued. “value” is the manual value if set, else the estimate.

  • valuenumber | null
  • currencystring
  • estimatenumber | null
  • manualValuenumber | null
  • lownumber | null
  • highnumber | null
  • listingsintegerListings behind the estimate.
  • conditionUsedstring | null
  • sourcestring
  • confidencestring
  • computedAtstring | null

Valuation

The valuation of one copy. Identical copies share the estimate; a manual value overrides it.

  • itemIdstring
  • valuenumber | null
  • currencystring
  • estimatenumber | null
  • manualValuenumber | null
  • manualNotestring | null
  • lownumber | null
  • highnumber | null
  • listingsCountintegerListings behind the estimate.
  • conditionUsedstring | null
  • sourcestring
  • confidencestring
  • computedAtstring | null
  • nextAtstring | null
  • historyarray

Stats

  • totalsobject
  • byPlatformarray

Tag

  • namestring
  • colorstring | null
  • countinteger

Collection

  • slugstring
  • namestring
  • biostring | null
  • publicItemsinteger
  • createdAtstring
  • urlstring