Skip to content
GAMETOME
Public API

API for developers

Read public GameTome profiles, libraries and lists from your site, a bot or an app. No key and no sign-up needed.

How it works

  • Read-only JSON. It returns only what anyone can see on a public profile without signing in.
  • Up to 60 requests per minute per IP address, and 1200 per minute for everyone together. Beyond that, the response is 429 with a Retry-After header.
  • Responses are cached for 5 minutes, so a change can take that long to show up.
  • CORS is open: you can call it straight from the browser, from any site. Preflight OPTIONS requests answer 204.
  • Existing fields never get renamed: new ones are added.

Endpoints

  • GET/api/v1/users/{username}

    The profile: games per status, hours, average rating, followers.

  • GET/api/v1/users/{username}/library?status=COMPLETED&page=1

    The library, 100 games per page, last updated first (updatedAt, not the date you finished the game). Parameters: status (PLAYING, COMPLETED, DROPPED, BACKLOG, WISHLIST, ON_HOLD) and page, up to 1000. Every page carries page, perPage, total and hasMore.

  • GET/api/v1/users/{username}/lists

    The person's public lists, without the games: title, description, ranked, gameCount, likes and dates. Up to 200, last updated first.

  • GET/api/v1/lists/{id}

    A public list with up to 1000 games in order: every item has position, note and the game. Plus author, likes and ranked. The id is the last part of the list's address on the site.

Examples

GET/api/v1/users/{username}
curl https://gametome.app/api/v1/users/gametome_test
{
  "username": "gametome_test",
  "avatarUrl": null,
  "joinedAt": "2026-08-20T10:12:00.000Z",
  "url": "https://gametome.app/users/gametome_test",
  "followers": 3,
  "following": 5,
  "stats": {
    "total": 42, "playing": 2, "completed": 25,
    "backlog": 10, "wishlist": 4, "dropped": 1, "onHold": 0,
    "hoursPlayed": 812.5, "averageRating": 3.9
  }
}
GET/api/v1/users/{username}/library
curl "https://gametome.app/api/v1/users/gametome_test/library?status=COMPLETED&page=1"
{
  "page": 1,
  "perPage": 100,
  "total": 25,
  "hasMore": false,
  "items": [
    {
      "game": {
        "id": "clx1", "igdbId": 1942, "title": "The Witcher 3",
        "slug": "the-witcher-3", "coverUrl": null,
        "releaseDate": "2015-05-19T00:00:00.000Z",
        "url": "https://gametome.app/games/clx1"
      },
      "status": "COMPLETED",
      "rating": 4.5,
      "review": "Finished it twice.",
      "reviewHasSpoilers": false,
      "hoursPlayed": 120,
      "startedAt": "2026-02-10",
      "completedAt": "2026-03-02T00:00:00.000Z",
      "updatedAt": "2026-03-02T18:40:00.000Z",
      "tags": ["rpg"]
    }
  ]
}
GET/api/v1/lists/{id}
curl https://gametome.app/api/v1/lists/clst1
{
  "id": "clst1",
  "title": "My RPGs",
  "description": null,
  "ranked": true,
  "author": "gametome_test",
  "likes": 12,
  "createdAt": "2026-02-01T09:00:00.000Z",
  "updatedAt": "2026-03-10T11:20:00.000Z",
  "url": "https://gametome.app/lists/clst1",
  "items": [
    { "position": 1, "note": "The best one.", "game": { "id": "clx1", "title": "The Witcher 3" } }
  ]
}

Errors

Errors look like { "error": "CODE" }: USER_NOT_FOUND and LIST_NOT_FOUND (404), INVALID_STATUS (400), RATE_LIMITED (429), INTERNAL_ERROR (500). Private profiles and lists, and banned accounts, answer 404 as if they did not exist.