{"openapi":"3.1.0","info":{"title":"PkmnPrices API","description":"Pokemon TCG market prices from TCGPlayer, Cardmarket, and eBay. Get a key at https://pkmnprices.com/dashboard. Prefer https://api.pkmnprices.com/llm.md for LLM quick context.","termsOfService":"https://www.pkmnprices.com/terms","contact":{"name":"PkmnPrices support","url":"https://discord.gg/G9b2p46EQX","email":"support@pkmnprices.com"},"version":"1.0.0"},"servers":[{"url":"https://api.pkmnprices.com","description":"Production"}],"paths":{"/health":{"get":{"tags":["health"],"operationId":"health","responses":{"200":{"description":"API healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"503":{"description":"Database unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/cards":{"get":{"tags":["cards"],"operationId":"list_cards","parameters":[{"name":"name","in":"query","description":"Substring match on card name","required":false,"schema":{"type":"string"}},{"name":"set_id","in":"query","description":"Filter by set ID","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"tcg_player_id","in":"query","description":"Filter by TCGPlayer product ID","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"number","in":"query","description":"Card number within the set","required":false,"schema":{"type":"string"}},{"name":"total_set_number","in":"query","description":"Full set number (e.g. 001/198)","required":false,"schema":{"type":"string"}},{"name":"rarity","in":"query","description":"Filter by rarity","required":false,"schema":{"type":"string"}},{"name":"stage","in":"query","description":"Filter by evolution stage","required":false,"schema":{"type":"string"}},{"name":"card_type","in":"query","description":"Filter by card type (e.g. Pokemon, Trainer)","required":false,"schema":{"type":"string"}},{"name":"weakness","in":"query","description":"Filter by weakness type","required":false,"schema":{"type":"string"}},{"name":"energy_type","in":"query","description":"Filter by energy type","required":false,"schema":{"type":"string"}},{"name":"language","in":"query","description":"Filter by language (Japanese and German require Pro+)","required":false,"schema":{"type":"string"}},{"name":"currency","in":"query","description":"Currency for price filters (USD or EUR)","required":false,"schema":{"type":"string"}},{"name":"condition","in":"query","description":"Filter by price condition","required":false,"schema":{"type":"string"}},{"name":"variant","in":"query","description":"Filter by price variant","required":false,"schema":{"type":"string"}},{"name":"grader","in":"query","description":"Filter by grader","required":false,"schema":{"type":"string"}},{"name":"grade","in":"query","description":"Filter by grade","required":false,"schema":{"type":"string"}},{"name":"min_price","in":"query","description":"Minimum market price","required":false,"schema":{"type":"number","format":"double"}},{"name":"max_price","in":"query","description":"Maximum market price","required":false,"schema":{"type":"number","format":"double"}},{"name":"sort","in":"query","description":"Sort order (price_asc, price_desc, or default by id)","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Page number (default 1)","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"per_page","in":"query","description":"Page size (default 50, max 100)","required":false,"schema":{"type":"integer","format":"int32","minimum":0}}],"responses":{"200":{"description":"Paginated card summaries. Prices are omitted; use GET /v1/cards/{id} for prices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCardSummary"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Tier restriction (e.g. Japanese/German cards or EUR currency on free tier)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate or credit limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"api_key":[]}]}},"/v1/cards/{id}":{"get":{"tags":["cards"],"operationId":"get_card","parameters":[{"name":"id","in":"path","description":"Card ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"currency","in":"query","description":"Filter prices by currency (USD or EUR)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Card with prices","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardResponse"}}}},"400":{"description":"Invalid currency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Tier restriction (e.g. Japanese/German cards or EUR on free tier)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Card not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate or credit limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"api_key":[]}]}},"/v1/cards/{id}/listings/cardmarket":{"get":{"tags":["listings"],"operationId":"cardmarket_card_listings","parameters":[{"name":"id","in":"path","description":"Card ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"condition","in":"query","description":"Filter by native Cardmarket condition","required":false,"schema":{"type":"string"}},{"name":"variant","in":"query","description":"Filter by printing variant; Reverse Holo and Reverse Holofoil are equivalent","required":false,"schema":{"type":"string"}},{"name":"min_price","in":"query","description":"Minimum listing price in EUR","required":false,"schema":{"type":"number","format":"double"}},{"name":"max_price","in":"query","description":"Maximum listing price in EUR","required":false,"schema":{"type":"number","format":"double"}},{"name":"cursor","in":"query","description":"Pagination cursor from previous response","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size (default 20, max 20)","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"sort","in":"query","description":"Sort order (price_asc or price_desc)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cursor-paginated Cardmarket marketplace listings in the card's language. Rows flagged signed, altered or graded are included but are excluded from market price derivation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorCardmarketListings"}}}},"400":{"description":"Invalid cursor or query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Listings require Pro or higher","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate or credit limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"api_key":[]}]}},"/v1/cards/{id}/listings/ebay":{"get":{"tags":["listings"],"operationId":"ebay_card_listings","parameters":[{"name":"id","in":"path","description":"Card ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"graded","in":"query","description":"Filter graded vs raw listings","required":false,"schema":{"type":"boolean"}},{"name":"grader","in":"query","description":"Filter by grader (e.g. PSA, BGS)","required":false,"schema":{"type":"string"}},{"name":"grade","in":"query","description":"Filter by grade","required":false,"schema":{"type":"string"}},{"name":"min_price","in":"query","description":"Minimum sale price","required":false,"schema":{"type":"number","format":"double"}},{"name":"max_price","in":"query","description":"Maximum sale price","required":false,"schema":{"type":"number","format":"double"}},{"name":"variant","in":"query","description":"Filter by the PriceCharting printing the comp was collected under, e.g. Holofoil","required":false,"schema":{"type":"string"}},{"name":"since","in":"query","description":"Only comps ingested after this instant (RFC 3339 timestamp or YYYY-MM-DD). Checkpoint on ingested_at, not sold_at","required":false,"schema":{"type":"string"}},{"name":"cursor","in":"query","description":"Pagination cursor from previous response","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size (default 20, max 20)","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"sort","in":"query","description":"Sort order (date_desc, date_asc, price_desc, price_asc)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cursor-paginated eBay sold listings, one row per eBay sale: a sale present more than once in our data is collapsed to the copy that recorded the most about itself. Because collapsing happens after the page is read, a page may return fewer rows than `limit` while `has_more` is still true — follow `next_cursor`, do not infer the end of the feed from a short page. Every row carries an `attribution` of exact, shared or unknown. `shared` means the comp came from a PriceCharting page this card shares with another entity, so the same sale appears in both feeds. `unknown` means the row predates our recording which printing it came from. `exact` means no sharing is known for that printing — it is the absence of a detected conflict, not a verification that the sale is this exact card, and a source page that silently covers several printings can still surface here as exact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorEbayListings"}}}},"400":{"description":"Invalid cursor or query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Listings require Pro or higher","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate or credit limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"api_key":[]}]}},"/v1/cards/{id}/listings/tcgplayer":{"get":{"tags":["listings"],"operationId":"tcgplayer_card_listings","parameters":[{"name":"id","in":"path","description":"Card ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"condition","in":"query","description":"Filter by condition","required":false,"schema":{"type":"string"}},{"name":"language","in":"query","description":"Filter by language","required":false,"schema":{"type":"string"}},{"name":"printing","in":"query","description":"Filter by printing","required":false,"schema":{"type":"string"}},{"name":"min_price","in":"query","description":"Minimum listing price","required":false,"schema":{"type":"number","format":"double"}},{"name":"max_price","in":"query","description":"Maximum listing price","required":false,"schema":{"type":"number","format":"double"}},{"name":"cursor","in":"query","description":"Pagination cursor from previous response","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size (default 20, max 20)","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"sort","in":"query","description":"Sort order","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cursor-paginated TCGPlayer marketplace listings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorTcgplayerListings"}}}},"400":{"description":"Invalid cursor or query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Listings require Pro or higher","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate or credit limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"api_key":[]}]}},"/v1/cards/{id}/prices/history":{"get":{"tags":["listings"],"operationId":"price_history","parameters":[{"name":"id","in":"path","description":"Card ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"period","in":"query","description":"History window in days (default 30d, e.g. 7d, 90d; max 365d)","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size (default 30, max 365)","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"page","in":"query","description":"Page number (default 1)","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"currency","in":"query","description":"Filter by currency (USD or EUR)","required":false,"schema":{"type":"string"}},{"name":"condition","in":"query","description":"Filter by condition, e.g. Near Mint (TCGplayer) or Excellent (Cardmarket)","required":false,"schema":{"type":"string"}},{"name":"variant","in":"query","description":"Filter by printing variant, e.g. Holofoil","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated price history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedPriceHistory"}}}},"400":{"description":"Invalid period or query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Price history requires Pro or higher","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate or credit limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"api_key":[]}]}},"/v1/sealed":{"get":{"tags":["sealed"],"operationId":"list_sealed","parameters":[{"name":"set_id","in":"query","description":"Filter by set ID","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"name","in":"query","description":"Substring match on product name","required":false,"schema":{"type":"string"}},{"name":"language","in":"query","description":"Filter by language","required":false,"schema":{"type":"string"}},{"name":"currency","in":"query","description":"Currency for price filters (USD or EUR)","required":false,"schema":{"type":"string"}},{"name":"min_price","in":"query","description":"Minimum market price","required":false,"schema":{"type":"number","format":"double"}},{"name":"max_price","in":"query","description":"Maximum market price","required":false,"schema":{"type":"number","format":"double"}},{"name":"sort","in":"query","description":"Sort order (price_asc, price_desc, or default by id)","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Page number (default 1)","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"per_page","in":"query","description":"Page size (default 50, max 100)","required":false,"schema":{"type":"integer","format":"int32","minimum":0}}],"responses":{"200":{"description":"Paginated sealed product summaries. Prices are omitted; use GET /v1/sealed/{id} for prices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedSealedSummary"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Sealed products require Pro or Business tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate or credit limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"api_key":[]}]}},"/v1/sealed/{id}":{"get":{"tags":["sealed"],"operationId":"get_sealed","parameters":[{"name":"id","in":"path","description":"Sealed product ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"currency","in":"query","description":"Filter prices by currency (USD or EUR)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sealed product with prices","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SealedResponse"}}}},"400":{"description":"Invalid currency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Sealed products require Pro or Business tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Sealed product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate or credit limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"api_key":[]}]}},"/v1/sealed/{id}/listings/cardmarket":{"get":{"tags":["listings"],"operationId":"cardmarket_sealed_listings","parameters":[{"name":"id","in":"path","description":"Sealed product ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"condition","in":"query","description":"Filter by native Cardmarket condition; sealed offers usually carry none","required":false,"schema":{"type":"string"}},{"name":"min_price","in":"query","description":"Minimum listing price in EUR","required":false,"schema":{"type":"number","format":"double"}},{"name":"max_price","in":"query","description":"Maximum listing price in EUR","required":false,"schema":{"type":"number","format":"double"}},{"name":"cursor","in":"query","description":"Pagination cursor from previous response","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size (default 20, max 20)","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"sort","in":"query","description":"Sort order (price_asc or price_desc)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cursor-paginated Cardmarket marketplace listings for a sealed product. Rows flagged signed, altered or graded are included but are excluded from market price derivation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorCardmarketListings"}}}},"400":{"description":"Invalid cursor or query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Listings require Pro or higher","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate or credit limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"api_key":[]}]}},"/v1/sealed/{id}/listings/ebay":{"get":{"tags":["listings"],"operationId":"ebay_sealed_listings","parameters":[{"name":"id","in":"path","description":"Sealed product ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"min_price","in":"query","description":"Minimum sale price","required":false,"schema":{"type":"number","format":"double"}},{"name":"max_price","in":"query","description":"Maximum sale price","required":false,"schema":{"type":"number","format":"double"}},{"name":"since","in":"query","description":"Only comps ingested after this instant (RFC 3339 timestamp or YYYY-MM-DD). Checkpoint on ingested_at, not sold_at","required":false,"schema":{"type":"string"}},{"name":"cursor","in":"query","description":"Pagination cursor from previous response","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size (default 20, max 20)","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"sort","in":"query","description":"Sort order (date_desc, date_asc, price_desc, price_asc)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cursor-paginated eBay sold listings for sealed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorEbayListings"}}}},"400":{"description":"Invalid cursor or query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Listings require Pro or higher","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate or credit limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"api_key":[]}]}},"/v1/sealed/{id}/listings/tcgplayer":{"get":{"tags":["listings"],"operationId":"tcgplayer_sealed_listings","parameters":[{"name":"id","in":"path","description":"Sealed product ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"condition","in":"query","description":"Filter by condition (sealed offers are normally 'Unopened')","required":false,"schema":{"type":"string"}},{"name":"language","in":"query","description":"Filter by language","required":false,"schema":{"type":"string"}},{"name":"printing","in":"query","description":"Filter by printing","required":false,"schema":{"type":"string"}},{"name":"min_price","in":"query","description":"Minimum listing price","required":false,"schema":{"type":"number","format":"double"}},{"name":"max_price","in":"query","description":"Maximum listing price","required":false,"schema":{"type":"number","format":"double"}},{"name":"cursor","in":"query","description":"Pagination cursor from previous response","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size (default 20, max 20)","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"sort","in":"query","description":"Sort order","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cursor-paginated TCGPlayer marketplace listings for a sealed product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorTcgplayerListings"}}}},"400":{"description":"Invalid cursor or query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Listings require Pro or higher","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate or credit limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"api_key":[]}]}},"/v1/sealed/{id}/prices/history":{"get":{"tags":["listings"],"operationId":"sealed_price_history","parameters":[{"name":"id","in":"path","description":"Sealed product ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"period","in":"query","description":"History window in days (default 30d, e.g. 7d, 90d; max 365d)","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size (default 30, max 365)","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"page","in":"query","description":"Page number (default 1)","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"currency","in":"query","description":"Filter by currency (USD or EUR)","required":false,"schema":{"type":"string"}},{"name":"condition","in":"query","description":"Filter by condition, e.g. Near Mint (TCGplayer) or Excellent (Cardmarket)","required":false,"schema":{"type":"string"}},{"name":"variant","in":"query","description":"Filter by printing variant, e.g. Holofoil","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated sealed product price history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedPriceHistory"}}}},"400":{"description":"Invalid period or query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Price history requires Pro or higher","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate or credit limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"api_key":[]}]}},"/v1/sets":{"get":{"tags":["sets"],"operationId":"list_sets","parameters":[{"name":"name","in":"query","description":"Substring match on set name","required":false,"schema":{"type":"string"}},{"name":"language","in":"query","description":"Filter by language","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Page number (default 1)","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"per_page","in":"query","description":"Page size (default 50, max 100)","required":false,"schema":{"type":"integer","format":"int32","minimum":0}}],"responses":{"200":{"description":"Paginated sets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedSetResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate or credit limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"api_key":[]}]}},"/v1/sets/{id}":{"get":{"tags":["sets"],"operationId":"get_set","parameters":[{"name":"id","in":"path","description":"Set ID","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetResponse"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Set not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"api_key":[]}]}}},"components":{"schemas":{"CardResponse":{"type":"object","required":["id","name","attacks","set","prices"],"properties":{"ability":{"type":["string","null"]},"artist":{"type":["string","null"]},"attacks":{"type":"array","items":{"type":"string"}},"card_type":{"type":["string","null"]},"cardmarket_product_id":{"type":["integer","null"],"format":"int64"},"cardmarket_url":{"type":["string","null"]},"energy_type":{"type":["array","null"],"items":{"type":"string"}},"flavor_text":{"type":["string","null"]},"hp":{"type":["integer","null"],"format":"int32"},"id":{"type":"integer","format":"int64"},"image_url":{"type":["string","null"]},"name":{"type":"string"},"number":{"type":["string","null"]},"prices":{"type":"array","items":{"$ref":"#/components/schemas/PriceResponse"}},"rarity":{"type":["string","null"]},"resistance":{"type":["string","null"]},"retreat_cost":{"type":["integer","null"],"format":"int32"},"set":{"$ref":"#/components/schemas/CardSetInfo"},"stage":{"type":["string","null"]},"tcg_player_id":{"type":["integer","null"],"format":"int64","description":"Null for cards with no TCGPlayer product, e.g. German-language cards."},"total_set_number":{"type":["string","null"]},"weakness":{"type":["string","null"]}}},"CardSetInfo":{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}},"CardSummary":{"type":"object","description":"List view of a card. Prices are intentionally omitted — fetch a single\ncard (`/v1/cards/{id}`) to get prices.","required":["id","name","set"],"properties":{"artist":{"type":["string","null"]},"hp":{"type":["integer","null"],"format":"int32"},"id":{"type":"integer","format":"int64"},"image_url":{"type":["string","null"]},"name":{"type":"string"},"number":{"type":["string","null"]},"rarity":{"type":["string","null"]},"set":{"$ref":"#/components/schemas/CardSetInfo"},"tcg_player_id":{"type":["integer","null"],"format":"int64","description":"Null for cards with no TCGPlayer product, e.g. German-language cards."},"total_set_number":{"type":["string","null"]}}},"CardmarketListingResponse":{"type":"object","required":["id","price","variant","updated_at","signed","altered","graded","opened"],"properties":{"altered":{"type":"boolean"},"article_id":{"type":["integer","null"],"format":"int64"},"comment":{"type":["string","null"]},"condition":{"type":["string","null"]},"grade":{"type":["string","null"]},"graded":{"type":"boolean"},"grader":{"type":["string","null"],"description":"Named to match the graded eBay sale shape (`ListingResponse.grader` /\n`.grade`), so a caller renders \"PSA 10\" the same way whichever source\nit came from. Null unless `graded` is true, and possibly null even\nthen -- Cardmarket flags a slab without always naming the grader."},"id":{"type":"integer","format":"int64"},"language":{"type":["string","null"]},"opened":{"type":"boolean","description":"The offer's own seller says the product is not sealed -- an opened\nwrapper or a display missing its shrink. Sealed products only; always\nfalse on a card listing, where the distinction does not exist. Treated\nlike `signed`/`altered`/`graded`: a real offer, excluded from price\nderivation, which is why the cheapest offer on a sealed product is\nsometimes not its price."},"price":{"type":"number","format":"double"},"quantity":{"type":["integer","null"],"format":"int32"},"sell_count":{"type":["integer","null"],"format":"int32","description":"The seller's completed sales, as Cardmarket reports them. This is the\ninput to the rule that decides whether an offer may set a price -- an\noffer from a seller with no completed sales does not -- so it is the\nfield that explains a market price sitting above the cheapest offer.\n\nNull means no count was recorded for this row, which is **not** zero\nsales: zero is a seller Cardmarket reports as having sold nothing."},"seller":{"type":["string","null"]},"signed":{"type":"boolean","description":"Cardmarket's per-listing special attributes, read off the icons on the\noffer row. Any of these being true means the offer is real but is\n**not** counted towards the card's market price: a signed and altered\nNear Mint copy at EUR 200 must not set the Near Mint price of a card\nwhose clean copies sell for EUR 3,800, and a graded slab is priced for\nthe slab rather than the card."},"updated_at":{"type":"string"},"variant":{"type":"string"}}},"CursorCardmarketListings":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CardmarketListingResponse"}},"pagination":{"$ref":"#/components/schemas/CursorMeta"}}},"CursorEbayListings":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ListingResponse"}},"pagination":{"$ref":"#/components/schemas/CursorMeta"}}},"CursorMeta":{"type":"object","required":["has_more","count"],"properties":{"count":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"CursorTcgplayerListings":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TcgplayerListingResponse"}},"pagination":{"$ref":"#/components/schemas/CursorMeta"}}},"ErrorBody":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","required":["code","message","docs_url"],"properties":{"code":{"type":"string"},"docs_url":{"type":"string","description":"Documentation for this class of error. A 401 that only says \"invalid\nkey\" is a dead end; the section that explains how to get and send one\nis the next thing the caller needs.","example":"https://www.pkmnprices.com/docs#authentication"},"message":{"type":"string"}}},"HealthResponse":{"type":"object","required":["status","database","version","timestamp"],"properties":{"database":{"type":"string"},"status":{"type":"string"},"timestamp":{"type":"string","description":"Server time this check ran, RFC 3339. Distinguishes a live healthy\nresponse from a cached one.","example":"2026-09-04T08:21:37Z"},"version":{"type":"string","description":"Deployed API version. Lets an integrator tell whether the API changed\nunder them, and gives support a build to reference.","example":"0.1.0"}}},"ListPrice":{"type":"object","description":"A single resolved price for a list tile. `condition`/`variant`/`currency`\necho back which best-available condition and printing were selected.\n`market_price` is null when the item has no price matching the filters.","properties":{"condition":{"type":["string","null"]},"currency":{"type":["string","null"]},"market_price":{"type":["number","null"],"format":"double"},"variant":{"type":["string","null"]}}},"ListingAttribution":{"type":"string","description":"Whether a sold comp describes this card alone.\n\nPriceCharting's catalogue is coarser than TCGplayer's, so several card\nentities can be mapped to one product page — a Pokemon Center stamp and the\nbase promo, a deck exclusive and the set card. Comps collected under a\nshared page are served under every card mapped to it, with titles that\ndescribe whichever printing the seller actually sold. Saying so is what\nlets an integrator price a variant off its own evidence rather than\ndiscard the feed.","enum":["exact","shared","unknown"]},"ListingResponse":{"type":"object","required":["id","title","price","attribution","sold_at","ingested_at"],"properties":{"attribution":{"$ref":"#/components/schemas/ListingAttribution"},"grade":{"type":["string","null"]},"grade_qualifier":{"type":["string","null"],"description":"Which tier of `grade` this sale is, when the grader issues more than one\nat that number: \"Pristine\" for a CGC 10 that is not a Gem Mint, \"Black\nLabel\" for a BGS 10 that is not a plain 10. A Pristine ten sells well\nabove a Gem Mint ten, so a population that mixes them prices neither.\n\nNull is the tier with no name of its own -- which is nearly every comp,\nincluding every grade from a grader that issues only one at a number.\n\nAdditive on purpose: `grade` still reads \"10\" for all of them, so a\nfilter on `grade=10` returns exactly what it returned before this field\nexisted. Split the population by reading this; nothing shrinks unless\nyou ask it to."},"grader":{"type":["string","null"]},"id":{"type":"integer","format":"int64"},"ingested_at":{"type":"string","description":"When this comp entered our data, as RFC 3339. Distinct from `sold_at`:\na collection run routinely brings in sales weeks old, so this is the\nfield to checkpoint when polling `since` for new comps."},"listing_url":{"type":["string","null"]},"price":{"type":"number","format":"double"},"sold_at":{"type":"string"},"title":{"type":"string"},"variant":{"type":["string","null"],"description":"The PriceCharting printing this comp was collected under, e.g.\n\"Holofoil\". Null on comps ingested before printings were recorded."}}},"PaginatedCardSummary":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CardSummary"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}}},"PaginatedPriceHistory":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceHistoryResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}}},"PaginatedSealedSummary":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SealedSummary"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}}},"PaginatedSetResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SetResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}}},"PaginationMeta":{"type":"object","required":["page","per_page","total","total_pages"],"properties":{"page":{"type":"integer","format":"int32","minimum":0},"per_page":{"type":"integer","format":"int32","minimum":0},"total":{"type":"integer","format":"int64"},"total_pages":{"type":"integer","format":"int32","minimum":0}}},"PriceHistoryResponse":{"type":"object","required":["date","source","currency"],"properties":{"avg":{"type":["number","null"],"format":"double"},"condition":{"type":["string","null"]},"currency":{"type":"string"},"date":{"type":"string"},"high":{"type":["number","null"],"format":"double"},"low":{"type":["number","null"],"format":"double"},"sale_count":{"type":["integer","null"],"format":"int64"},"source":{"type":"string"},"variant":{"type":["string","null"]}}},"PriceResponse":{"type":"object","required":["source","currency","created_at"],"properties":{"condition":{"type":["string","null"]},"created_at":{"type":"string"},"currency":{"type":"string"},"market_price":{"type":["number","null"],"format":"double"},"source":{"type":"string"},"variant":{"type":["string","null"]}}},"SealedResponse":{"type":"object","required":["id","tcg_player_id","name","set","prices"],"properties":{"cardmarket_product_id":{"type":["integer","null"],"format":"int64"},"cardmarket_url":{"type":["string","null"]},"id":{"type":"integer","format":"int64"},"image_url":{"type":["string","null"]},"name":{"type":"string"},"prices":{"type":"array","items":{"$ref":"#/components/schemas/PriceResponse"}},"set":{"$ref":"#/components/schemas/CardSetInfo"},"tcg_player_id":{"type":"integer","format":"int64"}}},"SealedSummary":{"type":"object","description":"List view of a sealed product. Prices are intentionally omitted — fetch a\nsingle product (`/v1/sealed/{id}`) to get prices.","required":["id","tcg_player_id","name","set"],"properties":{"id":{"type":"integer","format":"int64"},"image_url":{"type":["string","null"]},"name":{"type":"string"},"set":{"$ref":"#/components/schemas/CardSetInfo"},"tcg_player_id":{"type":"integer","format":"int64"}}},"SetResponse":{"type":"object","required":["id","name","language"],"properties":{"card_count":{"type":["integer","null"],"format":"int64"},"id":{"type":"integer","format":"int64"},"language":{"type":"string"},"name":{"type":"string"},"tcg_player_id":{"type":["integer","null"],"format":"int64","description":"Null for cards with no TCGPlayer product, e.g. German-language cards."}}},"TcgplayerListingResponse":{"type":"object","required":["id","printing","price","updated_at"],"properties":{"condition":{"type":["string","null"]},"custom_title":{"type":["string","null"]},"direct_seller":{"type":["boolean","null"]},"gold_seller":{"type":["boolean","null"]},"id":{"type":"integer","format":"int64"},"language":{"type":["string","null"]},"listing_id":{"type":["integer","null"],"format":"int64"},"listing_type":{"type":["string","null"]},"price":{"type":"number","format":"double"},"printing":{"type":"string"},"quantity":{"type":["integer","null"],"format":"int32"},"seller_id":{"type":["string","null"]},"seller_name":{"type":["string","null"]},"seller_rating":{"type":["number","null"],"format":"double"},"seller_sales":{"type":["string","null"]},"shipping_price":{"type":["number","null"],"format":"double"},"snapshot_at":{"type":["string","null"],"description":"When this product's listings were last confirmed against TCGplayer, as\nRFC 3339. Same for every row in a response, since a snapshot replaces a\nproduct's listings wholesale. Null if no successful snapshot has been\nrecorded since this field was introduced."},"updated_at":{"type":"string","description":"When this listing's own fields last changed, as RFC 3339. It does NOT\nmove when we re-confirm an unchanged listing, so it is not a freshness\nsignal -- a listing live and unchanged for a month keeps a month-old\nvalue. Read `snapshot_at` for freshness."},"verified_seller":{"type":["boolean","null"]}}}},"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"x-api-key"}}},"tags":[{"name":"health","description":"Service health"},{"name":"sets","description":"TCG sets"},{"name":"cards","description":"Cards and prices"},{"name":"sealed","description":"Sealed products"},{"name":"listings","description":"Sold comps and marketplace listings"}]}