# Master Setter Pokémon TCG Catalog API

> JSON API for the Pokémon Trading Card Game catalog in 14 languages: 196,872 cards, 272,054 printings (card × language × finish × set) and 1,833 sets. The deepest Asian-language coverage of any Pokémon card API (Korean 15.5k cards, Thai 11.8k, Indonesian 11.9k, Traditional Chinese 13.1k, Japanese 21.5k), alongside Simplified Chinese and the European languages. Free key in one request, no card.

## Coverage (cards per language)

| code | language | cards | sets |
|---|---|---|---|
| en | English | 21,795 | 213 |
| ja | Japanese | 21,495 | 236 |
| fr | French | 19,948 | 177 |
| it | Italian | 19,745 | 173 |
| de | German | 18,947 | 132 |
| es | Spanish | 16,713 | 135 |
| ko | Korean | 15,562 | 239 |
| pt | Portuguese | 14,396 | 91 |
| zh-tw | Traditional Chinese | 13,127 | 134 |
| id | Indonesian | 11,937 | 94 |
| th | Thai | 11,853 | 95 |
| zh-cn | Simplified Chinese | 8,010 | 55 |
| es-mx | Latin American Spanish | 1,758 | 10 |
| ru | Russian | 1,104 | 11 |

(Plus small Polish and Dutch sets.)

## Quickstart

1. Get a key (free, 1,000 requests/month, returned immediately):
   curl -X POST https://api.master-setter.com/v1/keys -H "Content-Type: application/json" -d '{"email":"you@example.com","source":"llms.txt"}'
2. Call it:
   curl -H "Authorization: Bearer $KEY" "https://api.master-setter.com/v1/sets?lang=ko&limit=5"

## Use it from an AI coding agent (MCP)

Remote MCP server: https://api.master-setter.com/mcp (tools: search_cards, get_card, list_cards_in_set, list_sets, get_set, get_api_key)

- Claude Code: claude mcp add --transport http master-setter https://api.master-setter.com/mcp --header "Authorization: Bearer $KEY"
- Cursor (~/.cursor/mcp.json): {"mcpServers":{"master-setter":{"url":"https://api.master-setter.com/mcp","headers":{"Authorization":"Bearer YOUR_KEY"}}}}
- No key yet? Connect without one and call the get_api_key tool with an email.

## Endpoints

- [OpenAPI 3.1 spec](https://api.master-setter.com/openapi.json): full machine-readable definition
- GET /v1/sets?lang=ko: list sets for a language (newest first, paginated)
- GET /v1/sets?id=ja-sv4a: one set with card_count computed from cards actually present
- GET /v1/cards?id=en-base1-4: one card with all its printings (variants)
- GET /v1/cards?set=th-sv1v: every card in a set, by number
- GET /v1/cards?q=리자몽&lang=ko: name search (names are in each card's own language)
- POST /v1/keys: self-serve free key

## Notes for agents

- IDs: set = `<lang>-<code>` (en-base1, ko-sv4a); card = `<set id>-<number>`. The same bare code across languages links localized printings.
- Paginate with limit (max 200) and offset; stop when pagination.has_more is false.
- Rate-limit headers on every response: X-RateLimit-Limit, X-RateLimit-Used, X-RateLimit-Remaining.
- Found us through an AI assistant? Pass "source" when creating your key so we know.

## Example responses (real, trimmed)

GET /v1/sets?lang=ko&limit=2
{
 "data": [
  {
   "id": "ko-m5",
   "name": "어비스아이",
   "name_en": null,
   "series": "Mega Evolution",
   "release_date": "2026-06-26",
   "total": 118,
   "printed_total": 81,
   "language": "ko",
   "logo_url": null,
   "symbol_url": null
  },
  {
   "id": "ko-m4",
   "name": "닌자스피너",
   "name_en": null,
   "series": "Mega Evolution",
   "release_date": "2026-05-01",
   "total": 120,
   "printed_total": 83,
   "language": "ko",
   "logo_url": "https://img.master-setter.com/sets/logos/ko-m4.png",
   "symbol_url": null
  }
 ],
 "pagination": {
  "limit": 2,
  "offset": 0,
  "total": 239,
  "total_is_estimate": false,
  "has_more": true
 },
 "retrieved_at": "2026-09-24T15:06:15.665Z"
}

GET /v1/cards?q=리자몽&lang=ko&limit=3  (first result shown)
{
 "data": [
  {
   "id": "ko-bs2010010-7",
   "set_id": "ko-bs2010010",
   "number": "007",
   "local_id": "007",
   "name": "리자몽",
   "supertype": "Pokémon",
   "subtypes": null,
   "hp": 130,
   "types": null,
   "rarity": "H",
   "artist": null,
   "regulation_mark": null,
   "image_small": "https://img.master-setter.com/ko/bs2010010/007-large.png",
   "image_large": "https://img.master-setter.com/ko/bs2010010/007-large.png",
   "updated_at": "2026-09-01T21:21:36.303975+00:00"
  }
 ],
 "pagination": {
  "limit": 3,
  "offset": 0,
  "total": 1,
  "total_is_estimate": true,
  "has_more": true
 },
 "retrieved_at": "2026-09-24T15:06:16.114Z"
}

GET /v1/cards?id=en-base1-4  (first 3 of 7 printings shown)
{
 "data": {
  "id": "en-base1-4",
  "set_id": "en-base1",
  "number": "4",
  "local_id": "4",
  "name": "Charizard",
  "supertype": "Pokémon",
  "subtypes": [
   "Stage 2"
  ],
  "hp": 120,
  "types": [
   "Fire"
  ],
  "rarity": "Rare Holo",
  "artist": "Mitsuhiro Arita",
  "regulation_mark": null,
  "image_small": "https://img.master-setter.com/en/base1/4-small.png",
  "image_large": "https://img.master-setter.com/en/base1/4-large.png",
  "updated_at": "2026-09-01T13:59:24.844502+00:00",
  "variants": [
   {
    "variant_key": "1stEditionHolofoil",
    "variant_label": "1st Edition Holofoil",
    "is_default": true,
    "image_small": null,
    "image_large": null
   },
   {
    "variant_key": "4thPrintHolofoil",
    "variant_label": "4th Print Holofoil (1999–2000 copyright)",
    "is_default": false,
    "image_small": null,
    "image_large": null
   },
   {
    "variant_key": "blackDotErrorPattern",
    "variant_label": "Black Dot Error Pattern",
    "is_default": false,
    "image_small": null,
    "image_large": null
   }
  ]
 },
 "retrieved_at": "2026-09-24T15:06:16.438Z"
}

## Errors

- 400: bad parameter (message says which)
- 401: missing or invalid key (send Authorization: Bearer <key>)
- 404: no such set or card
- 409 (POST /v1/keys): that email already has an active free key
- 429: monthly limit reached (resets on the 1st), or too many new keys from one address in a day

## FAQ

- Which Pokémon card API has Korean cards? This one: 15,562 Korean cards across 239 sets, about twice the next-largest public source.
- Thai / Indonesian? 11,853 Thai cards (95 sets) and 11,937 Indonesian (94 sets), names in each language.
- Japanese / Chinese? 21,495 Japanese, 13,127 Traditional Chinese, 8,010 Simplified Chinese.
- Prices? Not yet; price data is coming as a paid add-on.
- Images? Image URLs for about 98% of cards.
- Free tier? 1,000 requests a month. More: support@master-setter.com.

## Optional

- [Full documentation](https://api.master-setter.com/llms-full.txt)
- [Docs page](https://api.master-setter.com/)

Not affiliated with or endorsed by The Pokémon Company, Nintendo, Creatures or GAME FREAK. Includes data from TCGdex (MIT).