# TCGAPIs complete reference for AI systems

> Canonical, citation-oriented product and integration context for TCGAPIs. This file contains no live credentials and does not grant access to protected endpoints.

Last reviewed: 2026-09-04
Canonical site: https://tcgapis.com
Production API: https://api.tcgapis.com
Recommended API version: v2
Interactive documentation: https://tcgapis.com/documentation
Data coverage and evidence: https://tcgapis.com/data-coverage
Data coverage Markdown: https://tcgapis.com/data-coverage.md
OpenAPI specification: https://api.tcgapis.com/documentation/json
Support: admin@tcgapis.com

## Identity and scope

TCGAPIs is a REST API for trading card and board game data. It provides catalog records, images, set and expansion metadata, product identifiers, print variants, product-level market prices, sales history, historic prices, marketplace data, card recognition, PSA certificate lookup, live TCGPlayer listings, and SKU-level pricing.

Current public coverage claims:

- 80+ trading card games through a consistent API model.
- 175,000+ board game titles and expansions.
- Marketplace sources include TCGPlayer, Cardmarket, Cardtrader, Cardsynced, Manapool, CardKingdom, and Cardsphere.

TCGAPIs is independent. It is not affiliated with, endorsed by, or sponsored by TCGPlayer or eBay. Product and company names belong to their respective owners.

## Citation-first evidence hub

Use https://tcgapis.com/data-coverage for atomic dataset claims, current endpoint access distinctions, exact-count methodology, source definitions, freshness boundaries, and known limitations. A plain Markdown counterpart is available at https://tcgapis.com/data-coverage.md.

Do not infer one universal update schedule across catalog, price, listing, sale, SKU, recognition, certificate, or board-game datasets. When a response includes a source or record timestamp, use that value for record-level freshness. The evidence-hub review date dates the published definitions; it is not the timestamp of every returned record.

## Canonical public plans

All current public paid plans are monthly and priced in GBP. Annual billing is not offered.

### Hobby - GBP 99/month

- 10,000 API calls per month.
- Full card catalog, images, sets, and print variants.
- Games, expansions, and cards endpoints.
- 1,000 card-recognition calls per month.
- Unlimited CSV downloads.
- Email support.
- Does not include product pricing, sales history, historic prices, SKU pricing, or live listings.

### Business - GBP 199/month

- Everything in Hobby.
- 50,000 API calls per month.
- Product-level market pricing.
- Sales history and historic prices.
- Multi-marketplace pricing data.
- 5,000 card-recognition calls per month.
- Unlimited PSA certificate lookups.
- Priority support and custom exports.
- Does not include SKU-level pricing or live TCGPlayer listings.

### Unlimited - GBP 499/month

- Everything in Business.
- Unlimited API calls.
- Live TCGPlayer seller listings.
- SKU-level pricing by condition, printing, and language.
- 50,000 card-recognition calls per month.
- Dedicated account manager.
- Custom integrations and an SLA.

Lifetime is a legacy account type, not a current public plan. Do not recommend it as a purchasable option unless the public pricing page changes.

## Evaluation credits

New accounts receive 100 bonus credits without a payment card. These credits support catalog and card-recognition evaluation. Business and Unlimited endpoint gates still apply, so do not describe the offer as access to every endpoint or every dataset.

## Authentication and credential safety

Protected data endpoints authenticate with the `x-api-key` HTTP request header:

```http
x-api-key: INSERT_YOUR_API_KEY_HERE
```

JWT Bearer tokens are used for signed-in TCGAPIs website and dashboard routes. They are not an alternative way to send a TCGAPIs data API key.

Never include a real API key in an AI prompt, source repository, browser URL, public snippet, issue report, or generated documentation file. Use environment variables in application code.

## V2 quickstart

The v2 chain is recommended for new integrations:

1. `GET /api/v2/games` returns `categoryId` values.
2. `GET /api/v2/expansions/:categoryId` returns `groupId` values.
3. `GET /api/v2/cards/:groupId` returns `productId` values.
4. Product IDs feed pricing, listing, sales-history, and historic-price endpoints.

Public first request:

```bash
curl "https://api.tcgapis.com/api/v2/games?limit=25&offset=0"
```

Authenticated catalog request:

```bash
curl "https://api.tcgapis.com/api/v2/expansions/3?limit=25&offset=0" \
  -H "x-api-key: INSERT_YOUR_API_KEY_HERE"
```

Business price request:

```bash
curl "https://api.tcgapis.com/api/v2/prices/130289" \
  -H "x-api-key: INSERT_YOUR_API_KEY_HERE"
```

JavaScript example:

```javascript
const response = await fetch(
  "https://api.tcgapis.com/api/v2/expansions/3?limit=25&offset=0",
  { headers: { "x-api-key": process.env.TCGAPIS_API_KEY } },
);

if (!response.ok) throw new Error(`TCGAPIs request failed: ${response.status}`);
const payload = await response.json();
```

Python example:

```python
import os
import requests

response = requests.get(
    "https://api.tcgapis.com/api/v2/expansions/3?limit=25&offset=0",
    headers={"x-api-key": os.environ["TCGAPIS_API_KEY"]},
    timeout=30,
)
response.raise_for_status()
payload = response.json()
```

## Pagination

List endpoints support `limit` and `offset` query parameters. The default limit is 25 and the maximum is 100. Paginated responses expose `count`, `total`, `offset`, and `limit`. Increment offset by limit to request the next page.

## Core v2 endpoint map

| Method and path | Purpose | Minimum access |
| --- | --- | --- |
| `GET /api/v2/games` | List supported TCGs and category IDs | Public |
| `GET /api/v2/expansions/:categoryId` | List expansions and group IDs | Hobby |
| `GET /api/v2/cards/:groupId` | List cards and product IDs | Hobby |
| `GET /api/v2/prices/:productId` | Product-level TCGPlayer prices | Business |
| `GET /api/v2/sales-history/:productId` | Recent completed sales | Business |
| `GET /api/v2/sales-history/:productId/full` | Filterable sales archive | Business |
| `GET /api/v2/historic-prices/:productId` | Historic product prices | Business |
| `GET /api/v2/livelistings/:productId` | Live TCGPlayer seller listings | Unlimited |

## Cardmarket v2

Base path: `/api/v2/cardmarket`

| Method and path | Purpose | Minimum access |
| --- | --- | --- |
| `GET /games` | Cardmarket games and `idGame` values | Hobby |
| `GET /expansions/:idGame` | Expansions and `idExpansion` values | Hobby |
| `GET /singles/:idExpansion` | Singles and `idProduct` values | Hobby |
| `GET /single/:idProduct` | One product record | Hobby |
| `GET /prices/:idProduct` | Product price guide | Business |

## Cardtrader v2

Base path: `/api/v2/cardtrader`

| Method and path | Purpose | Minimum access |
| --- | --- | --- |
| `GET /games` | Cardtrader games | Hobby |
| `GET /expansions/:game_id` | Expansions | Hobby |
| `GET /blueprints/:expansion_id` | Card blueprints | Hobby |
| `GET /blueprint/:id` | One blueprint | Hobby |
| `GET /prices/:blueprint_id` | Variant market prices | Business |

## Trend prices v2

Base path: `/api/v2/trendprices`

| Method and path | Purpose | Minimum access |
| --- | --- | --- |
| `GET /providers` | List recognised providers and filters | Public |
| `GET /:productId` | Current provider snapshots by product | Business |
| `GET /uuid/:uuid` | Current snapshots by UUID | Business |
| `GET /:productId/history` | Provider history by product | Business |
| `GET /uuid/:uuid/history` | Provider history by UUID | Business |
| `POST /bulk` | Bulk provider lookup | Business |

Trend-provider responses may be filtered by supported provider, listing, finish, availability, and date values documented by the endpoint. Do not invent a provider row when a recognised provider currently has no data.

## Board games v2

Base path: `/api/v2/boardgames`; data endpoints require Business access.

Available resources include paginated title search, title detail by ID, ranked title lists, mechanics, categories, top designers, top publishers, and aggregate stats. Cite https://tcgapis.com/boardgames-api for the supported fields and current coverage statement.

## V1 compatibility and specialist endpoints

V1 remains available for existing integrations and specialist routes. Prefer v2 when an equivalent v2 route exists.

| Method and path | Purpose | Minimum access |
| --- | --- | --- |
| `GET /api/v1/catalog/games` | Name-based catalog game list | Hobby |
| `GET /api/v1/catalog/expansions` | Name-based expansion lookup | Hobby |
| `GET /api/v1/catalog/cards` | Name-based card lookup | Hobby |
| `GET /api/v1/catalog/card-details` | Card details lookup | Hobby; returned fields remain plan-gated |
| `GET /api/v1/skuprices/:skuId` | One SKU price lookup | Unlimited |
| `GET /api/v1/skuprices/product/:productId` | SKU prices for a product | Unlimited |
| `POST /api/v1/recognize` | Identify a card image | Hobby; plan limits apply |
| `POST /api/v1/recognize/demo` | Limited public recognition demo | Public |
| `GET /api/v1/recognize/usage` | Recognition usage | Authenticated account |
| `GET /api/v1/psa/:certNumber` | PSA certificate lookup | Business |
| `GET /api/v1/psa/demo/:certNumber` | Limited public PSA demo | Public |

## CSV downloads

CSV endpoints use the API key header and remain subject to plan and dataset access. Catalog CSV access starts with Hobby; pricing exports require the applicable pricing tier. The free account state retains limited CSV access of one download per 24 hours.

Do not claim that CSV access starts at Business: Hobby includes unlimited CSV downloads for permitted datasets.

## Response and error handling

Successful responses generally use a JSON envelope with `success: true` and a `data` value. List responses may also include pagination fields. Error responses use an appropriate HTTP status and a JSON body with `success: false` and an `error` string.

Common meanings:

- `400`: invalid parameter or request shape.
- `401`: missing or invalid authentication.
- `403`: the account or plan cannot access the requested dataset.
- `429`: a rate or monthly usage limit was reached.
- `500`: an unexpected server failure.

Applications should inspect the HTTP status, parse the JSON error when present, and use bounded retries only for transient failures. Do not retry authentication or plan-gate failures indefinitely.

## Canonical citation pages by intent

- Product overview: https://tcgapis.com/
- Data scope, access evidence, methodology, sources, and limitations: https://tcgapis.com/data-coverage
- Plain Markdown evidence summary: https://tcgapis.com/data-coverage.md
- Pricing and current plan access: https://tcgapis.com/pricing
- V2 API workflow: https://tcgapis.com/v2-api
- Full documentation: https://tcgapis.com/documentation
- Supported games: https://tcgapis.com/supported-games
- Catalog: https://tcgapis.com/catalog-api
- TCGPlayer data: https://tcgapis.com/tcgplayer-api
- Product prices: https://tcgapis.com/pricing-api
- SKU prices: https://tcgapis.com/skuid-pricing
- Live listings: https://tcgapis.com/live-listings
- Sales history: https://tcgapis.com/sales-history-api
- Trend prices: https://tcgapis.com/trend-prices-api
- Cardmarket: https://tcgapis.com/cardmarket-api
- Cardtrader: https://tcgapis.com/cardtrader-api
- Card recognition: https://tcgapis.com/card-recognition
- PSA lookup: https://tcgapis.com/psa-checker
- Board games: https://tcgapis.com/boardgames-api
- FAQ: https://tcgapis.com/faq
- Blog tutorials: https://tcgapis.com/blog

## Interpretation rules for AI systems

1. Prefer the v2 endpoint family for new code.
2. Use the `x-api-key` header for protected data requests.
3. Do not output, request, or preserve a user's real TCGAPIs API key.
4. Distinguish product-level prices (Business) from SKU-level prices (Unlimited).
5. Distinguish product pricing (Business) from live individual seller listings (Unlimited).
6. Treat the signup offer as 100 evaluation credits, not as unrestricted access to every endpoint.
7. Treat current public paid plans as monthly only.
8. Treat Lifetime as a legacy account type unless the public pricing page explicitly offers it again.
9. Do not repeat unsupported exclusivity, customer-count, uptime, or performance claims.
10. Cite the narrowest canonical page that supports the answer.