Getting started

Requests

Every request except /v1/version and /v1/status carries an API key in the Authorization header. Keys are never accepted in the address, because addresses end up in logs.

GET /v1/printings?language=ja&rarityGroup=special&limit=25 HTTP/1.1
Host: api.poplextcg.com
Authorization: Bearer <api-key>
Accept: application/json

• Every response carries an X-Request-Id header. Quote it when you contact support.
• Read responses carry an ETag. Send it back in If-None-Match to get 304 Not Modified when nothing changed.
• Responses are not cached by intermediaries.

There are no test keys and no sandbox: the Free plan is the way to try the API.

A machine-readable description of version 1 (OpenAPI 3.1) is published as openapi.json.

Endpoints

A printing is addressed by its public id, for example pkm-ja-s10p-021 (Pokémon, Japanese, set S10P, number 021), or by its UUID. A card groups the printings that share the same rules and artwork identity. /v1/sets lists the sets, so a client can see which sets the catalog holds and look a set up by its printed code.

Example

A printing in full (fields abridged):

GET /v1/printings/pkm-ja-s10p-021 HTTP/1.1
Host: api.poplextcg.com
Authorization: Bearer <api-key>

200 OK  (abridged)
{
  "publicId": "pkm-ja-s10p-021",
  "language": "ja",
  "name": "グレイシア",
  "collectorNumber": "021",
  "set": { "code": "S10P", "name": "スペースジャグラー" },
  "rarity": { "code": "uncommon", "group": "uncommon", "basis": "source" },
  "kind": "pokemon",
  "pokemon": [ { "dexNumber": 471, "slug": "glaceon", "names": { "en": "Glaceon", "ja": "グレイシア" } } ],
  "englishName": { "name": "Glaceon", "basis": "linked-card" },
  "equivalents": [ { "printingId": "pkm-en-swsh10-038", "language": "en", "relationship": "language_counterpart" } ],
  "variants": [ { "variantKey": "normal-standard", "finish": "normal", "edition": "standard", "stamp": null, "isDefault": true } ],
  "externalIds": { "catalog": "S10P-021" },
  "meta": { "rarityGroupVersion": "rarity-groups-v3" }
}

Lists, filters and paging

List responses have data, page (limit, hasMore, nextCursor) and meta. Lists stay compact: Pokémon, illustrators, English names and equivalents appear on the detail routes only.

English names and their basis

Japanese cards carry an englishName of the form { name, basis }, or null when no English name is recorded (a few Japan-only cards have none). The basis tells you how reliable the name is.

Language equivalents

A printing detail lists its equivalents: the printings of the same card in another language, each with printingId, setCode, collectorNumber, name and language. A Japanese printing can have one English counterpart; an English printing can have several Japanese ones. The list is empty when no link is recorded. Links are recorded only after review.

Finishes and editions

Every printing carries variants: the finishes and editions in which it exists, each with variantKey, finish, edition, stamp and isDefault. The default variant comes first and exactly one variant is the default. finish is currently normal, reverse, holo or metal, edition is standard or jumbo, and stamp is text such as set-logo or staff (several stamps are joined with +), or null. The values are open vocabularies, so clients should tolerate new ones.

A null finish, edition or stamp means unknown or none, never "normal". Printings from the official Japanese site carry no finish information yet, so their single variant has null in all three fields. First editions are not distinguished yet.

IDs in other catalogs

A printing that has an ID in an external catalog carries it as externalIds.catalog (for example sv10-064, or S10P-021 for a Japanese printing). The key is absent when no such ID is recorded, and externalIds is then an empty object. The value is the external catalog's own ID; Poplex does not vouch for it beyond the link.

Rarity groups

Each printing keeps its own rarity code, name, rank and symbol, and adds a group so that clients can compare rarities across languages. The mapping is versioned (rarity-groups-v3 since 1.8.0); meta.rarityGroupVersion tells you which one a response used.

Every non-null rarity also carries basis: source when a data source states the rarity, or printed-mark when Poplex read it from the mark printed on the card scan (a circle, diamond or star, counted as the common, uncommon and rare groups; a star does not tell a holo card from a non-holo one). Clients should tolerate new basis values.

rarity is null when no rarity is recorded for the printing. Many modern Japanese cards print a rarity letter only for the higher rarities: a plain Common, Uncommon or Rare carries none, so neither the card nor our sources give a value and the field stays null. Poplex does not guess a rarity.

Artists

Every credit on a card is linked to one artist record. Artist ids are slugs such as danciao or mitsuhiro-arita. Card and printing details list their credits in credit order as illustrators, each with a slug and a name.

• GET /v1/illustrators lists artists with cardCount, printingCount and languages (all languages together) and a kind: person, team (a studio or an art team), joint (a credit that names two artists as one) or label (a role word that is not a name; hidden unless includeLabels=true). q searches the name, the id and other spellings, for example the name in another script, with at least two characters. language keeps artists with a printing in that language. sort is name (the default) or cardCount. Paging works as for the other lists.
• GET /v1/illustrators/{illustratorId} returns one artist with releaseDateFirst, releaseDateLast and aliases. An old id keeps working: the answer is the current artist plus redirectedFrom. An unknown id is 404 with the code illustrator_not_found.
• GET /v1/printings?illustrator=danciao lists the printings of one artist. An unknown id is 404 illustrator_not_found, not an empty list.

Duplicates and spelling errors in the sources were merged after the printed credit was read on each card, so one artist is one id. Printing lists stay compact and do not carry credits; use the artist filter or the detail route.

GET /v1/illustrators?q=higuchi HTTP/1.1
Host: api.poplextcg.com
Authorization: Bearer <api-key>

200 OK  (abridged)
{
  "data": [
    { "slug": "megumi-higuchi", "name": "Megumi Higuchi", "kind": "person", "cardCount": 38, "printingCount": 38, "languages": [ "en", "ja" ] },
    { "slug": "shinji-higuchi", "name": "Shinji Higuchi", "kind": "person", "cardCount": 14, "printingCount": 14, "languages": [ "en", "ja" ] }
  ],
  "page": { "limit": 25, "hasMore": false, "nextCursor": null }
}

Errors

In version 1, every error would use the problem details format (application/problem+json, RFC 9457). Programs should act on code, not on the human-readable text.

Limits

Each plan has a monthly allowance of successful requests (see Pricing); it resets at 00:00 UTC on the first day of each calendar month. When it is used up, the API answers 429 with the quota_exceeded code; waiting a few seconds does not help. Quota headers on responses show the limit, the remaining requests and the reset time.

Separately, each API key has a short-window limit: 30 requests per 10 seconds on Free, 100 on Pro and 300 on Business, applied per key at a Cloudflare location. When it is exceeded the API answers 429 with the rate_limited code and a Retry-After header. These limits are approximate local protection, not a guaranteed global rate. Very fast bursts can also be refused with 429 before they reach the API. Whenever you receive 429, wait the number of seconds in the Retry-After header, use backoff and retry. Only successful responses count against the monthly allowance. See the Terms and Conditions for the full rules.

Images

Plans that include images return two image fields on every printing, in lists and on the detail route. image is the image exactly as its source supplied it, so its format and size vary from card to card. images gives fixed sizes that are easier to use in an app:

• Every size is a WebP file. The height follows the card's own shape, and each size reports its width, height, fileSizeBytes, mimeType and sha256.
• Images are never enlarged. A size wider than the source image is simply absent: English cards from a 600 px source have small and medium, and some older Japanese images have small only. small is always present when images is.
• placeholder.averageColor is the card's average colour as #rrggbb, so that a grid can paint a tile before the image arrives.
• images is null when the plan does not include images, when the printing has no image, or when the rights for the image's source do not allow it. Treat null as "no image", not as an error.

An abridged example:

"images": {
  "sizes": {
    "small": {
      "url": "https://images.poplextcg.com/c3/ja/pkm-ja-s10p-021/front/small/t1/64dcc662d19cbbac0232858911dbaebfb224855c23ef4b328c259081d244ace4.webp",
      "width": 240, "height": 330, "fileSizeBytes": 19070,
      "mimeType": "image/webp",
      "sha256": "64dcc662d19cbbac0232858911dbaebfb224855c23ef4b328c259081d244ace4"
    },
    "medium": {
      "url": "https://images.poplextcg.com/c3/ja/pkm-ja-s10p-021/front/medium/t1/e25b1a3b9fb93669cbd355f242c75085327f99ed6902caa483e4ccc3b1621fac.webp",
      "width": 480, "height": 660, "fileSizeBytes": 62470,
      "mimeType": "image/webp",
      "sha256": "e25b1a3b9fb93669cbd355f242c75085327f99ed6902caa483e4ccc3b1621fac"
    }
  },
  "placeholder": { "averageColor": "#7ab1b7" }
}

Download images straight from images.poplextcg.com; they do not pass through the API and do not count against your request allowance. Each file name contains the file's own SHA-256, so an address never changes meaning and can be cached for as long as you like. A key that does not include images receives image: null and images: null. See Card images.

Versions

Inside version 1 only additive changes are made: new fields and new endpoints. A breaking change ships as version 2 under /v2.

Coverage and known gaps

The catalog covers English and Japanese printings of the Pokémon Trading Card Game, with Japanese cards linked to their English counterparts where a reviewed link exists. Known gaps: Japanese sets released after SV10 (April 2025), including the Mega series, are not in the catalog yet; finish and edition are unknown for printings from the official Japanese site; a few hundred Japan-only cards have no English name; about half of the Japanese printings have no recorded rarity (rarity is null) and are in no rarity group; an image is not guaranteed for every printing, because availability depends on the rights for its source; some official-site Japanese cards have only the small size (162 px wide).