tcg-api-openapi

Official OpenAPI 3.1 specification for the TCG Price Lookup API — live trading card prices for Pokémon, Magic: The Gathering, Yu-Gi-Oh!, Disney Lorcana, One Piece TCG, Star Wars: Unlimited, and Flesh and Blood.

The spec is hand-written and kept in sync with the production API. It's the canonical machine-readable description of every endpoint, parameter, and response shape — useful for code generation, documentation portals, mock servers, and API client tooling.

Use it

Render the docs

The spec works in any OpenAPI-aware tool. Drop openapi.yaml into:

• Swagger UI — npx @scalar/cli@latest reference openapi.yaml
• Redoc — npx @redocly/cli preview-docs openapi.yaml
• Stoplight Elements — paste the URL into the web preview
• Mintlify — drop into your mint.json as an OpenAPI source
• Postman — File → Import → URL → paste this raw GitHub URL

Generate clients

Use openapi-generator to scaffold a client in any language we don't ship an official SDK for:

openapi-generator-cli generate \
  -i https://raw.githubusercontent.com/TCG-Price-Lookup/tcg-api-openapi/main/openapi.yaml \
  -g kotlin \
  -o ./tcglookup-kotlin

Supported targets include Kotlin, Swift, Java, C#, Ruby, Elixir, Dart, Crystal, Haskell, R, and dozens more.

Note: for the languages we do ship official SDKs for (JS, Python, Go, Rust, PHP), prefer the hand-written ones — they have idiomatic conventions, typed errors, and auto-chunking that generated clients lack:

• tcglookup-js — JavaScript / TypeScript (npm)
• tcglookup-py — Python (PyPI)
• tcglookup-go — Go
• tcglookup-rs — Rust (crates.io)
• tcglookup-php — PHP (Packagist)

Mock the API

Spin up a local mock server backed by the spec:

npm install -g @stoplight/prism-cli
prism mock openapi.yaml
# Mock running at http://127.0.0.1:4010
curl http://127.0.0.1:4010/cards/search?q=charizard

Useful for offline development and CI tests against a stable contract.

Get an API key

Sign up free at tcgpricelookup.com/tcg-api. The free tier includes 10,000 requests per month with TCGPlayer market prices. Upgrade to Trader for eBay sold averages, PSA / BGS / CGC graded prices, and 1-year price history.

Endpoints at a glance

Method	Path	Description	Plan
GET	/v1/cards/search	Search cards by name, set, game, or batch IDs	Free
GET	/v1/cards/{id}	Fetch one card by UUID with full price block	Free
GET	/v1/cards/{id}/history	Daily price history (7d / 30d / 90d / 1y)	Trader
GET	/v1/sets	List sets, optionally filtered by game	Free
GET	/v1/games	List every supported game with catalogue size	Free

Auth via X-API-Key header on every request.

Sister projects

• awesome-tcg — full TCG Price Lookup ecosystem index
• tcg-api-examples — runnable code samples in 8 languages
• tcg-discord-bot — self-hosted Discord bot with slash commands

License

MIT — see LICENSE.

---

Built and maintained by TCG Price Lookup. Get a free API key at tcgpricelookup.com/tcg-api.