{ "openapi": "3.1.2", "info": { "title": "Poplex TCG API", "version": "1.9.1", "summary": "Read-only Pokémon Trading Card Game catalog in English and Japanese.", "description": "Read-only catalog data for the Pokémon Trading Card Game in English and Japanese: sets, cards, printings, the finishes and editions of each printing, English names for Japanese cards (each with a basis label), language equivalents, rarity groups, the illustrators (artists) of the cards with a directory and a filter, the identifier of a printing in an external catalog where one exists, and image links in fixed WebP sizes on plans that include images.\n\n## Authentication\nEvery endpoint except `/version` and `/status` needs an API key in the header `Authorization: Bearer `. Keys are never accepted in the address. Keep the key on your server, never in a mobile app, a web page or a public repository.\n\n## Responses and errors\nJSON over HTTPS. Errors use `application/problem+json` (RFC 9457) with a stable `code` and a `requestId`. Every response carries `X-Request-Id` (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.\n\n## Lists and paging\nLists take `limit` (1 to 100, default 25; a larger value is rejected with 400 `invalid_parameter`) and the opaque `cursor` copied from `page.nextCursor`. A cursor is valid only for the same filters and sort that produced it.\n\n## Limits\nEach plan has a monthly allowance of successful requests, shared by all keys of an organization (Free 1,000, Pro 25,000, Business 100,000; see https://poplextcg.com/pricing/, where paid plans are marked as not yet available), which resets at 00:00 UTC on the first day of each month; when it is used up the API answers 429 `quota_exceeded`. Each key also has a short-window limit that is approximate and applied per location, so treat any 429 as a signal to back off; when it is exceeded the API answers 429 `rate_limited` with `Retry-After`. The headers `X-Poplex-Quota-Limit`, `X-Poplex-Quota-Remaining`, `X-Poplex-Quota-Reset` and `X-Poplex-Quota-Warning` show your position.\n\n## Images\nPlans that include images return `image` (the file exactly as its source supplied it) and `images` (WebP files 240, 480 and 720 px wide where the source allows, never enlarged, plus an average colour for placeholders). Download image files from `images.poplextcg.com`; they need no key and do not count against your allowance. Availability depends on the rights recorded for each source, and Pokémon names and artwork belong to their respective owners.\n\n## Versioning\nInside version 1 only additive changes are made: new fields and new endpoints. A breaking change ships as version 2.", "contact": { "name": "Poplex Support", "email": "support@poplextcg.com", "url": "https://poplextcg.com/docs/" }, "termsOfService": "https://poplextcg.com/terms/" }, "servers": [ { "url": "https://api.poplextcg.com/v1", "description": "Production" } ], "tags": [ { "name": "Meta", "description": "Version and status (no key needed)." }, { "name": "Catalog", "description": "Sets, cards, printings and illustrators." }, { "name": "Images", "description": "Image records and the canonical image of a printing." } ], "security": [ { "bearerApiKey": [] } ], "paths": { "/version": { "get": { "operationId": "getApiVersion", "summary": "API version", "description": "Returns the service name and status. No API key is needed.", "tags": [ "Meta" ], "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" }, { "$ref": "#/components/parameters/RequestIdHeader" } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/Cache-Control" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiVersion" } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [] } }, "/status": { "get": { "operationId": "getServiceStatus", "summary": "Service status", "description": "Liveness check; it touches no database. No API key is needed.", "tags": [ "Meta" ], "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" }, { "$ref": "#/components/parameters/RequestIdHeader" } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/Cache-Control" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceStatus" } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [] } }, "/sets": { "get": { "operationId": "listSets", "summary": "List sets", "description": "Lists sets with their code, language, printed total, total number of cards and release date. Filter by `game`, `language` and an exact, case-insensitive `code`; sort by `releaseDate` (newest first, the default) or `code`. Sets without a release date or code come last. A cursor is valid only for the filters and sort that produced it.", "tags": [ "Catalog" ], "parameters": [ { "$ref": "#/components/parameters/GameFilter" }, { "$ref": "#/components/parameters/LanguageFilter" }, { "name": "code", "in": "query", "required": false, "description": "Exact set code, case-insensitive. A code can exist in more than one language (for example `SV10` in English and Japanese).", "schema": { "type": "string", "minLength": 1 } }, { "name": "sort", "in": "query", "required": false, "description": "Order: `releaseDate` (newest first, default) or `code` (ascending). Ties are ordered by `publicId`. A cursor is valid only for the sort that produced it.", "schema": { "type": "string", "enum": [ "releaseDate", "code" ], "default": "releaseDate" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "$ref": "#/components/parameters/RequestIdHeader" } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Poplex-Quota-Limit": { "$ref": "#/components/headers/X-Poplex-Quota-Limit" }, "X-Poplex-Quota-Remaining": { "$ref": "#/components/headers/X-Poplex-Quota-Remaining" }, "X-Poplex-Quota-Reset": { "$ref": "#/components/headers/X-Poplex-Quota-Reset" }, "X-Poplex-Quota-Warning": { "$ref": "#/components/headers/X-Poplex-Quota-Warning" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetList" }, "examples": { "sets": { "summary": "Two sets with real public IDs (synthetic UUIDs); the second has no release date", "value": { "data": [ { "id": "3f1e2a40-7c1d-4a52-9d0e-5b6a7c8d9e01", "publicId": "pkm-en-sv10", "name": "Destined Rivals", "code": "sv10", "language": "en", "printedTotal": 182, "total": 244, "releaseDate": "2025-05-30", "isPromo": false }, { "id": "3f1e2a40-7c1d-4a52-9d0e-5b6a7c8d9e02", "publicId": "pkm-ja-20th", "name": "ポケットモンスターカードゲーム スターターパック", "code": "20th", "language": "ja", "printedTotal": 72, "total": null, "releaseDate": null, "isPromo": false } ], "page": { "limit": 25, "hasMore": false, "nextCursor": null }, "meta": { "rarityGroupVersion": "rarity-groups-v3" } } } } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/sets/{setId}": { "get": { "operationId": "getSet", "summary": "Get a set", "description": "Returns one set by UUID or stable public ID.", "tags": [ "Catalog" ], "parameters": [ { "$ref": "#/components/parameters/SetIdPath" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "$ref": "#/components/parameters/RequestIdHeader" } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Poplex-Quota-Limit": { "$ref": "#/components/headers/X-Poplex-Quota-Limit" }, "X-Poplex-Quota-Remaining": { "$ref": "#/components/headers/X-Poplex-Quota-Remaining" }, "X-Poplex-Quota-Reset": { "$ref": "#/components/headers/X-Poplex-Quota-Reset" }, "X-Poplex-Quota-Warning": { "$ref": "#/components/headers/X-Poplex-Quota-Warning" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Set" } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/cards/{cardId}": { "get": { "operationId": "getCard", "summary": "Get a card", "description": "Returns one card by UUID or `card:`, with its English name when one is recorded, its Pokémon and its illustrators. If the card's identity was superseded, the response is still 200 and describes the active card, together with a resolution record that shows what happened (the API never answers with an HTTP redirect).", "tags": [ "Catalog" ], "parameters": [ { "$ref": "#/components/parameters/CardIdPath" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "$ref": "#/components/parameters/RequestIdHeader" } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Poplex-Quota-Limit": { "$ref": "#/components/headers/X-Poplex-Quota-Limit" }, "X-Poplex-Quota-Remaining": { "$ref": "#/components/headers/X-Poplex-Quota-Remaining" }, "X-Poplex-Quota-Reset": { "$ref": "#/components/headers/X-Poplex-Quota-Reset" }, "X-Poplex-Quota-Warning": { "$ref": "#/components/headers/X-Poplex-Quota-Warning" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardDetail" }, "examples": { "japaneseSmoliv": { "summary": "Resolved card with bilingual species names (synthetic UUIDs)", "value": { "id": "16082260-3b03-4a05-a7f4-0ef92e3ec157", "publicId": "card:16082260-3b03-4a05-a7f4-0ef92e3ec157", "canonicalName": "ミニーブ", "kind": "pokemon", "game": "pokemon", "identityState": "active", "identityStrategy": "artwork-and-rules-concept-v2", "updatedAt": "2026-09-03T17:40:02.123456Z", "resolution": { "requestedIdentifier": "16082260-3b03-4a05-a7f4-0ef92e3ec157", "requestedCardId": "16082260-3b03-4a05-a7f4-0ef92e3ec157", "requestedPublicId": "card:16082260-3b03-4a05-a7f4-0ef92e3ec157", "resolvedCardId": "16082260-3b03-4a05-a7f4-0ef92e3ec157", "resolvedPublicId": "card:16082260-3b03-4a05-a7f4-0ef92e3ec157", "identityState": "active", "resolvedIdentityState": "active", "identityStrategy": "artwork-and-rules-concept-v2", "redirected": false }, "pokemon": [ { "dexNumber": 928, "slug": "smoliv", "isPrimary": true, "names": { "en": "Smoliv", "ja": "ミニーブ" } } ], "illustrators": [ { "slug": "yuka-morii", "name": "Yuka Morii" } ], "englishName": null } }, "japaneseGlaceon": { "summary": "Japanese card with linked-card English name (synthetic UUIDs)", "value": { "id": "16082260-3b03-4a05-a7f4-0ef92e3ec157", "publicId": "card:16082260-3b03-4a05-a7f4-0ef92e3ec157", "canonicalName": "グレイシア", "kind": "pokemon", "game": "pokemon", "identityState": "active", "identityStrategy": "artwork-and-rules-concept-v2", "updatedAt": "2026-09-03T17:40:02.123456Z", "resolution": { "requestedIdentifier": "16082260-3b03-4a05-a7f4-0ef92e3ec157", "requestedCardId": "16082260-3b03-4a05-a7f4-0ef92e3ec157", "requestedPublicId": "card:16082260-3b03-4a05-a7f4-0ef92e3ec157", "resolvedCardId": "16082260-3b03-4a05-a7f4-0ef92e3ec157", "resolvedPublicId": "card:16082260-3b03-4a05-a7f4-0ef92e3ec157", "identityState": "active", "resolvedIdentityState": "active", "identityStrategy": "artwork-and-rules-concept-v2", "redirected": false }, "pokemon": [ { "dexNumber": 471, "slug": "glaceon", "isPrimary": true, "names": { "en": "Glaceon", "ja": "グレイシア" } } ], "illustrators": [], "englishName": { "name": "Glaceon", "basis": "linked-card" } } } } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/printings": { "get": { "operationId": "listPrintings", "summary": "List printings", "description": "Lists printings (a numbered card in one set and language) with filters and cursor paging. Lists stay compact: Pokémon, illustrators, English names and equivalents appear on the detail route only. `name` is an exact, case-insensitive match on the printed name. `illustrator` (an illustrator slug from `GET /illustrators`) keeps the printings of cards credited to that illustrator; an unknown slug is 404 `illustrator_not_found`, never an empty list. On plans that include images, each item also carries `image` and `images`.", "tags": [ "Catalog" ], "parameters": [ { "name": "set", "in": "query", "required": false, "description": "Set UUID or public ID.", "schema": { "$ref": "#/components/schemas/CatalogEntityIdentifier" } }, { "name": "card", "in": "query", "required": false, "description": "Conceptual card UUID or 'card:' public ID (a superseded ID is NOT followed here; use getCard first).", "schema": { "$ref": "#/components/schemas/CardIdentifier" } }, { "$ref": "#/components/parameters/GameFilter" }, { "$ref": "#/components/parameters/LanguageFilter" }, { "name": "rarity", "in": "query", "required": false, "description": "Rarity code within the printing's own game and language.", "schema": { "type": "string" } }, { "name": "rarityGroup", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/RarityGroup" }, "description": "Filter by rarity group. `unrated` includes printings whose rarity is explicitly unrated or not mapped to a group; printings without a rarity are excluded from every group. A cursor is valid only for the group it was issued for." }, { "name": "collectorNumber", "in": "query", "required": false, "description": "Exact collector number (text).", "schema": { "type": "string" } }, { "name": "name", "in": "query", "required": false, "description": "Exact, case-insensitive match on the printed name.", "schema": { "type": "string" } }, { "name": "regulationMark", "in": "query", "required": false, "description": "Exact regulation mark.", "schema": { "type": "string" } }, { "name": "illustrator", "in": "query", "required": false, "description": "Illustrator slug (see `GET /illustrators`). A card with several credits matches any of them. An old or merged slug resolves to the current illustrator, and a cursor is then valid for the current slug. An unknown slug is 404 `illustrator_not_found`, not an empty list.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "minLength": 1 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order; prefix '-' for descending. Ordering is deterministic: ties are always broken by the stated tie-breaker column ascending, so a cursor never skips or repeats rows. ", "schema": { "type": "string", "enum": [ "publicId", "-publicId", "collectorNumber", "-collectorNumber", "name", "-name" ], "default": "publicId" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "$ref": "#/components/parameters/RequestIdHeader" } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Poplex-Quota-Limit": { "$ref": "#/components/headers/X-Poplex-Quota-Limit" }, "X-Poplex-Quota-Remaining": { "$ref": "#/components/headers/X-Poplex-Quota-Remaining" }, "X-Poplex-Quota-Reset": { "$ref": "#/components/headers/X-Poplex-Quota-Reset" }, "X-Poplex-Quota-Warning": { "$ref": "#/components/headers/X-Poplex-Quota-Warning" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintingList" }, "examples": { "sizedImages": { "summary": "One entitled printing with WebP sizes (synthetic fixture)", "value": { "data": [ { "id": "09262db8-96e9-5606-8b0b-af46de9e3549", "publicId": "pkm-ja-sv10-010", "cardId": "16082260-3b03-4a05-a7f4-0ef92e3ec157", "cardPublicId": "card:16082260-3b03-4a05-a7f4-0ef92e3ec157", "set": { "id": "3f1e2a40-7c1d-4a52-9d0e-5b6a7c8d9e01", "publicId": "sv10-ja", "name": "ロケット団の栄光", "code": "SV10" }, "game": "pokemon", "language": "ja", "collectorNumber": "010", "name": "ミニーブ", "regulationMark": "I", "rarity": { "code": "common", "name": "Common", "rank": null, "symbol": null, "group": "common", "basis": "source" }, "image": { "id": "aaaaaaaa-0000-4000-8000-000000000001", "printingId": "09262db8-96e9-5606-8b0b-af46de9e3549", "variantId": null, "role": "front", "isPrimary": true, "mimeType": "image/jpeg", "width": 748, "height": 1044, "fileSizeBytes": 123456, "sha256": "0000000000000000000000000000000000000000000000000000000000000000", "url": "https://images.poplextcg.com/example/source.jpg", "objectKey": "example/source.jpg" }, "updatedAt": "2026-09-03T17:40:02.123456Z", "images": { "sizes": { "small": { "url": "https://images.poplextcg.com/c3/ja/pkm-ja-sv10-010/front/small/t1/1111111111111111111111111111111111111111111111111111111111111111.webp", "width": 240, "height": 335, "fileSizeBytes": 12000, "mimeType": "image/webp", "sha256": "1111111111111111111111111111111111111111111111111111111111111111" }, "medium": { "url": "https://images.poplextcg.com/c3/ja/pkm-ja-sv10-010/front/medium/t1/2222222222222222222222222222222222222222222222222222222222222222.webp", "width": 480, "height": 670, "fileSizeBytes": 42000, "mimeType": "image/webp", "sha256": "2222222222222222222222222222222222222222222222222222222222222222" }, "large": { "url": "https://images.poplextcg.com/c3/ja/pkm-ja-sv10-010/front/large/t1/3333333333333333333333333333333333333333333333333333333333333333.webp", "width": 720, "height": 1005, "fileSizeBytes": 75000, "mimeType": "image/webp", "sha256": "3333333333333333333333333333333333333333333333333333333333333333" } }, "placeholder": { "averageColor": "#778899" } }, "variants": [ { "variantKey": "standard", "finish": null, "edition": null, "stamp": null, "isDefault": true } ], "externalIds": {} } ], "page": { "limit": 25, "hasMore": false, "nextCursor": null }, "meta": { "rarityGroupVersion": "rarity-groups-v3" } } } } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/printings/{printingId}": { "get": { "operationId": "getPrinting", "summary": "Get a printing", "description": "Returns one printing in full: set, rarity and rarity group, Pokémon, illustrators, `englishName` with its basis, language `equivalents`, and on plans that include images `image` and `images`.", "tags": [ "Catalog" ], "parameters": [ { "$ref": "#/components/parameters/PrintingIdPath" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "$ref": "#/components/parameters/RequestIdHeader" } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Poplex-Quota-Limit": { "$ref": "#/components/headers/X-Poplex-Quota-Limit" }, "X-Poplex-Quota-Remaining": { "$ref": "#/components/headers/X-Poplex-Quota-Remaining" }, "X-Poplex-Quota-Reset": { "$ref": "#/components/headers/X-Poplex-Quota-Reset" }, "X-Poplex-Quota-Warning": { "$ref": "#/components/headers/X-Poplex-Quota-Warning" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintingDetail" }, "examples": { "japaneseSmoliv": { "summary": "Japanese printing with English/Japanese species names (synthetic UUIDs)", "value": { "id": "09262db8-96e9-5606-8b0b-af46de9e3549", "publicId": "pkm-ja-sv10-010", "cardId": "16082260-3b03-4a05-a7f4-0ef92e3ec157", "cardPublicId": "card:16082260-3b03-4a05-a7f4-0ef92e3ec157", "set": { "id": "3f1e2a40-7c1d-4a52-9d0e-5b6a7c8d9e01", "publicId": "sv10-ja", "name": "ロケット団の栄光", "code": "SV10" }, "game": "pokemon", "language": "ja", "collectorNumber": "010", "name": "ミニーブ", "regulationMark": "I", "rarity": { "code": "common", "name": "Common", "rank": null, "symbol": null, "group": "common", "basis": "source" }, "image": null, "updatedAt": "2026-09-03T17:40:02.123456Z", "kind": "pokemon", "pokemon": [ { "dexNumber": 928, "slug": "smoliv", "isPrimary": true, "names": { "en": "Smoliv", "ja": "ミニーブ" } } ], "illustrators": [ { "slug": "yuka-morii", "name": "Yuka Morii" } ], "equivalents": [], "englishName": null, "meta": { "rarityGroupVersion": "rarity-groups-v3" }, "images": null, "variants": [ { "variantKey": "standard", "finish": null, "edition": null, "stamp": null, "isDefault": true } ], "externalIds": {} } }, "japaneseGlaceon": { "summary": "Japanese Glaceon with an English counterpart and name provenance (synthetic UUIDs)", "value": { "id": "09262db8-96e9-5606-8b0b-af46de9e3549", "publicId": "pkm-ja-s10p-021", "cardId": "16082260-3b03-4a05-a7f4-0ef92e3ec157", "cardPublicId": "card:16082260-3b03-4a05-a7f4-0ef92e3ec157", "set": { "id": "3f1e2a40-7c1d-4a52-9d0e-5b6a7c8d9e01", "publicId": "s10p-ja", "name": "S10P", "code": "S10P" }, "game": "pokemon", "language": "ja", "collectorNumber": "021", "name": "グレイシア", "regulationMark": null, "rarity": null, "image": null, "updatedAt": "2026-09-03T17:40:02.123456Z", "kind": "pokemon", "pokemon": [ { "dexNumber": 471, "slug": "glaceon", "isPrimary": true, "names": { "en": "Glaceon", "ja": "グレイシア" } } ], "illustrators": [], "equivalents": [ { "printingId": "pkm-en-swsh10-038", "setCode": "SWSH10", "collectorNumber": "038", "name": "Glaceon", "language": "en", "relationship": "language_counterpart" } ], "englishName": { "name": "Glaceon", "basis": "linked-card" }, "meta": { "rarityGroupVersion": "rarity-groups-v3" }, "images": null, "variants": [ { "variantKey": "standard", "finish": null, "edition": null, "stamp": null, "isDefault": true } ], "externalIds": {} } }, "japaneseSizedImages": { "summary": "Japanese printing with all t1 sizes; synthetic UUIDs, keys, hashes and dimensions", "value": { "id": "09262db8-96e9-5606-8b0b-af46de9e3549", "publicId": "pkm-ja-sv10-010", "cardId": "16082260-3b03-4a05-a7f4-0ef92e3ec157", "cardPublicId": "card:16082260-3b03-4a05-a7f4-0ef92e3ec157", "set": { "id": "3f1e2a40-7c1d-4a52-9d0e-5b6a7c8d9e01", "publicId": "sv10-ja", "name": "ロケット団の栄光", "code": "SV10" }, "game": "pokemon", "language": "ja", "collectorNumber": "010", "name": "ミニーブ", "regulationMark": "I", "rarity": { "code": "common", "name": "Common", "rank": null, "symbol": null, "group": "common", "basis": "source" }, "image": { "id": "aaaaaaaa-0000-4000-8000-000000000001", "printingId": "09262db8-96e9-5606-8b0b-af46de9e3549", "variantId": null, "role": "front", "isPrimary": true, "mimeType": "image/jpeg", "width": 748, "height": 1044, "fileSizeBytes": 123456, "sha256": "0000000000000000000000000000000000000000000000000000000000000000", "url": "https://images.poplextcg.com/example/source.jpg", "objectKey": "example/source.jpg" }, "updatedAt": "2026-09-03T17:40:02.123456Z", "kind": "pokemon", "pokemon": [ { "dexNumber": 928, "slug": "smoliv", "isPrimary": true, "names": { "en": "Smoliv", "ja": "ミニーブ" } } ], "illustrators": [ { "slug": "yuka-morii", "name": "Yuka Morii" } ], "equivalents": [], "englishName": null, "meta": { "rarityGroupVersion": "rarity-groups-v3" }, "images": { "sizes": { "small": { "url": "https://images.poplextcg.com/c3/ja/pkm-ja-sv10-010/front/small/t1/1111111111111111111111111111111111111111111111111111111111111111.webp", "width": 240, "height": 335, "fileSizeBytes": 12000, "mimeType": "image/webp", "sha256": "1111111111111111111111111111111111111111111111111111111111111111" }, "medium": { "url": "https://images.poplextcg.com/c3/ja/pkm-ja-sv10-010/front/medium/t1/2222222222222222222222222222222222222222222222222222222222222222.webp", "width": 480, "height": 670, "fileSizeBytes": 42000, "mimeType": "image/webp", "sha256": "2222222222222222222222222222222222222222222222222222222222222222" }, "large": { "url": "https://images.poplextcg.com/c3/ja/pkm-ja-sv10-010/front/large/t1/3333333333333333333333333333333333333333333333333333333333333333.webp", "width": 720, "height": 1005, "fileSizeBytes": 75000, "mimeType": "image/webp", "sha256": "3333333333333333333333333333333333333333333333333333333333333333" } }, "placeholder": { "averageColor": "#778899" } }, "variants": [ { "variantKey": "standard", "finish": null, "edition": null, "stamp": null, "isDefault": true } ], "externalIds": {} } } } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/printings/{printingId}/images": { "get": { "operationId": "listPrintingImages", "summary": "List the images of a printing", "description": "Lists the images of a printing, primary images by default, optionally for one variant. Plans without images receive 403 `entitlement_required`. Images whose source's rights do not allow publication are left out, so a page can hold fewer than `limit` items while `hasMore` is true.", "tags": [ "Images" ], "parameters": [ { "$ref": "#/components/parameters/PrintingIdPath" }, { "name": "variant", "in": "query", "required": false, "description": "Restrict to one variant (UUID or public ID).", "schema": { "$ref": "#/components/schemas/CatalogEntityIdentifier" } }, { "name": "role", "in": "query", "required": false, "description": "Restrict to one canonical role.", "schema": { "$ref": "#/components/schemas/ImageRole" } }, { "name": "isPrimary", "in": "query", "required": false, "description": "Primary images only (default true).", "schema": { "type": "boolean", "default": true } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order; prefix '-' for descending. Ordering is deterministic: ties are always broken by the stated tie-breaker column ascending, so a cursor never skips or repeats rows. ", "schema": { "type": "string", "enum": [ "role", "-role" ], "default": "role" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "$ref": "#/components/parameters/RequestIdHeader" } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Poplex-Quota-Limit": { "$ref": "#/components/headers/X-Poplex-Quota-Limit" }, "X-Poplex-Quota-Remaining": { "$ref": "#/components/headers/X-Poplex-Quota-Remaining" }, "X-Poplex-Quota-Reset": { "$ref": "#/components/headers/X-Poplex-Quota-Reset" }, "X-Poplex-Quota-Warning": { "$ref": "#/components/headers/X-Poplex-Quota-Warning" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageList" } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/printings/{printingId}/image": { "get": { "operationId": "resolvePrintingImage", "summary": "Get the canonical image of a printing", "description": "Returns the exact variant's primary image if one exists, otherwise the printing's primary image; never an image of another printing or variant. Default role order: front, back, then other roles alphabetically. When no image is available the answer is 200 with `missing: true`. A variant that does not belong to the printing gives 404 `variant_not_found`. Plans without images receive 403 `entitlement_required`.", "tags": [ "Images" ], "parameters": [ { "$ref": "#/components/parameters/PrintingIdPath" }, { "name": "variant", "in": "query", "required": false, "description": "Variant UUID or public ID; must belong to the printing.", "schema": { "$ref": "#/components/schemas/CatalogEntityIdentifier" } }, { "name": "role", "in": "query", "required": false, "description": "Canonical image role.", "schema": { "$ref": "#/components/schemas/ImageRole" } }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "$ref": "#/components/parameters/RequestIdHeader" } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Poplex-Quota-Limit": { "$ref": "#/components/headers/X-Poplex-Quota-Limit" }, "X-Poplex-Quota-Remaining": { "$ref": "#/components/headers/X-Poplex-Quota-Remaining" }, "X-Poplex-Quota-Reset": { "$ref": "#/components/headers/X-Poplex-Quota-Reset" }, "X-Poplex-Quota-Warning": { "$ref": "#/components/headers/X-Poplex-Quota-Warning" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResolution" } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/illustrators": { "get": { "operationId": "listIllustrators", "summary": "List illustrators", "description": "Lists the illustrators (artists) credited on cards, with the number of cards and printings credited to each (all languages together) and the languages in which they appear. `q` is a case- and accent-insensitive \"contains\" search of the name, the slug and other spellings of the name (for example the name in another script), with at least 2 characters. `language` keeps illustrators with at least one printing in that language. `sort` is `name` (default) or `cardCount` (most cards first); ties are ordered by slug. Entries of `kind` `label` (a role word that is not a name) are hidden unless `includeLabels=true`. A cursor is valid only for the filters and sort that produced it.", "tags": [ "Catalog" ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search text, at least 2 characters after trimming. Case- and accent-insensitive; matches the name, the slug and other spellings of the name.", "schema": { "type": "string", "minLength": 2 } }, { "$ref": "#/components/parameters/LanguageFilter" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "name", "cardCount" ], "default": "name" }, "description": "Order: `name` (default, alphabetical) or `cardCount` (most cards first). Ties are ordered by slug. A cursor is valid only for the sort that produced it." }, { "name": "includeLabels", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "When `true`, entries of `kind` `label` (role words such as a job title, not names) are included. Default `false`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Page size, 1 to 100 (default 25). A larger value is rejected with 400 `invalid_parameter`." }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "$ref": "#/components/parameters/RequestIdHeader" } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Poplex-Quota-Limit": { "$ref": "#/components/headers/X-Poplex-Quota-Limit" }, "X-Poplex-Quota-Remaining": { "$ref": "#/components/headers/X-Poplex-Quota-Remaining" }, "X-Poplex-Quota-Reset": { "$ref": "#/components/headers/X-Poplex-Quota-Reset" }, "X-Poplex-Quota-Warning": { "$ref": "#/components/headers/X-Poplex-Quota-Warning" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IllustratorList" }, "examples": { "artists": { "summary": "Two illustrators; illustrative counts", "value": { "data": [ { "slug": "mitsuhiro-arita", "name": "Mitsuhiro Arita", "kind": "person", "cardCount": 250, "printingCount": 420, "languages": [ "en", "ja" ] }, { "slug": "the-pokemon-company-art-team", "name": "The Pokémon Company Art-team", "kind": "team", "cardCount": 17, "printingCount": 20, "languages": [ "en", "ja" ] } ], "page": { "limit": 25, "hasMore": false, "nextCursor": null } } } } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/illustrators/{illustratorId}": { "get": { "operationId": "getIllustrator", "summary": "Get an illustrator", "description": "Returns one illustrator by slug, with counts, languages, the release span of the sets with credited printings and alternate spellings. An old or merged slug is still accepted: the answer is 200 with the current illustrator and `redirectedFrom` set to the slug you asked for. An unknown slug is 404 `illustrator_not_found`; a malformed slug is 400 `invalid_parameter`.", "tags": [ "Catalog" ], "parameters": [ { "$ref": "#/components/parameters/IllustratorIdPath" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "$ref": "#/components/parameters/RequestIdHeader" } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Poplex-Quota-Limit": { "$ref": "#/components/headers/X-Poplex-Quota-Limit" }, "X-Poplex-Quota-Remaining": { "$ref": "#/components/headers/X-Poplex-Quota-Remaining" }, "X-Poplex-Quota-Reset": { "$ref": "#/components/headers/X-Poplex-Quota-Reset" }, "X-Poplex-Quota-Warning": { "$ref": "#/components/headers/X-Poplex-Quota-Warning" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Illustrator" }, "examples": { "artist": { "summary": "One illustrator; illustrative counts", "value": { "slug": "shinji-higuchi", "name": "Shinji Higuchi", "kind": "person", "cardCount": 14, "printingCount": 16, "languages": [ "en", "ja" ], "releaseDateFirst": "2026-01-30", "releaseDateLast": "2026-01-30", "aliases": [ "樋口真嗣" ] } }, "redirected": { "summary": "An old slug of the same person", "value": { "slug": "shinji-higuchi", "name": "Shinji Higuchi", "kind": "person", "cardCount": 14, "printingCount": 16, "languages": [ "en", "ja" ], "releaseDateFirst": "2026-01-30", "releaseDateLast": "2026-01-30", "aliases": [ "樋口真嗣" ], "redirectedFrom": "j-aa124b55b67f" } } } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "default": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearerApiKey": { "type": "http", "scheme": "bearer", "description": "Your Poplex API key (`px_live_...`) in `Authorization: Bearer `. Keys are never accepted in the address." } }, "schemas": { "CardIdentifier": { "type": "string", "description": "A UUID, or `card:` followed by a UUID. The UUID part is case-insensitive.", "pattern": "^(card:)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "CatalogEntityIdentifier": { "type": "string", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9][a-z0-9._:-]*)$", "description": "A UUID or a Poplex public ID (lower-case letters, digits and . _ : -, starting with a letter or digit), for example `pkm-ja-s10p-021`." }, "ImageRole": { "type": "string", "description": "Canonical image role (front, back, ...).", "pattern": "^[a-z0-9]+([._-][a-z0-9]+)*$" }, "GameSlug": { "type": "string", "description": "Game identifier, for example `pokemon`.", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }, "LanguageCode": { "type": "string", "description": "Language code of a set, for example `en` or `ja`.", "pattern": "^[a-z]{2,3}(-[a-z0-9]{2,8})*$" }, "ProblemDetails": { "type": "object", "required": [ "title", "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri-reference", "default": "about:blank", "description": "RFC 9457 problem type. Poplex does not define problem-type URIs; use `code`." }, "title": { "type": "string", "description": "Short human-readable summary of the problem type." }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "HTTP status code, repeated in the body." }, "detail": { "type": "string", "description": "Human-readable explanation of this occurrence." }, "code": { "type": "string", "enum": [ "invalid_card_identifier", "printing_required_for_image_resolution", "invalid_printing_identifier", "invalid_variant_identifier", "invalid_image_role", "not_found", "printing_not_found", "variant_not_found", "card_resolution_unavailable", "invalid_parameter", "invalid_cursor", "unauthorized", "forbidden", "method_not_allowed", "rate_limited", "internal_error", "service_unavailable", "entitlement_required", "quota_exceeded", "illustrator_not_found" ], "description": "Stable machine-readable error code." }, "requestId": { "type": "string", "description": "Correlation identifier, equal to the X-Request-Id response header." }, "parameter": { "type": "string", "description": "Name of the offending query or path parameter, when the error is a validation error." }, "reset_at": { "type": "string", "format": "date-time", "description": "Only on code quota_exceeded: the ISO-8601 UTC instant at which the allowance resets (the end of the allowance period). The period itself is supplied by the operator; the contract does not define a calendar month or a billing anniversary." }, "period_start": { "type": "string", "format": "date-time", "description": "Only on code quota_exceeded: the ISO-8601 UTC instant at which the allowance period that is used up started." } }, "description": "Error body, media type `application/problem+json` (RFC 9457). Key on `code`; `requestId` is always present. Bodies never contain stack traces, SQL, host names or storage details." }, "PageInfo": { "type": "object", "required": [ "limit", "hasMore", "nextCursor" ], "properties": { "limit": { "type": "integer", "minimum": 1, "description": "Effective page size used for this response." }, "hasMore": { "type": "boolean", "description": "True when a further page exists." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor to pass as the 'cursor' query parameter for the next page; null on the last page. Clients must not parse or construct cursors." } } }, "ApiVersion": { "type": "object", "description": "Service name and status.", "required": [ "name", "status", "apiVersion" ], "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "apiVersion": { "type": "string", "enum": [ "v1" ], "description": "Major API version; equals the first path segment of the server URL." }, "catalogRelease": { "type": [ "string", "null" ], "description": "Identifier of the canonical catalog release being served." } } }, "ServiceStatus": { "type": "object", "description": "Liveness status; no database access.", "required": [ "status", "service", "timestamp" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "service": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } }, "RaritySummary": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "rank": { "type": [ "integer", "null" ], "minimum": 0 }, "symbol": { "type": [ "string", "null" ] }, "group": { "$ref": "#/components/schemas/RarityGroup", "description": "Coarse rarity group derived by Poplex (see `RarityGroup`). The source rarity code, name, rank and symbol are unchanged." }, "basis": { "type": "string", "enum": [ "source", "printed-mark" ], "description": "Who established this rarity: `source` (stated by a data source) or `printed-mark` (read by Poplex from the mark printed on the card: a circle, diamond or star; a star does not tell a holo card from a non-holo one). Clients must tolerate new values." } }, "required": [ "code", "name", "rank", "symbol" ], "description": "The rarity printed or recorded for a printing, with Poplex's derived group. `basis` says who established it." }, "SeriesSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "releaseOrder": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "id", "slug", "name", "code", "releaseOrder" ] }, "SetSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "publicId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._:-]*$" }, "name": { "type": "string" }, "code": { "type": [ "string", "null" ] } }, "required": [ "id", "publicId", "name", "code" ] }, "Set": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "publicId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._:-]*$" }, "slug": { "type": "string" }, "name": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "game": { "type": "string", "description": "Game slug." }, "language": { "type": "string", "description": "Language code of the set's catalog." }, "series": { "description": "Series the set belongs to, or null.", "oneOf": [ { "$ref": "#/components/schemas/SeriesSummary" }, { "type": "null" } ] }, "printedTotal": { "type": [ "integer", "null" ], "minimum": 0 }, "total": { "type": [ "integer", "null" ], "minimum": 0 }, "releaseDate": { "type": [ "string", "null" ], "format": "date" }, "isPromo": { "type": "boolean" }, "isActive": { "type": "boolean" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "publicId", "slug", "name", "code", "game", "language", "series", "printedTotal", "total", "releaseDate", "isPromo", "isActive", "updatedAt" ] }, "Card": { "type": "object", "description": "A card is the language-independent design: the same card across languages and printings. A card has no language of its own; its printings do.", "required": [ "id", "publicId", "canonicalName", "kind", "game", "identityState", "identityStrategy", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "publicId": { "type": "string", "pattern": "^card:[0-9a-f-]{36}$", "description": "Stable public ID, generated as 'card:' + id." }, "canonicalName": { "type": "string", "description": "Display and search label for the card. It is not an identifier; use `id` to refer to a card." }, "kind": { "type": [ "string", "null" ], "description": "Card kind (`pokemon`, `trainer` or `energy`); null when unknown." }, "game": { "type": "string", "description": "Game slug." }, "identityState": { "type": "string", "enum": [ "active", "superseded" ], "description": "Lifecycle state of the card. Clients must tolerate new values." }, "identityStrategy": { "type": "string", "enum": [ "printing-scoped-v1", "artwork-and-rules-concept-v2" ], "description": "Identity policy of the card. Clients must tolerate new values." }, "updatedAt": { "type": "string", "format": "date-time" }, "displayName": { "type": "string", "description": "Name chosen for the requested language." } } }, "CardResolution": { "type": "object", "description": "Identity resolution record: shows whether the requested identifier was superseded and which active card it resolves to.", "required": [ "requestedIdentifier", "requestedCardId", "requestedPublicId", "resolvedCardId", "resolvedPublicId", "identityState", "resolvedIdentityState", "identityStrategy", "redirected" ], "properties": { "requestedIdentifier": { "type": "string", "description": "The identifier exactly as the client supplied it." }, "requestedCardId": { "type": "string", "format": "uuid" }, "requestedPublicId": { "type": "string" }, "resolvedCardId": { "type": "string", "format": "uuid" }, "resolvedPublicId": { "type": "string" }, "identityState": { "type": "string", "enum": [ "active", "superseded" ] }, "resolvedIdentityState": { "type": "string", "enum": [ "active" ] }, "identityStrategy": { "type": "string", "enum": [ "printing-scoped-v1", "artwork-and-rules-concept-v2" ] }, "redirected": { "type": "boolean", "description": "True when a superseded card was redirected to an active survivor." } } }, "CardDetail": { "allOf": [ { "$ref": "#/components/schemas/Card" }, { "type": "object", "required": [ "resolution" ], "properties": { "resolution": { "description": "How the requested identifier was resolved to this (active) card.", "$ref": "#/components/schemas/CardResolution" } } }, { "type": "object", "properties": { "kind": { "type": [ "string", "null" ], "enum": [ "pokemon", "trainer", "energy", null ], "description": "Card kind; null when unknown." }, "pokemon": { "type": "array", "items": { "$ref": "#/components/schemas/PokemonSummary" }, "description": "Pokémon on the card, in order. Empty for Trainers and Energies or when no species is linked." }, "illustrators": { "type": "array", "items": { "$ref": "#/components/schemas/IllustratorCredit" }, "description": "Illustrator credits, in credit order. Empty when none are recorded." } } }, { "type": "object", "properties": { "englishName": { "oneOf": [ { "$ref": "#/components/schemas/EnglishName" }, { "type": "null" } ], "description": "English name of the card with its basis. Null when none is recorded, including English cards. `getPrinting` uses the requested printing's card; `getCard` uses the active card it resolves to." } } } ], "description": "The resolved card plus the identity resolution record. Returned with HTTP 200 also when the requested identifier belonged to a superseded card." }, "Image": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "printingId": { "type": "string", "format": "uuid" }, "variantId": { "type": [ "string", "null" ], "format": "uuid" }, "role": { "type": "string", "pattern": "^[a-z0-9]+([._-][a-z0-9]+)*$" }, "isPrimary": { "type": "boolean" }, "mimeType": { "type": [ "string", "null" ] }, "width": { "type": [ "integer", "null" ], "minimum": 1 }, "height": { "type": [ "integer", "null" ], "minimum": 1 }, "fileSizeBytes": { "type": [ "integer", "null" ], "minimum": 0 }, "sha256": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the image bytes when recorded." }, "url": { "type": "string", "format": "uri", "description": "Complete address of the image file on images.poplextcg.com." }, "objectKey": { "type": "string", "minLength": 1, "description": "Storage key of the image file; the address is the image host plus this key. Prefer `url`." } }, "required": [ "id", "printingId", "variantId", "role", "isPrimary", "mimeType", "width", "height", "fileSizeBytes", "sha256", "url", "objectKey" ] }, "ImageList": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } }, "Printing": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "publicId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._:-]*$" }, "cardId": { "type": "string", "format": "uuid" }, "cardPublicId": { "type": "string" }, "set": { "$ref": "#/components/schemas/SetSummary" }, "game": { "type": "string", "description": "Game slug." }, "language": { "type": "string", "description": "Language code, inherited from the printing's set (language belongs to the set, not the card)." }, "collectorNumber": { "type": "string", "description": "Collector number as printed (text; not necessarily numeric)." }, "name": { "type": "string", "description": "Printed (local-language) name of the printing." }, "regulationMark": { "type": [ "string", "null" ] }, "rarity": { "description": "Rarity with its group and basis, or null when no rarity is recorded. Many modern Japanese cards print no rarity at all (a plain Common, Uncommon or Rare carries no rarity letter), and for those neither the card nor our sources give a value, so this stays null. Poplex does not guess.", "oneOf": [ { "$ref": "#/components/schemas/RaritySummary" }, { "type": "null" } ] }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/PrintingVariant" }, "description": "Finishes and editions in which this printing exists. The default variant comes first, the others follow ordered by `variantKey`. Always an array (empty when none are recorded). Clients must tolerate new finish, edition and stamp values." }, "externalIds": { "$ref": "#/components/schemas/PrintingExternalIds" }, "image": { "description": "The printing's primary image exactly as its source supplied it (format and size vary, including JPEG and GIF), or null when the plan does not include images or no publishable image exists. Prefer `images` for fixed WebP sizes.", "oneOf": [ { "$ref": "#/components/schemas/Image" }, { "type": "null" } ] }, "images": { "oneOf": [ { "$ref": "#/components/schemas/PrintingImages" }, { "type": "null" } ], "description": "Fixed WebP sizes of the same image as `image`, plus an average colour for placeholders. Null when the plan does not include images, the printing has no image, or the source's rights do not allow it." }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "publicId", "cardId", "cardPublicId", "set", "game", "language", "collectorNumber", "name", "regulationMark", "rarity", "image", "updatedAt" ] }, "PrintingList": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Printing" } }, "page": { "$ref": "#/components/schemas/PageInfo" }, "meta": { "$ref": "#/components/schemas/RarityGroupMetadata" } } }, "ImageResolution": { "type": "object", "description": "Result of explicit image resolution. `missing: true` (HTTP 200) means no image is available; no image is ever borrowed from another printing or variant.", "required": [ "requestedPrintingIdentifier", "printingId", "printingPublicId", "requestedVariantIdentifier", "variantPublicId", "imageId", "role", "url", "scope", "requestedVariantId", "actualVariantId", "usedFallback", "missing", "objectKey" ], "properties": { "requestedPrintingIdentifier": { "type": "string", "description": "Printing identifier exactly as supplied in the path." }, "printingId": { "type": "string", "format": "uuid" }, "printingPublicId": { "type": "string" }, "requestedVariantIdentifier": { "type": [ "string", "null" ], "description": "Variant identifier exactly as supplied, or null." }, "variantPublicId": { "type": [ "string", "null" ] }, "imageId": { "type": [ "string", "null" ], "format": "uuid" }, "role": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "Canonical image URL; see Image.url." }, "scope": { "type": [ "string", "null" ], "enum": [ "variant", "printing", null ] }, "requestedVariantId": { "type": [ "string", "null" ], "format": "uuid" }, "actualVariantId": { "type": [ "string", "null" ], "format": "uuid" }, "usedFallback": { "type": "boolean", "description": "True when a variant was requested but the printing-level primary image was used." }, "missing": { "type": "boolean" }, "objectKey": { "type": [ "string", "null" ], "minLength": 1, "description": "Storage key of the image file (null when `missing` is true). Prefer `url`." } } }, "SetList": { "type": "object", "additionalProperties": false, "description": "One page of sets. Sets without a release date (or, when sorted by code, without a code) come last.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SetListItem" } }, "page": { "$ref": "#/components/schemas/PageInfo" }, "meta": { "$ref": "#/components/schemas/RarityGroupMetadata" } }, "required": [ "data", "page" ] }, "PokemonSummary": { "type": "object", "required": [ "dexNumber", "slug", "isPrimary", "names" ], "properties": { "dexNumber": { "type": "integer", "minimum": 1 }, "slug": { "type": "string", "minLength": 1 }, "isPrimary": { "type": "boolean" }, "names": { "type": "object", "required": [ "en", "ja" ], "description": "Independent language lookups. Missing names remain null; no translation or fallback is invented.", "properties": { "en": { "type": [ "string", "null" ] }, "ja": { "type": [ "string", "null" ] } } } } }, "IllustratorCredit": { "type": "object", "required": [ "slug", "name" ], "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "minLength": 1 }, "name": { "type": "string", "minLength": 1 } }, "description": "One illustrator credit of a card, in credit order. `slug` is the stable identifier (use it with `GET /illustrators/{illustratorId}` and the `illustrator` filter); `name` is the display name." }, "PrintingDetail": { "allOf": [ { "$ref": "#/components/schemas/Printing" }, { "type": "object", "properties": { "kind": { "type": [ "string", "null" ], "enum": [ "pokemon", "trainer", "energy", null ], "description": "Card kind; null when unknown." }, "pokemon": { "type": "array", "items": { "$ref": "#/components/schemas/PokemonSummary" }, "description": "Pokémon on the card, in card order. Empty for Trainers and Energies, unknown kinds, or when no species is linked." }, "illustrators": { "type": "array", "items": { "$ref": "#/components/schemas/IllustratorCredit" }, "description": "Illustrator credits, in credit order. Empty when none are recorded." } } }, { "type": "object", "properties": { "equivalents": { "type": "array", "items": { "$ref": "#/components/schemas/PrintingEquivalent" }, "description": "Language counterparts of this printing, in either direction, ordered by language code and then public ID. Several Japanese reprints can share one English counterpart, so a lookup from the English side can return several rows. Empty when none is recorded." }, "englishName": { "oneOf": [ { "$ref": "#/components/schemas/EnglishName" }, { "type": "null" } ], "description": "English name of the card with its basis. Null when none is recorded, including English cards." }, "meta": { "$ref": "#/components/schemas/RarityGroupMetadata" } } } ], "description": "A printing plus Pokémon, illustrators, English name and language equivalents (detail route only)." }, "RarityGroup": { "type": "string", "enum": [ "common", "uncommon", "rare", "special", "promo", "unrated" ], "description": "Derived coarse grouping, version rarity-groups-v3. Source rarity values are preserved. Japanese printed marks map circle to common, diamond to uncommon and star to rare; the English Classic Collection, full-art trainer, shiny V and shiny VMAX rarities and the Japanese promo rarity are grouped (since 1.8.0). Rarities that are not mapped to a group, including ja:hikaru, are unrated." }, "RarityGroupMetadata": { "type": "object", "required": [ "rarityGroupVersion" ], "properties": { "rarityGroupVersion": { "type": "string", "enum": [ "rarity-groups-v3" ] } } }, "PrintingEquivalent": { "type": "object", "required": [ "printingId", "setCode", "collectorNumber", "name", "language", "relationship" ], "properties": { "printingId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._:-]*$", "description": "The counterpart printing public ID (not its UUID)." }, "setCode": { "type": [ "string", "null" ] }, "collectorNumber": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "language": { "type": "string", "minLength": 1 }, "relationship": { "type": "string", "enum": [ "language_counterpart" ] } } }, "EnglishName": { "type": "object", "required": [ "name", "basis" ], "description": "The recorded English name and how it was established (`basis`). `species-derived` is an official species name plus a learned affix; `web-effect-matched` has lower confidence. Names are never guessed from other fields.", "properties": { "name": { "type": "string", "minLength": 1 }, "basis": { "type": "string", "enum": [ "linked-card", "linked-name", "web-verified", "web-name-matched", "species-derived", "web-effect-matched" ] } } }, "ImageDerivativeSize": { "type": "object", "additionalProperties": false, "required": [ "url", "width", "height", "fileSizeBytes", "mimeType", "sha256" ], "description": "One WebP size of an image: its width, height, byte size and address. Never enlarged.", "properties": { "url": { "type": "string", "format": "uri", "description": "Complete address of this WebP file on images.poplextcg.com." }, "width": { "type": "integer", "minimum": 1, "maximum": 720 }, "height": { "type": "integer", "minimum": 1 }, "fileSizeBytes": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "mimeType": { "type": "string", "enum": [ "image/webp" ], "description": "Always `image/webp`." }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } }, "PrintingImages": { "type": "object", "additionalProperties": false, "required": [ "sizes", "placeholder" ], "description": "Sizes of the image. `small` (up to 240 px wide) is always present; `medium` (480) and `large` (720) are present only when the source image is wide enough, because images are never enlarged. Keys appear in the order small, medium, large.", "properties": { "sizes": { "type": "object", "additionalProperties": false, "required": [ "small" ], "description": "Nominal widths: small 240, medium 480, large 720 pixels. Sizes are never enlarged, so `medium` and `large` can be absent; a source narrower than 240 px gives a `small` as wide as the source.", "properties": { "small": { "allOf": [ { "$ref": "#/components/schemas/ImageDerivativeSize" }, { "type": "object", "properties": { "width": { "type": "integer", "maximum": 240 } } } ] }, "medium": { "allOf": [ { "$ref": "#/components/schemas/ImageDerivativeSize" }, { "type": "object", "properties": { "width": { "type": "integer", "maximum": 480 } } } ] }, "large": { "allOf": [ { "$ref": "#/components/schemas/ImageDerivativeSize" }, { "type": "object", "properties": { "width": { "type": "integer", "maximum": 720 } } } ] } } }, "placeholder": { "type": "object", "additionalProperties": false, "required": [ "averageColor" ], "properties": { "averageColor": { "type": "string", "pattern": "^#[0-9a-f]{6}$", "description": "Average colour of the image (`#rrggbb`), for a placeholder while the image loads." } } } } }, "PrintingVariant": { "type": "object", "additionalProperties": false, "description": "One finish or edition in which a printing exists, for example normal or reverse finish, standard or 1st edition. The values are open vocabularies: clients must tolerate new ones. A null `finish`, `edition` or `stamp` means unknown (or none), never \"normal\".", "properties": { "variantKey": { "type": "string", "minLength": 1 }, "finish": { "type": [ "string", "null" ] }, "edition": { "type": [ "string", "null" ] }, "stamp": { "type": [ "string", "null" ] }, "isDefault": { "type": "boolean" } }, "required": [ "variantKey", "finish", "edition", "stamp", "isDefault" ] }, "PrintingExternalIds": { "type": "object", "additionalProperties": false, "description": "IDs of a printing in an external catalog. A key appears only when an ID is recorded.", "properties": { "catalog": { "type": "string", "minLength": 1, "description": "The printing's own ID in the external catalog, as that catalog writes it." } } }, "SetListItem": { "type": "object", "additionalProperties": false, "description": "A set with the code, language, counts and release date needed for browsing.", "properties": { "id": { "type": "string", "format": "uuid" }, "publicId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._:-]*$" }, "name": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "language": { "type": "string", "description": "Language code of the set, for example `en` or `ja`." }, "printedTotal": { "type": [ "integer", "null" ], "minimum": 0 }, "total": { "type": [ "integer", "null" ], "minimum": 0 }, "releaseDate": { "type": [ "string", "null" ], "format": "date" }, "isPromo": { "type": "boolean" } }, "required": [ "id", "publicId", "name", "code", "language", "printedTotal", "total", "releaseDate", "isPromo" ] }, "IllustratorListItem": { "type": "object", "additionalProperties": false, "required": [ "slug", "name", "kind", "cardCount", "printingCount", "languages" ], "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "person", "team", "joint", "label" ], "description": "`person` (one artist), `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 from lists unless `includeLabels=true`). Clients must tolerate new values." }, "cardCount": { "type": "integer", "minimum": 0, "description": "Cards credited to this illustrator, all languages." }, "printingCount": { "type": "integer", "minimum": 0, "description": "Printings of those cards, all languages." }, "languages": { "type": "array", "items": { "$ref": "#/components/schemas/LanguageCode" }, "description": "Languages with at least one printing." } } }, "Illustrator": { "type": "object", "additionalProperties": false, "required": [ "slug", "name", "kind", "cardCount", "printingCount", "languages", "releaseDateFirst", "releaseDateLast", "aliases" ], "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "person", "team", "joint", "label" ], "description": "`person` (one artist), `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 from lists unless `includeLabels=true`). Clients must tolerate new values." }, "cardCount": { "type": "integer", "minimum": 0, "description": "Cards credited to this illustrator, all languages." }, "printingCount": { "type": "integer", "minimum": 0, "description": "Printings of those cards, all languages." }, "languages": { "type": "array", "items": { "$ref": "#/components/schemas/LanguageCode" }, "description": "Languages with at least one printing." }, "releaseDateFirst": { "type": [ "string", "null" ], "format": "date", "description": "Release date (`YYYY-MM-DD`) of the earliest set with a credited printing; null when no such set has a date." }, "releaseDateLast": { "type": [ "string", "null" ], "format": "date" }, "aliases": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Other spellings of the name, for example the name in another script. Empty when none are recorded." }, "redirectedFrom": { "type": "string", "description": "Present only when the requested slug was an old or merged one; it echoes the slug you asked for. `slug` is the current one." } } }, "IllustratorList": { "type": "object", "additionalProperties": false, "description": "One cursor page of illustrators.", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IllustratorListItem" } }, "page": { "$ref": "#/components/schemas/PageInfo" } } } }, "parameters": { "Limit": { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 100 (default 25). A larger value is rejected with 400 `invalid_parameter`.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "Cursor": { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor copied from `page.nextCursor`. Valid only with the same filters and sort that produced it, otherwise 400 `invalid_cursor`. Do not parse or build it.", "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "IfNoneMatch": { "name": "If-None-Match", "in": "header", "required": false, "description": "Conditional request validator (RFC 9110 section 13.1.2): send a previously received ETag; a match yields 304 Not Modified.", "schema": { "type": "string" } }, "RequestIdHeader": { "name": "X-Request-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,64}$" } }, "SetIdPath": { "name": "setId", "in": "path", "required": true, "description": "Set UUID or public ID.", "schema": { "$ref": "#/components/schemas/CatalogEntityIdentifier" } }, "CardIdPath": { "name": "cardId", "in": "path", "required": true, "description": "Card UUID or 'card:'-prefixed public ID. A superseded card still resolves (see CardResolution).", "schema": { "$ref": "#/components/schemas/CardIdentifier" } }, "PrintingIdPath": { "name": "printingId", "in": "path", "required": true, "description": "Printing UUID or public ID.", "schema": { "$ref": "#/components/schemas/CatalogEntityIdentifier" } }, "GameFilter": { "name": "game", "in": "query", "required": false, "description": "Filter by game slug.", "schema": { "$ref": "#/components/schemas/GameSlug" } }, "LanguageFilter": { "name": "language", "in": "query", "required": false, "description": "Filter by language code (languages belong to sets, not cards).", "schema": { "$ref": "#/components/schemas/LanguageCode" } }, "IllustratorIdPath": { "name": "illustratorId", "in": "path", "required": true, "description": "Illustrator slug, for example `mitsuhiro-arita` (see `GET /illustrators`). An old or merged slug is accepted and answers with the current illustrator and `redirectedFrom`.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "minLength": 1 } } }, "headers": { "X-Request-Id": { "description": "Correlation identifier of this request; also the `requestId` of error bodies. Quote it when you contact support.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,64}$" } }, "ETag": { "description": "Validator of the representation. Send it in `If-None-Match` to get 304 when nothing changed.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Responses are authenticated and are not cached by intermediaries (`no-store`).", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "WWW-Authenticate": { "description": "Challenge on 401: `Bearer`.", "schema": { "type": "string" } }, "X-Poplex-Quota-Limit": { "description": "Requests the key's organization may use in the current period; the allowance is shared by all keys of the organization.", "schema": { "type": "integer", "minimum": 0 } }, "X-Poplex-Quota-Remaining": { "description": "Requests still available to the organization in the current period, as of the start of this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-Poplex-Quota-Reset": { "description": "ISO-8601 UTC instant at which the allowance resets.", "schema": { "type": "string", "format": "date-time" } }, "X-Poplex-Quota-Warning": { "description": "The highest warning percentage (80 or 95) the organization has reached in the current period; absent when none has been reached.", "schema": { "type": "number", "maximum": 100 } } }, "responses": { "NotModified": { "description": "Not Modified: the If-None-Match validator matched the current representation. No body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Poplex-Quota-Limit": { "$ref": "#/components/headers/X-Poplex-Quota-Limit" }, "X-Poplex-Quota-Remaining": { "$ref": "#/components/headers/X-Poplex-Quota-Remaining" }, "X-Poplex-Quota-Reset": { "$ref": "#/components/headers/X-Poplex-Quota-Reset" }, "X-Poplex-Quota-Warning": { "$ref": "#/components/headers/X-Poplex-Quota-Warning" } } }, "BadRequest": { "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "Missing, malformed or unknown API key (code unauthorized).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The key is valid but not permitted for this request (`forbidden`), or the key's plan does not include the feature (`entitlement_required`, for example the image routes on a plan without images).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "Resource not found (codes: not_found, printing_not_found, variant_not_found, illustrator_not_found).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "Too many requests. `rate_limited`: the short-window limit of the key was exceeded (approximate, applied per location); wait `Retry-After` seconds. `quota_exceeded`: the organization's monthly allowance is used up; it resets at 00:00 UTC on the first day of the month. Neither counts as usage. A very fast burst can also be refused at the edge with a plain-text 429 and `Retry-After`; wait and retry on any 429.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Poplex-Quota-Limit": { "$ref": "#/components/headers/X-Poplex-Quota-Limit" }, "X-Poplex-Quota-Remaining": { "$ref": "#/components/headers/X-Poplex-Quota-Remaining" }, "X-Poplex-Quota-Reset": { "$ref": "#/components/headers/X-Poplex-Quota-Reset" }, "X-Poplex-Quota-Warning": { "$ref": "#/components/headers/X-Poplex-Quota-Warning" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/plain": { "schema": { "type": "string" }, "example": "An edge rate-limit response may precede the API." } } }, "InternalServerError": { "description": "Unexpected server fault (code internal_error); no internal detail is returned.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "ServiceUnavailable": { "description": "Dependency unavailable (codes: service_unavailable, card_resolution_unavailable).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Error": { "description": "Any other error, using the standard problem body (for example 405 method_not_allowed).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "externalDocs": { "description": "Getting started", "url": "https://poplextcg.com/docs/" } }