---
title: "OpenAPI (Swagger) Spec: JustTCG API"
description: "Download the JustTCG OpenAPI 3.0 (Swagger) specification at justtcg.com/docs/swagger.json. Import it into Swagger UI, Postman or Insomnia, or generate a typed client for the TCG pricing API."
url: https://justtcg.com/docs/openapi
markdown_url: https://justtcg.com/docs/openapi.md
---

# 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

`GET https://justtcg.com/docs/swagger.json`

Format

OpenAPI 3.0.3 (JSON)

Spec version

1.1.2

Last updated

November 3, 2026

Auth

`x-api-key` header

**Always fetch the live URL.** The spec changes as the API grows (see the [changelog](https://justtcg.com/docs/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](https://justtcg.com/docs/api/games) | List all games | getGames |
| GET[/v1/sets](https://justtcg.com/docs/api/sets) | List all sets | getSets |
| GET[/v1/cards](https://justtcg.com/docs/api/cards) | Search or Lookup Cards | getCards |
| POST[/v1/cards](https://justtcg.com/docs/api/cards) | Batch Card Lookup | batchGetCards |
| GET[/v2/cards](https://justtcg.com/docs/api/cards-v2) | Search, browse or look up cards (beta) | getCardsV2 |
| GET[/v2/cards/{id}](https://justtcg.com/docs/api/cards-v2) | Get one card by ID (beta) | getCardV2 |

Schemas included: `GamesResponse`, `SetsResponse`, `CardsResponse`, `Game`, `Set`, `Card`, `Variant`, `BatchCardRequestItem`, `PaginationMeta`, `UsageMetadata`, `Error`, `CardV2`, `GameplayV2`, `PrintDetailsV2`, `VariantV2`, `GradingV2`, `MarketV2`, `PeriodStatsV2`, `PricePoint`, `PaginationMetaV2`, `CardsV2Response`, `CardV2Response`, `Problem`. Field-level detail is on the [Card](https://justtcg.com/docs/schema/card) and [Variant](https://justtcg.com/docs/schema/variant) schema pages.

**v2 operations are beta.** The [/v2/cards](https://justtcg.com/docs/api/cards-v2) 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 (`POST /v2/cards`) is live but not in the spec yet; see [v2 batch](https://justtcg.com/docs/api/cards-v2/batch).

## 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](https://justtcg.com/dashboard) 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](https://justtcg.com/docs/sdk) is already typed and is usually the faster route.

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

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

```bash
# 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](https://justtcg.com/docs/api/mcp) gives the same data without any glue code. A plain-text summary of the API for LLMs is at [/llms.txt](https://justtcg.com/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 (POST /v2/cards) is live but not in the spec yet; it is documented at justtcg.com/docs/api/cards-v2/batch.

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.