← Back to CheckMyGamesCheckMyGames 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.
| Parameter | In | Description |
|---|
| platform | query | Platform slug or id. Repeat it or comma-separate for several. |
| status | query | Ownership status. |
| progress | query | Play progress. Repeat it or comma-separate for several. |
| q | query | Free text search across the copy and the game. |
| tag | query | Only copies carrying this tag. |
| cursor | query | Opaque cursor returned as nextCursor by the previous page. |
| limit | query | Page size, 50 by default. |
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.
GET/games/{id}read
Read one copy
An id that belongs to another collection answers 404: the API never confirms that it exists.
| Parameter | In | Description |
|---|
| id required | path | The id of the copy. |
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.
| Parameter | In | Description |
|---|
| id required | path | The id of the copy. |
DELETE/games/{id}write
Remove a copy
Removes the copy and its tags. The canonical game record stays: other collections may share it.
| Parameter | In | Description |
|---|
| id required | path | The id of the copy. |
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.
| Parameter | In | Description |
|---|
| id required | path | |
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).
| Parameter | In | Description |
|---|
| id required | path | |
PATCH/games/{id}/valuationwrite
Set the value by hand
Overrides the estimate everywhere. Send manualValue: null to go back to the estimate.
| Parameter | In | Description |
|---|
| id required | path | |
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.
GET/tagsread
List your tags
Every tag in your collection with how many copies carry it.
GET/collectionsread
Index of the public collections on this instance
Public collections only. Private ones do not appear, not even as a count.
GET/openapi.jsonno key
This document
The only endpoint that needs no API key.
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.
| Parameter | In | Description |
|---|
| q required | query | At least two characters. English or Spanish title. |
| platform | query | Only games released on this platform, by slug or id. |
| limit | query | |
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.
| Parameter | In | Description |
|---|
| q required | query | At least two characters. |
| platform | query | Narrow the search to one platform, by slug or id. |
data
Statistics and export.
GET/statsread
Collection statistics
The same figures as the showcase footer, plus the breakdown per platform. Cached for ten minutes.
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.
| Parameter | In | Description |
|---|
| format | query | json by default. |
schemas
The objects the endpoints send and receive. The full definition, with every constraint, is in the OpenAPI document.
Error
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