Does JustTCG have an OpenAPI or Swagger spec?

Yes. JustTCG publishes a public OpenAPI 3.0.3 (Swagger) specification at https://justtcg.com/docs/swagger.json. No API key is needed to download it; you only need a key to call the API itself.

Is the JustTCG OpenAPI spec kept up to date?

Yes. The spec is updated alongside the API and the documentation, and notable changes are recorded in the changelog. Always fetch it from the canonical URL rather than keeping a copy, so tools and agents pick up new parameters automatically.

Does the OpenAPI spec cover the v2 endpoints?

Yes. Alongside the stable v1 API (/v1/games, /v1/sets and /v1/cards, including batch POST /v1/cards), the spec describes the /v2/cards beta: GET /v2/cards and GET /v2/cards/{id}, with graded variants, the per-region markets array, cursor pagination and problem+json errors. v2 operations are tagged "v2 (beta)" and marked x-beta. v2 batch lookups are not live yet, so they are not in the spec.

How do I authenticate requests made from the spec?

The spec declares an apiKey security scheme: send your key in the x-api-key header. In Swagger UI, Postman or Insomnia, set it once as the API key for the collection and every request inherits it.

OpenAPI (Swagger) spec

OpenAPI 3.0.3

The complete, machine-readable definition of the JustTCG REST API. Import it into Swagger UI or Postman, generate a typed client, or give it to an AI agent. No API key needed to download it.

Spec URL

GEThttps://justtcg.com/docs/swagger.json

Format: OpenAPI 3.0.3 (JSON)
Spec version: 1.1.0
Last updated: September 22, 2026
Auth: x-api-key header

Always fetch the live URL.The spec changes as the API grows (see the changelog). Point your tools at https://justtcg.com/docs/swagger.json rather than a saved copy so new parameters show up automatically.

What the spec covers

6 operations across the stable v1 API and the v2 beta, against the base URL https://api.justtcg.com. Paths carry the version prefix. Each links to its full reference page.

Operation	Summary	`operationId`
GET/v1/games	List all games	getGames
GET/v1/sets	List all sets	getSets
GET/v1/cards	Search or Lookup Cards	getCards
POST/v1/cards	Batch Card Lookup	batchGetCards
GET/v2/cards	Search, browse or look up cards (beta)	getCardsV2
GET/v2/cards/{id}	Get one card by ID (beta)	getCardV2

Schemas included: GamesResponse, SetsResponse, CardsResponse, Game, Set, Card, Variant, BatchCardRequestItem, PaginationMeta, UsageMetadata, Error, CardV2, VariantV2, GradingV2, MarketV2, PeriodStatsV2, PricePoint, PaginationMetaV2, CardsV2Response, CardV2Response, Problem. Field-level detail is on the Card and Variant schema pages.

v2 operations are beta.The /v2/cards operations (graded cards and localized pricing) are tagged v2 (beta) and marked x-beta. Their shape is finalized but may still change before general availability, so keep production traffic on v1. v2 batch lookups are not live yet; use POST /v1/cards.

Import into Swagger UI, Postman or Insomnia

The spec is served with open CORS, so browser-based tools can load it straight from the URL.

Swagger Editor / Swagger UI: Open editor.swagger.io, choose File → Import URL, and paste the spec URL.
Postman: Import → Link, paste the spec URL, and generate a collection.
Insomnia: Create → Import → URL, then paste the spec URL.

Then set your API key as the x-api-key value. Get a free key if you don't have one yet.

Generate a client

Any OpenAPI 3 tooling works. Using Node.js or TypeScript? The official justtcg-js SDK is already typed and is usually the faster route.

Download

# Fetch the raw spec, no API key required
curl -s https://justtcg.com/docs/swagger.json -o swagger.json

TypeScript types

# TypeScript types (openapi-typescript)
npx openapi-typescript https://justtcg.com/docs/swagger.json -o justtcg.d.ts

OpenAPI Generator

# Any language (OpenAPI Generator), e.g. a Python client
npx @openapitools/openapi-generator-cli generate \
  -i https://justtcg.com/docs/swagger.json \
  -g python \
  -o ./justtcg-client

Using the spec with AI agents

Agents that build tools from OpenAPI (custom GPT actions, LangChain toolkits, agent frameworks) can load the spec URL directly. For Claude, Cursor, VS Code and other MCP hosts, the hosted JustTCG MCP server gives the same data without any glue code. A plain-text summary of the API for LLMs is at /llms.txt.

FAQ

Does JustTCG have an OpenAPI or Swagger spec?: Yes. JustTCG publishes a public OpenAPI 3.0.3 (Swagger) specification at https://justtcg.com/docs/swagger.json. No API key is needed to download it; you only need a key to call the API itself.
Is the JustTCG OpenAPI spec kept up to date?: Yes. The spec is updated alongside the API and the documentation, and notable changes are recorded in the changelog. Always fetch it from the canonical URL rather than keeping a copy, so tools and agents pick up new parameters automatically.
Does the OpenAPI spec cover the v2 endpoints?: Yes. Alongside the stable v1 API (/v1/games, /v1/sets and /v1/cards, including batch POST /v1/cards), the spec describes the /v2/cards beta: GET /v2/cards and GET /v2/cards/{id}, with graded variants, the per-region markets array, cursor pagination and problem+json errors. v2 operations are tagged "v2 (beta)" and marked x-beta. v2 batch lookups are not live yet, so they are not in the spec.
How do I authenticate requests made from the spec?: The spec declares an apiKey security scheme: send your key in the x-api-key header. In Swagger UI, Postman or Insomnia, set it once as the API key for the collection and every request inherits it.