API for developers

Fetch the best covers, logos, icons and backgrounds for board games in a single request. By internal ID, BoardGameGeek or Tesera ID.

Get a key Documentation (OpenAPI)

Getting started

Sign up and create a key in settings.
Send the key in the Authorization: Bearer KEY header.
Call /api/v1/games/best and get image URLs.

Examples

Best assets by BGG ID

curl -H "Authorization: Bearer bgd_…" \
  "https://bggriddb.ru/api/v1/games/best?platform=bgg&ids=174430,167791&types=cover,logo,icon&aspect=1:1&lang=en"

{
  "success": true,
  "data": [
    { "id": "174430", "gameId": 12, "status": 200,
      "assets": {
        "cover": { "id": 345, "url": "https://…/o/cover/ab/….jpg", "variants": { "1024x1024": "https://…webp" }, "thumb": "https://…_300.webp", … },
        "logo":  { … }, "icon": { …, "ico": "https://…/i/….ico" }
      } }
  ]
}

All covers of a game

GET https://bggriddb.ru/api/v1/covers/game/12?aspects=1:1,2:3&styles=official&sort=score&limit=25
GET https://bggriddb.ru/api/v1/covers/by/bgg/174430?language=ru,none

Game relations: expansions, editions, series

The family is returned whole from the base game, even if you ask for an expansion. Build the tree from parentId; kind tells entries apart: base, expansion, pack, standalone, collection, edition, promo, fan, accessory. Series group standalone games of one line.

GET https://bggriddb.ru/api/v1/games/by/bgg/237182/family
GET https://bggriddb.ru/api/v1/series?q=unmatched
GET https://bggriddb.ru/api/v1/series/{id}

{
  "success": true,
  "data": {
    "rootId": 3,
    "root": { "id": 3, "kind": "base", "name": "Root", "seriesId": null, … },
    "nodes": [
      { "id": 26015, "kind": "expansion", "parentId": 3, "name": "Root: The Riverfolk Expansion", … },
      { "id": 29092, "kind": "pack", "parentId": 3, … }
    ],
    "series": null
  }
}

Upload a logo

curl -H "Authorization: Bearer bgd_…" -F game_id=12 -F style=white -F language=ru \
  -F file=@logo.png "https://bggriddb.ru/api/v1/logos"

Limits

By default 120 requests per minute and 5000 per day per key. For high-volume integrations contact us — there is a partner tier.

Asset types

Sizes, aspect groups and styles are available programmatically: GET /api/v1/meta/asset-types.

Content license

Content is uploaded by users and provided as is for non-commercial use. Credit the author (username) and link to the asset where possible.