# Reference lists

> Every closed vocabulary the API uses — locales, currencies, print regions, conditions, printings, graders, price variants and bases, change kinds, image faces and sizes — in one response.

- **Endpoint**: `GET /v1/reference`
- **Cost**: free, no key needed, cached for a day
- **Minimum plan**: free
- **Cache-Control**: `public, max-age=86400`

Source: https://pokemontcgapi.com/docs/api/reference/lists

No key yet? One call gets you one: `POST /v1/accounts/free` with an `Idempotency-Key` header and your email address returns a working key in the response. Keep the original Idempotency-Key and body for response replay for up to 24 hours, under the conditions in the quickstart. The trial is 800 credits over 30 days once the address is confirmed, no card; paid plans start at 29 € a month. See the [quickstart](https://pokemontcgapi.com/docs/quickstart) and the [pricing](https://pokemontcgapi.com/pricing).

One route, one object, no key: these are the values the schema accepts, so a filter built from them is never rejected as unsupported. Fetch it once at boot, not once per render — it is served with `public, max-age=86400`.

The printed vocabularies — rarity, supertype, energy types — are not lists here, because they are values read off each card, not enumerations of the schema. They are on every card object as `rarity`, `supertype` and `types`, and a query such as `q=rarity:"Double Rare"` matches them as printed.

## Headers

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `If-None-Match` | string | — | Send back the `ETag` you stored. The API returns a strong ETag on every catalogue response, and a 304 is a header exchange: no body, no database row read. |

## Example request

**curl**

```bash
curl -s "https://api.pokemontcgapi.com/v1/reference" \
  -H "X-Api-Key: $PTCG_API_KEY"
```

**TypeScript**

`request.ts`

```ts
const url = new URL("https://api.pokemontcgapi.com/v1/reference");

const res = await fetch(url, {
  headers: { "X-Api-Key": process.env.PTCG_API_KEY ?? "" },
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message} (${error.request_id})`);
}

const { data, meta } = await res.json();
```

**Python**

`request.py`

```python
import os, httpx

res = httpx.get(
    "https://api.pokemontcgapi.com/v1/reference",
    headers={"X-Api-Key": os.environ["PTCG_API_KEY"]},
)
res.raise_for_status()
payload = res.json()
```

## Example response

`200 OK` · `Cache-Control: public, max-age=86400`

`response.json`

```json
{
  "data": {
    "locales": [
      "en",
      "ja",
      "zh",
      "fr",
      "de",
      "es",
      "it",
      "pt",
      "ko"
    ],
    "currencies": [
      "EUR",
      "USD",
      "GBP",
      "JPY"
    ],
    "print_regions": [
      "WEST",
      "JP",
      "CN",
      "KR"
    ],
    "conditions": [
      "MINT",
      "NEAR_MINT",
      "EXCELLENT",
      "GOOD",
      "LIGHT_PLAYED",
      "PLAYED",
      "POOR"
    ],
    "printings": [
      "NORMAL",
      "HOLOFOIL",
      "REVERSE_HOLO",
      "FIRST_EDITION",
      "FIRST_EDITION_HOLOFOIL"
    ],
    "grading_companies": [
      "PSA",
      "BGS",
      "CGC",
      "SGC",
      "ACE",
      "TAG"
    ],
    "price_variants": [
      "LOW",
      "MARKET",
      "TREND",
      "AVG_1D",
      "AVG_7D",
      "AVG_30D",
      "MEDIAN_GRADED",
      "INDEX"
    ],
    "price_bases": [
      "SOLD",
      "ASKING",
      "GUIDE",
      "DERIVED"
    ],
    "change_kinds": [
      "CARD",
      "SET",
      "SEALED",
      "PRICE",
      "IMAGE"
    ],
    "image_faces": [
      "FRONT",
      "BACK",
      "ART",
      "LOGO",
      "SYMBOL"
    ],
    "image_sizes": [
      "SMALL",
      "NORMAL",
      "LARGE"
    ]
  }
}
```