### Sealed product object example (JSON)

Source: https://pokemontcgapi.com/docs/objects/sealed

Example response for a sealed product object, as returned by GET /v1/sealed and GET /v1/sealed/{id}. Shows all 15 fields, including id equal to sku, nullable fields like slug and pack_count, and the languages array.

```json
{
  "id": "SV2a-booster-box",
  "sku": "SV2a-booster-box",
  "slug": null,
  "name": "Pokemon Card 151 Booster Box",
  "kind": "BOOSTER_BOX",
  "set_code": "sv2a",
  "set_name": "Pokemon Card 151",
  "image_url": "https://media.rarebit.app/boxes/SV2a-booster-box-normal.webp",
  "release_date": "2023-06-16",
  "pack_count": null,
  "languages": [
    "ja"
  ],
  "index_eur": null,
  "last_price_at": "2026-06-23T01:24:42.794Z",
  "created_at": "2026-06-12T10:29:43.290Z",
  "updated_at": "2026-09-02T15:56:54.473Z"
}
```

--------------------------------

### Example request: curl

Source: https://pokemontcgapi.com/docs/api/sets/cards

Sends a GET request to /v1/sets/bs/cards with limit, include, and select parameters, using the X-Api-Key header.

```bash
curl -s -G "https://api.pokemontcgapi.com/v1/sets/bs/cards" \
  --data-urlencode "limit=2" \
  --data-urlencode "include=index" \
  --data-urlencode "select=id,name,number,rarity,index_eur" \
  -H "X-Api-Key: $PTCG_API_KEY"
```

--------------------------------

### Example response from GET /v1/prices/sources

Source: https://pokemontcgapi.com/docs/api/prices/sources

Shows the JSON response containing an array of price sources with fields: source, label, min_delay_hours, and is_own. The response includes a count of 7 sources.

```json
{
  "data": [
    {
      "source": "CARDMARKET",
      "label": "Cardmarket",
      "min_delay_hours": 24,
      "is_own": false
    },
    {
      "source": "CARDTRADER",
      "label": "CardTrader",
      "min_delay_hours": 24,
      "is_own": false
    },
    {
      "source": "COMMUNITY",
      "label": "Community-observed",
      "min_delay_hours": 0,
      "is_own": false
    },
    {
      "source": "EBAY",
      "label": "eBay",
      "min_delay_hours": 24,
      "is_own": false
    },
    {
      "source": "PRICECHARTING",
      "label": "PriceCharting",
      "min_delay_hours": 24,
      "is_own": false
    },
    {
      "source": "PTCG_INDEX",
      "label": "pokemontcgapi composite index",
      "min_delay_hours": 0,
      "is_own": true
    },
    {
      "source": "TCGPLAYER",
      "label": "TCGplayer",
      "min_delay_hours": 24,
      "is_own": false
    }
  ],
  "count": 7
}
```

--------------------------------

### GET /v1/prices/movers - Example JSON response

Source: https://pokemontcgapi.com/docs/api/prices/movers

The 200 OK response body returned for the example request, showing three gainers with their index values and metadata. The response is cached for 300 seconds.

```json
{
  "data": [
    {
      "card_id": "adv1-002",
      "name": "Weezing",
      "set_code": "adv1",
      "from": 7.23,
      "to": 7.23,
      "change_pct": 0,
      "currency": "EUR"
    },
    {
      "card_id": "adv1-003",
      "name": "Sceptile",
      "set_code": "adv1",
      "from": 21.56,
      "to": 21.56,
      "change_pct": 0,
      "currency": "EUR"
    },
    {
      "card_id": "adv1-006",
      "name": "Beautifly",
      "set_code": "adv1",
      "from": 6.73,
      "to": 6.73,
      "change_pct": 0,
      "currency": "EUR"
    }
  ],
  "meta": {
    "window": "90d",
    "from": "2026-06-04",
    "to": "2026-09-02",
    "direction": "gainers",
    "min_value": 5,
    "count": 3,
    "source": "PTCG_INDEX"
  }
}
```

--------------------------------

### orderBy parameter example

Source: https://pokemontcgapi.com/docs/pagination

Shows how to sort results by multiple keys, with a leading minus for descending order. The example sorts by release_date descending and name ascending.

```text
orderBy=-release_date,name
```

--------------------------------

### GET /v1/sets

Source: https://pokemontcgapi.com/docs/api/sets/list

Documentation for the GET /v1/sets endpoint, including query parameters, headers, and example request.

```APIDOC
## [GET] /v1/sets

### Description
Lists Pokémon TCG card sets with filtering, pagination, and sorting options.

### Method
GET

### Endpoint
https://api.pokemontcgapi.com/v1/sets

### Parameters
#### Query Parameters
- **q** (string) - Optional - Accent-insensitive substring match on the set name, or an exact `code` or `slug`.
- **series** (string) - Optional - Series slug, e.g. `base`. Sets whose series is unmapped match no value.
- **region** (string) - Optional - Print region: `WEST` (176 sets), `JP` (380) or `CN` (96), counted 2026-09-18. `KR` is accepted and matches 0 rows. Anything else is `INVALID_PARAMETER` with the accepted values in `details.supported`.
- **orderBy** (string) - Optional - Default: `-release_date`. One or more of `code`, `name`, `release_date`, `total`, `updated_at`. Tiebreaker is `code`.
- **limit** (integer) - Optional - Default: 50. Rows per page, 1 to 250. Above 250 you get `LIMIT_EXCEEDED` — follow `links.next` instead of raising it.
- **cursor** (string) - Optional - Opaque keyset cursor from `links.next`. Never construct one; it carries the sort order it was issued for and is rejected if `orderBy` changes mid-run.

#### Headers
- **X-Api-Key** (string) - Required - Your API key. `Authorization: Bearer <key>` is accepted as an alias.
- **If-None-Match** (string) - Optional - 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.

### Request Example
```
curl -s -G "https://api.pokemontcgapi.com/v1/sets" \
  --data-urlencode "region=JP" \
  --data-urlencode "limit=2" \
  -H "X-Api-Key: $PTCG_API_KEY"
```

### Response
#### Success Response (200)
Returns a paginated list of sets. The response includes an `ETag` header for caching.

#### Error Handling
- `INVALID_PARAMETER` - Returned for invalid `region` values, with accepted values in `details.supported`.
- `LIMIT_EXCEEDED` - Returned when `limit` exceeds 250. Follow `links.next` instead.
- `304 Not Modified` - Returned when `If-None-Match` matches the current `ETag`. No body is returned.
```

--------------------------------

### Example response for free key creation

Source: https://pokemontcgapi.com/docs/api/accounts/free

Example response from POST /v1/accounts/free with status 201 OK and Cache-Control: no-store. Only the key secret is shown; other account, key, and quota fields are omitted.

```json
{"data":{"key":{"secret":"ptcg_live_example"}}}

```

--------------------------------

### Example response for GET /v1/sets/{code}

Source: https://pokemontcgapi.com/docs/api/sets/get

Shows the JSON response for a successful request (200 OK). The response includes the set's id, code, slug, legacy_id, name, series, region, release_date, totals, ptcgo_code, symbol_url, logo_url, and updated_at.

```json
{
  "id": "bs",
  "code": "bs",
  "slug": "base",
  "legacy_id": "base1",
  "name": "Base",
  "series": "Base",
  "region": "WEST",
  "release_date": "1999-01-09",
  "total": 134,
  "printed_total": 102,
  "ptcgo_code": "BS",
  "symbol_url": null,
  "logo_url": "https://media.rarebit.app/sets/BASE/logo-normal.webp",
  "updated_at": "2026-08-26T17:47:39.900Z"
}
```

--------------------------------

### Example response: response.json

Source: https://pokemontcgapi.com/docs/api/sets/cards

Shows the JSON response for the example request, including data array with card objects, meta, and links.

```json
{
  "data": [
    { "id": "bs-1", "name": "Alakazam", "number": "1", "rarity": "Rare Holo", "index_eur": 48.83 },
    { "id": "bs-1s", "name": "Alakazam (1st Edition Shadowless)", "number": "1S", "rarity": "Rare Holo", "index_eur": 49.30 }
  ],
  "meta": { "limit": 2, "count": 2, "has_more": true },
  "links": { "next": "https://api.pokemontcgapi.com/v1/sets/bs/cards?include=index&select=id%2Cname%2Cnumber%2Crarity%2Cindex_eur&limit=2&cursor=eyJrIjpbMSwiMVMiXSwiaWQ..." }
}
```

--------------------------------

### Example response for get artist

Source: https://pokemontcgapi.com/docs/api/artists/get

Example 200 OK response body for the get artist endpoint. Contains the artist's slug, name, and card_count.

```json
{ "slug": "mitsuhiro-arita", "name": "Mitsuhiro Arita", "card_count": 760 }
```

--------------------------------

### Example response for GET /v1/status

Source: https://pokemontcgapi.com/docs/api/status/get

Example 200 OK response from GET /v1/status. Contains catalog counts, ingest job timestamps and ages, and upstream contract status. The response is cached with Cache-Control: public, max-age=60.

```json
{
  "status": "ok",
  "catalog": {
    "sets": 651,
    "cards": 57450,
    "sealed": 2091,
    "artists": 402
  },
  "sources": [
    {
      "source": "refresh-catalog",
      "last_success_at": "2026-09-02T22:21:28.703Z",
      "age_hours": 0.9,
      "state": "fresh"
    },
    {
      "source": "refresh-index",
      "last_success_at": "2026-09-02T23:09:52.114Z",
      "age_hours": 0.1,
      "state": "fresh"
    },
    {
      "source": "refresh-prices",
      "last_success_at": "2026-09-02T23:07:22.204Z",
      "age_hours": 0.1,
      "state": "fresh"
    }
  ],
  "upstream": {
    "contract_ok": true,
    "error": null
  },
  "version": "dev"
}
```

--------------------------------

### Example response for /v1/sets

Source: https://pokemontcgapi.com/docs/api/sets/list

Example JSON response from the /v1/sets endpoint, showing two sets with metadata and pagination links. The response includes fields like id, code, slug, name, region, release_date, total, and logo_url.

```json
{
  "data": [
    {
      "id": "m6",
      "code": "m6",
      "slug": "storm-emeralda",
      "legacy_id": null,
      "name": "Storm Emeralda",
      "series": null,
      "region": "JP",
      "release_date": "2026-07-31",
      "total": 116,
      "printed_total": null,
      "ptcgo_code": null,
      "symbol_url": null,
      "logo_url": "https://media.rarebit.app/sets/m6/logo-normal.webp",
      "updated_at": "2026-08-26T17:47:39.900Z"
    },
    {
      "id": "m5",
      "code": "m5",
      "slug": "abyss-eye",
      "legacy_id": null,
      "name": "Abyss Eye",
      "series": null,
      "region": "JP",
      "release_date": "2026-05-22",
      "total": 118,
      "printed_total": null,
      "ptcgo_code": null,
      "symbol_url": null,
      "logo_url": "https://media.rarebit.app/sets/M5/logo-normal.webp",
      "updated_at": "2026-08-26T17:47:39.900Z"
    }
  ],
  "meta": { "limit": 2, "count": 2, "total_count": 379, "has_more": true },
  "links": { "next": "https://api.pokemontcgapi.com/v1/sets?limit=2&region=JP&cursor=eyJrIjpbIjIwMjYtMDUtMjJUMDA6MDA6MDAuMDAwWiJdLCJ..." }
}
```

--------------------------------

### List artists example response

Source: https://pokemontcgapi.com/docs/api/artists/list

Example response for a successful request, returning a single artist with a card count and metadata.

```json
{
  "data": [
    { "slug": "mitsuhiro-arita", "name": "Mitsuhiro Arita", "card_count": 760 }
  ],
  "meta": { "limit": 3, "count": 1, "total_count": 1, "has_more": false }
}

```

--------------------------------

### Price JSON example

Source: https://pokemontcgapi.com/docs/objects/price

Example of a Price object from the PTCG_INDEX source, showing a derived index price in EUR.

```json
{
  "source": "PTCG_INDEX",
  "variant": "INDEX",
  "basis": "DERIVED",
  "amount": 561.84,
  "currency": "EUR",
  "locale": "en",
  "condition": null,
  "printing": "HOLOFOIL",
  "grading": null,
  "as_of": "2026-08-26",
  "sample_n": 2,
  "provenance": "pokemontcgapi composite index"
}
```

--------------------------------

### Example response from /v1/sealed

Source: https://pokemontcgapi.com/docs/api/sealed/list

Example 200 OK response from the /v1/sealed endpoint. Includes data array, meta with pagination info, and links with a next cursor. The response is cached with Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=600.

```json
{
  "data": [
    {
      "id": "evolving-skies-6-booster-box-case",
      "sku": "evolving-skies-6-booster-box-case",
      "slug": "evolving-skies-6-booster-box-case",
      "name": "Evolving Skies 6 Booster Box Case",
      "kind": "BOOSTER_BOX",
      "set_code": "evs",
      "set_name": "Evolving Skies",
      "image_url": "https://media.rarebit.app/boxes/evolving-skies-6-booster-box-case-normal.webp",
      "release_date": null,
      "pack_count": 216,
      "languages": [],
      "index_eur": 15495,
      "last_price_at": "2026-09-02T00:38:55.286Z",
      "created_at": "2026-05-23T12:43:56.128Z",
      "updated_at": "2026-09-02T15:56:54.473Z"
    },
    {
      "id": "evolving-skies-booster-box",
      "sku": "evolving-skies-booster-box",
      "slug": "evolving-skies-booster-box",
      "name": "Evolving Skies Booster Box",
      "kind": "BOOSTER_BOX",
      "set_code": "evs",
      "set_name": "Evolving Skies",
      "image_url": "https://media.rarebit.app/boxes/evolving-skies-booster-box-normal.webp",
      "release_date": null,
      "pack_count": 36,
      "languages": [],
      "index_eur": 1750,
      "last_price_at": "2026-09-02T00:36:37.317Z",
      "created_at": "2026-05-23T12:43:56.069Z",
      "updated_at": "2026-09-02T15:56:54.473Z"
    }
  ],
  "meta": {
    "limit": 2,
    "count": 2,
    "total_count": 3,
    "has_more": true
  },
  "links": {
    "next": "https://api.pokemontcgapi.com/v1/sealed?cursor=eyJrIjpbbnVsbF0sImlkIjoiZXZvbHZpbmctc2tpZXMtYm9vc3Rlci1ib3giLCJzIjoicmVsZWFzZV9kYXRlOmRlc2Msc2t1OmFzYyJ9&kind=BOOSTER_BOX&limit=2&q=evolving+skies"
  }
}
```

--------------------------------

### Example response: 200 OK for /v1/changes

Source: https://pokemontcgapi.com/docs/api/changes/list

The JSON body returned by the example request. It shows the data array with two INSERT operations, pagination meta (next_since, watermark, oldest_available, behind), and the links.next URL to follow for more pages.

```json
{
  "data": [
    {
      "id": 1,
      "kind": "SET",
      "entity_id": "sv2a",
      "op": "INSERT",
      "version": 1,
      "changed_at": "2026-09-02T12:39:35.894Z"
    },
    {
      "id": 2,
      "kind": "SET",
      "entity_id": "svln",
      "op": "INSERT",
      "version": 1,
      "changed_at": "2026-09-02T12:39:35.894Z"
    }
  ],
  "meta": {
    "count": 2,
    "has_more": true,
    "next_since": 2,
    "watermark": 116242,
    "oldest_available": 1,
    "behind": 116240
  },
  "links": {
    "next": "https://api.pokemontcgapi.com/v1/changes?limit=2&since=2"
  }
}
```

--------------------------------

### Reference list response JSON

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

Example response from GET /v1/reference with status 200 OK and Cache-Control: public, max-age=86400. Contains all closed vocabularies: locales, currencies, print regions, conditions, printings, grading companies, price variants, price bases, change kinds, image faces, and image sizes.

```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"
    ]
  }
}
```

--------------------------------

### GET /v1/prices/movers - Example curl request

Source: https://pokemontcgapi.com/docs/api/prices/movers

Lists the top price movers over a 90-day window with a minimum value of 5 EUR and a limit of 3, using an X-Api-Key header. Replace $PTCG_API_KEY with your actual key.

```bash
curl -s -G "https://api.pokemontcgapi.com/v1/prices/movers" \
  --data-urlencode "window=90d" \
  --data-urlencode "min_value=5" \
  --data-urlencode "limit=3" \
  -H "X-Api-Key: $PTCG_API_KEY"
```

--------------------------------

### Batch Prices Example Response (JSON)

Source: https://pokemontcgapi.com/docs/api/prices/batch

Example 200 OK response for the batch price endpoint. Includes an index with EUR average and per-locale data, plus quotes from CARDMARKET, CARDTRADER, and TCGPLAYER for each requested card.

```json
{
  "data": [
    {
      "card_id": "bs-4",
      "index": {
        "eur": 556.23,
        "as_of": "2026-09-02",
        "sample_n": 16,
        "by_locale": [
          {
            "locale": "en",
            "printing": null,
            "eur": 556.23,
            "as_of": "2026-09-02",
            "sample_n": 16
          },
          {
            "locale": "fr",
            "printing": null,
            "eur": 900.58,
            "as_of": "2026-09-02",
            "sample_n": 3
          },
          {
            "locale": "de",
            "printing": null,
            "eur": 399.95,
            "as_of": "2026-09-02",
            "sample_n": 5
          },
          {
            "locale": "es",
            "printing": null,
            "eur": 1313.14,
            "as_of": "2026-09-02",
            "sample_n": 8
          },
          {
            "locale": "it",
            "printing": null,
            "eur": 400.64,
            "as_of": "2026-09-02",
            "sample_n": 11
          }
        ]
      },
      "quotes": [
        {
          "source": "CARDMARKET",
          "variant": "LOW",
          "basis": "ASKING",
          "amount": 599.9,
          "currency": "EUR",
          "locale": "en",
          "condition": "NEAR_MINT",
          "printing": null,
          "grading": null,
          "as_of": "2026-09-01",
          "sample_n": null,
          "provenance": "Cardmarket"
        },
        {
          "source": "CARDTRADER",
          "variant": "LOW",
          "basis": "ASKING",
          "amount": 368.67,
          "currency": "EUR",
          "locale": "en",
          "condition": "GOOD",
          "printing": null,
          "grading": null,
          "as_of": "2026-09-01",
          "sample_n": 14,
          "provenance": "CardTrader"
        },
        {
          "source": "TCGPLAYER",
          "variant": "LOW",
          "basis": "GUIDE",
          "amount": 510,
          "currency": "USD",
          "locale": "en",
          "condition": null,
          "printing": "HOLOFOIL",
          "grading": null,
          "as_of": "2026-07-30",
          "sample_n": null,
          "provenance": "TCGplayer"
        }
      ]
    },
    {
      "card_id": "bs-2",
      "index": {
        "eur": 181.35,
        "as_of": "2026-09-02",
        "sample_n": 16,
        "by_locale": [
          {
            "locale": "en",
            "printing": null,
            "eur": 181.35,
            "as_of": "2026-09-02",
            "sample_n": 16
          },
          {
            "locale": "fr",
            "printing": null,
            "eur": 350,
            "as_of": "2026-09-02",
            "sample_n": 1
          },
          {
            "locale": "de",
            "printing": null,
            "eur": 95.13,
            "as_of": "2026-09-02",
            "sample_n": 4
          },
          {
            "locale": "es",
            "printing": null,
            "eur": 240.64,
            "as_of": "2026-09-02",
            "sample_n": 5
          },
          {
            "locale": "it",
            "printing": null,
            "eur": 130.63,
            "as_of": "2026-09-02",
            "sample_n": 11
          }
        ]
      },
      "quotes": [
        {
          "source": "CARDMARKET",
          "variant": "LOW",
          "basis": "ASKING",
          "amount": 200,
          "currency": "EUR",
          "locale": "en",
          "condition": "NEAR_MINT",
          "printing": null,
          "grading": null,
          "as_of": "2026-09-01",
          "sample_n": null,
          "provenance": "Cardmarket"
        },
        {
          "source": "CARDTRADER",
          "variant": "LOW",
          "basis": "ASKING",
          "amount": 336.39,
          "currency": "EUR",
          "locale": "en",
          "condition": "NEAR_MINT",
          "printing": null,
          "grading": null,
          "as_of": "2026-09-01",
          "sample_n": 5,
          "provenance": "CardTrader"
        },
        {
          "source": "TCGPLAYER",
          "variant": "LOW",
          "basis": "GUIDE",
          "amount": 125,
          "currency": "USD",
          "locale": "en",
          "condition": null,
          "printing": "HOLOFOIL",
          "grading": null,
          "as_of": "2026-07-30",
          "sample_n": null,
          "provenance": "TCGplayer"
        }
      ]
    }
  ],
  "requested": 2,
  "found": 2
}
```

--------------------------------

### Example response for list series

Source: https://pokemontcgapi.com/docs/api/series/list

Example response for the series list request. Shows the data array with series objects, meta with pagination info, and a links.next cursor for the next page.

```json
{
  "data": [
    {
      "id": "sword-shield",
      "slug": "sword-shield",
      "name": "Sword & Shield",
      "set_count": 22
    },
    {
      "id": "ex",
      "slug": "ex",
      "name": "EX",
      "set_count": 20
    },
    {
      "id": "scarlet-violet",
      "slug": "scarlet-violet",
      "name": "Scarlet & Violet",
      "set_count": 18
    }
  ],
  "meta": {
    "limit": 3,
    "count": 3,
    "total_count": 17,
    "has_more": true
  },
  "links": {
    "next": "https://api.pokemontcgapi.com/v1/series?cursor=eyJrIjpbMThdLCJpZCI6InNjYXJsZXQtdmlvbGV0IiwicyI6InNldF9jb3VudDpkZXNjLHNsdWc6YXNjIn0&limit=3"
  }
}
```

--------------------------------

### Example response for a sealed product

Source: https://pokemontcgapi.com/docs/api/sealed/get

Example JSON response for a successful request. Shows the product fields including `id`, `sku`, `slug`, `name`, `kind`, `set_code`, `set_name`, `image_url`, `release_date`, `pack_count`, `languages`, `index_eur`, `last_price_at`, `created_at`, and `updated_at`.

```json
{
  "id": "evolving-skies-booster-box",
  "sku": "evolving-skies-booster-box",
  "slug": "evolving-skies-booster-box",
  "name": "Evolving Skies Booster Box",
  "kind": "BOOSTER_BOX",
  "set_code": "evs",
  "set_name": "Evolving Skies",
  "image_url": "https://media.rarebit.app/boxes/evolving-skies-booster-box-normal.webp",
  "release_date": null,
  "pack_count": 36,
  "languages": [],
  "index_eur": 1750,
  "last_price_at": "2026-09-02T00:36:37.317Z",
  "created_at": "2026-05-23T12:43:56.069Z",
  "updated_at": "2026-09-02T15:56:54.473Z"
}
```

--------------------------------

### Image object example (image.json)

Source: https://pokemontcgapi.com/docs/objects/image

Example JSON response for an Image object, showing the fields face, size, locale, url, image_source, width, and height. Note that width and height are null, and locale is null for language-neutral art.

```json
{
  "face": "FRONT",
  "size": "NORMAL",
  "locale": null,
  "url": "https://media.rarebit.app/cards/BASE/4-normal.webp",
  "image_source": "rarebit-media",
  "width": null,
  "height": null
}
```

--------------------------------

### Example response for /v1/cards/{id}/prices/stats

Source: https://pokemontcgapi.com/docs/api/prices/stats

Example response for the stats endpoint. Shows the summary fields (low, high, median, first, last, change_pct) and sample_n, which is the number of index points in the window. The response is cached with Cache-Control: private, max-age=300.

```json
{
  "data": {
    "window": "30d",
    "from": "2026-08-03",
    "to": "2026-09-02",
    "low": 431.41,
    "high": 431.41,
    "median": 431.41,
    "first": 431.41,
    "last": 431.41,
    "change_pct": 0,
    "sample_n": 1,
    "currency": "EUR"
  },
  "meta": {
    "card_id": "base1-4",
    "source": "PTCG_INDEX"
  }
}
```

--------------------------------

### GET /v1/sets

Source: https://pokemontcgapi.com/docs/api/sets/list

Documentation for the GET /v1/sets endpoint, including response format, error codes, and pagination details.

```APIDOC
## GET /v1/sets

### Description
Retrieves a paginated list of Pokémon TCG sets. Supports filtering by region and other query parameters, with cursor-based pagination.

### Method
GET

### Endpoint
/v1/sets

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of sets to return. Must be an integer between 1 and 250.
- **region** (string) - Optional - Filter sets by region (e.g., "JP").
- **orderBy** (string) - Optional - Sort key for the results. Must be a sortable field.
- **cursor** (string) - Optional - Pagination cursor for fetching the next page of results.

### Response
#### Success Response (200)
- **data** (array) - List of set objects.
  - **id** (string) - Unique identifier for the set.
  - **code** (string) - Set code.
  - **slug** (string) - URL-friendly slug.
  - **legacy_id** (string|null) - Legacy identifier, if any.
  - **name** (string) - Set name.
  - **series** (string|null) - Series name, if any.
  - **region** (string) - Region code (e.g., "JP").
  - **release_date** (string) - Release date in ISO format.
  - **total** (integer) - Total number of cards in the set.
  - **printed_total** (integer|null) - Printed total, if any.
  - **ptcgo_code** (string|null) - PTCGO code, if any.
  - **symbol_url** (string|null) - URL to the set symbol, if any.
  - **logo_url** (string) - URL to the set logo.
  - **updated_at** (string) - Last update timestamp in ISO format.
- **meta** (object) - Pagination metadata.
  - **limit** (integer) - Number of results returned.
  - **count** (integer) - Number of results in this page.
  - **total_count** (integer) - Total number of sets matching the query.
  - **has_more** (boolean) - Whether there are more pages.
- **links** (object) - Pagination links.
  - **next** (string) - URL for the next page, if available.

#### Response Example
```json
{
  "data": [
    {
      "id": "m6",
      "code": "m6",
      "slug": "storm-emeralda",
      "legacy_id": null,
      "name": "Storm Emeralda",
      "series": null,
      "region": "JP",
      "release_date": "2026-07-31",
      "total": 116,
      "printed_total": null,
      "ptcgo_code": null,
      "symbol_url": null,
      "logo_url": "https://media.rarebit.app/sets/m6/logo-normal.webp",
      "updated_at": "2026-08-26T17:47:39.900Z"
    },
    {
      "id": "m5",
      "code": "m5",
      "slug": "abyss-eye",
      "legacy_id": null,
      "name": "Abyss Eye",
      "series": null,
      "region": "JP",
      "release_date": "2026-05-22",
      "total": 118,
      "printed_total": null,
      "ptcgo_code": null,
      "symbol_url": null,
      "logo_url": "https://media.rarebit.app/sets/M5/logo-normal.webp",
      "updated_at": "2026-08-26T17:47:39.900Z"
    }
  ],
  "meta": { "limit": 2, "count": 2, "total_count": 379, "has_more": true },
  "links": { "next": "https://api.pokemontcgapi.com/v1/sets?limit=2&region=JP&cursor=eyJrIjpbIjIwMjYtMDUtMjJUMDA6MDA6MDAuMDAwWiJdLCJ..." }
}
```

### Error Handling
Every error body carries `error.code`, `error.message` and `error.request_id`. Switch on the code, never on the message.

#### Error Codes
- **401** `MISSING_API_KEY` - No `X-Api-Key` header and no bearer token on a route that requires one.
- **401** `INVALID_API_KEY` - The key does not match any account.
- **400** `INVALID_CURSOR` - The cursor is malformed, or was issued for a different `orderBy` than the one on this request.
- **400** `INVALID_PARAMETER` - A query parameter has the wrong type or an unsupported value — a non-integer `limit`, an unknown `lang`, an unknown `region`, a sort key that is not sortable.
- **400** `LIMIT_EXCEEDED` - `limit` is above 250, or a batch request carries more than 100 ids.
- **429** `QUOTA_EXCEEDED` - Trial credits, monthly credits or the daily cap are exhausted, and `details` says which: `daily_cap` with `retry_after_s` is the trial daily cap, which resets at midnight UTC; `renews: true` with `resets_at` is the monthly quota of a paid plan; `renews: false` is the trial allowance, which never comes back. `details.next_step` carries the plan, prices and owner action, or email verification when it unlocks the full trial.
- **403** `PLAN_REQUIRED` - The feature is outside the plan (photo recognition and movers require Growth), or the account subscription is canceled or suspended. `details.next_step` carries the owner action and handoff.
- **403** `TRIAL_EXPIRED` - The trial has ended: the account is on the trial and its 30 days from signup are over, and this route costs credits. `details.trial_expired_at` is the date, `details.trial_days` the length, and `details.next_step` the owner handoff. Zero-cost routes — `/v1/me`, `/v1/me/usage`, the key routes and `/v1/billing/checkout` — still answer.

### Notes
- Unknown query parameters are ignored silently. A typo in a filter name returns a full, unfiltered page rather than a 400. Check parameter names before concluding that a filter does nothing.
```

--------------------------------

### Example response for card prices

Source: https://pokemontcgapi.com/docs/api/prices/current

Example `200 OK` response for the prices endpoint. Contains an `index` object with per-locale EUR values and a `quotes` array with rows from sources like CARDMARKET, CARDTRADER, TCGPLAYER, EBAY, and PRICECHARTING, including graded medians.

```json
{
  "data": {
    "card_id": "base1-4",
    "index": {
      "eur": 556.23,
      "as_of": "2026-09-02",
      "sample_n": 16,
      "by_locale": [
        {
          "locale": "en",
          "printing": null,
          "eur": 556.23,
          "as_of": "2026-09-02",
          "sample_n": 16
        },
        {
          "locale": "fr",
          "printing": null,
          "eur": 900.58,
          "as_of": "2026-09-02",
          "sample_n": 3
        },
        {
          "locale": "de",
          "printing": null,
          "eur": 399.95,
          "as_of": "2026-09-02",
          "sample_n": 5
        },
        {
          "locale": "es",
          "printing": null,
          "eur": 1313.14,
          "as_of": "2026-09-02",
          "sample_n": 8
        },
        {
          "locale": "it",
          "printing": null,
          "eur": 400.64,
          "as_of": "2026-09-02",
          "sample_n": 11
        }
      ]
    },
    "quotes": [
      {
        "source": "CARDMARKET",
        "variant": "LOW",
        "basis": "ASKING",
        "amount": 599.9,
        "currency": "EUR",
        "locale": "en",
        "condition": "NEAR_MINT",
        "printing": null,
        "grading": null,
        "as_of": "2026-09-01",
        "sample_n": null,
        "provenance": "Cardmarket"
      },
      {
        "source": "CARDTRADER",
        "variant": "LOW",
        "basis": "ASKING",
        "amount": 1250.64,
        "currency": "EUR",
        "locale": "en",
        "condition": "NEAR_MINT",
        "printing": null,
        "grading": null,
        "as_of": "2026-09-01",
        "sample_n": 4,
        "provenance": "CardTrader"
      },
      {
        "source": "TCGPLAYER",
        "variant": "LOW",
        "basis": "GUIDE",
        "amount": 510,
        "currency": "USD",
        "locale": "en",
        "condition": null,
        "printing": "HOLOFOIL",
        "grading": null,
        "as_of": "2026-07-30",
        "sample_n": null,
        "provenance": "TCGplayer"
      },
      {
        "source": "EBAY",
        "variant": "MEDIAN_GRADED",
        "basis": "ASKING",
        "amount": 400,
        "currency": "USD",
        "locale": "en",
        "condition": null,
        "printing": null,
        "grading": {
          "company": "PSA",
          "score": "1"
        },
        "as_of": "2026-08-26",
        "sample_n": 7,
        "provenance": "eBay"
      },
      {
        "source": "PRICECHARTING",
        "variant": "MEDIAN_GRADED",
        "basis": "GUIDE",
        "amount": 20061.4,
        "currency": "USD",
        "locale": "en",
        "condition": null,
        "printing": null,
        "grading": {
          "company": "PSA",
          "score": "10"
        },
        "as_of": "2026-08-24",
        "sample_n": null,
        "provenance": "PriceCharting"
      }
    ]
  },
  "meta": {
    "quotes": 5,
    "delayed_hours": 0
  }
}
```

--------------------------------

### Example request: curl

Source: https://pokemontcgapi.com/docs/api/changes/list

Fetch the first page of changes with a limit of 2. Requires a valid API key in the X-Api-Key header. The response is documented on the same page and is shown in its own snippet.

```bash
curl -s -G "https://api.pokemontcgapi.com/v1/changes" \
  --data-urlencode "limit=2" \
  -H "X-Api-Key: $PTCG_API_KEY"
```

--------------------------------

### GET /v1/status with curl

Source: https://pokemontcgapi.com/docs/api/status/get

Sends a GET request to the /v1/status endpoint. The endpoint is free and does not require a key, but the example includes an X-Api-Key header. The response is cached with Cache-Control: public, max-age=60.

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

--------------------------------

### Create a free API key with curl

Source: https://pokemontcgapi.com/docs/api/accounts/free

Creates a free API key for a script by sending a POST request to /v1/accounts/free with an Idempotency-Key header and an email address. The response contains a working key secret; keep the Idempotency-Key and body for replay within 24 hours.

```bash
IDEM=$(uuidgen)
curl -s -X POST "https://api.pokemontcgapi.com/v1/accounts/free" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEM" \
  -d '{"email":"you@example.com"}'

```