# Quick start

> Make your first request in two minutes: get a key, search, fetch one item, and filter.

## Get a key

Reading needs no key, so the search below works as it is. For photos, contributing, and a higher rate limit: log in, open **Account → API keys**, and create one. Keys start with `bgdb_` and are shown once.

## Search

```bash
curl "https://tablearchive.dev/v1/items?q=wingspan" \
  -H "Authorization: Bearer $TA_KEY"
```
```javascript
const res = await fetch('https://tablearchive.dev/v1/items?q=wingspan', {
  headers: { Authorization: `Bearer ${process.env.TA_KEY}` },
})
const { total, items } = await res.json()
```
```python
import os, requests

res = requests.get(
    "https://tablearchive.dev/v1/items",
    params={"q": "wingspan"},
    headers={"Authorization": f"Bearer {os.environ['TA_KEY']}"},
)
items = res.json()["items"]
```

```json
{
  "total": 3,
  "items": [{
    "id": "9b2e…",
    "kind": "board_game",
    "name": "Wingspan",
    "slug": "wingspan",
    "data": { "year_published": 2019, "min_players": 1, "max_players": 5, "min_age": 10 },
    "image": { "thumb_url": "https://tablearchive.dev/v1/images/…/file?size=thumb&…" },
    "updated_at": "2026-10-04T18:21:07.000Z"
  }]
}
```

## Fetch one item

```bash
curl "https://tablearchive.dev/v1/items/wingspan" -H "Authorization: Bearer $TA_KEY"
```

The response adds `credits`, `terms`, `relations`, `images`, `external_ids`, and `provenance` (which source set each field). See [Items](https://tablearchive.dev/docs/items).

## Filter

Combine any of these on `GET /v1/items`:

| Parameter | Example | What it does |
|---|---|---|
| `q` | `catan` | Search names and descriptions |
| `kind` | `board_game` | One kind; see [Items](https://tablearchive.dev/docs/items#kinds) |
| `players` | `2` | Playable with exactly this many |
| `max_playtime` | `45` | At most this many minutes |
| `age` | `8` | Suitable for a player this old |
| `year` | `2019` | Published that year |
| `external_id` | `029877030712` | A barcode, Wikidata QID, or BGG ID |

Full list in [Search and filters](https://tablearchive.dev/docs/search).

> Building with an AI assistant? Give it [https://tablearchive.dev/llms.txt](https://tablearchive.dev/llms.txt). It describes this API in plain text.