Documentation

Trading Card Studio APIDocumentation

How to read the multi-game catalog. GET /health and GET /catalog/games need no key. Every other catalog call uses an API key.

Examples call https://api.tradingcardstudio.com/v1

Public catalog

Games, sets, prints, concepts, and sealed products

Sets and prints

Release groups and language coverage

Developer ready

Keys, pagination, and a quickstart

Base URL:

https://api.tradingcardstudio.com/v1

Quick Start

Call the production catalog in four steps. The first request does not need a key. Price data is included on Hobbyist and Builder for select cards where available. Many cards have no price data. Free keys use the same routes and receive empty price fields, with prices_included set to false. On Hobbyist and Builder, the /prices routes return 200 with an empty data array for a card or print that has no price data.

Use the production base URL

Every sample on this page calls the production API. https://api.tradingcardstudio.com/v1

Get an API Key

Create a key in the dashboard. Keep the key on your server and send it as X-API-Key on catalog calls. Only GET /health and GET /catalog/games work without a key.

Get a free API key

Make a Catalog Request

This request is public. Keyed card search uses the same host with X-API-Key. The title list is also on Supported titles

cURL

curl "https://api.tradingcardstudio.com/v1/catalog/games"

Review Pagination and Limits

GET /catalog/games returns the full title list in one object. Catalog list routes accept limit and offset. limit defaults to 50 and is read as a value from 1 to 200. A value below 1 is read as 1, a value above 200 is read as 200, and a non-numeric value is read as 50. offset defaults to 0. Read pagination.total before you request the next page.

Authentication

Only GET /health and GET /catalog/games need no key. Every other catalog call, including games, sets, cards, and prints, sends your API key in the X-API-Key header.

API Key Format

->Issued keys: tv_live_xxxxxxxxxxxxxxxxxxxxxxxx

Security Warning

Never expose API keys in client-side code, public repositories, logs, or screenshots. Use server-side environment variables and rotate keys after accidental exposure.

Authentication Methods

X-API-Key Header

curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/games"

Rate Limits

Each plan includes a monthly allowance of catalog reads, counted per UTC month. Free includes 500 reads, Hobbyist includes 10,000, and Builder includes 50,000.

These GET routes count toward the allowance: /games, /sets, /sets/{setRef}, /cards, /cards/{id}, /cards/{id}/siblings, /cards/{id}/localizations, /cards/{id}/prices, /concepts/{id}, /prints/{id}, and /prints/{id}/prices. Send your API key on these routes. A signed-in session request from the same account counts toward the same allowance.

Price data is included on Hobbyist and Builder for select cards where available. Many cards have no price data. Free keys get the same responses with price fields empty and prices_included: false. A Free call still counts, including when the price fields are empty.

When the allowance is used up, the API returns 429. Wait until 00:00 UTC on the 1st of the next month, or for the number of seconds in Retry-After. A 429 still counts as a request, so wait before you call again. On a 500-read allowance, reads 1–500 succeed and read 501 onward returns 429.

Plan	Monthly catalog reads	API keys
Free	500 / UTC month	1
Hobbyist	10,000 / UTC month	No cap
Builder	50,000 / UTC month	No cap

429 response

HTTP 429 includes Retry-After, the number of seconds until 00:00 UTC on the 1st of the next month. Wait that long, then call the catalog again.

Response Example

Example counts for a 500-request quota. error, message, and window are exact.

{
  "error": "rate_limited",
  "message": "This account has used its monthly catalog request allowance.",
  "window": "month",
  "used": { "monthly": 501 },
  "limits": { "monthly": 500 }
}

Identifiers

The API separates catalog ids from game-native set codes.

Card IDs

97997e2be098df0ff51e0e945dda577a

A card id is 32-character hex. Card routes also accept the same id as a dashed UUID. Card responses use the 32-character hex form. Print and set responses use dashed UUIDs.

Set References

EX-09

Set detail accepts the set code returned by the catalog, such as EX-09. Include game when a code may collide across games.

Response Shape

Successful JSON routes return data. GET /catalog/games returns the full title list with no pagination object. Keyed list routes add pagination with limit, offset, and total. total_is_estimate is true only on GET /cards with no filter or only a game filter. Detail routes return one object inside data. GET /cards/{id}, GET /cards/{id}/prices, GET /prints/{id}, and GET /prints/{id}/prices also return prices_included and upgrade_hint. Errors return error and, on keyed catalog routes, message.

Paginated Cards Response

{
  "data": [
    {
      "id": "97997e2be098df0ff51e0e945dda577a",
      "name": "Abbadomon",
      "card_number": "EX9-055 R",
      "rarity": "r",
      "language_code": "en",
      "game_slug": "digimon-card-game",
      "set_code": "EX-09",
      "set_name": "EXTRA BOOSTER VERSUS MONSTERS",
      "image_url": "https://images.tradingcardstudio.com/card-images/faa8f84b5d4e091fc3bf2257080f9c1600b9d10e13ab84f59113026a32845cdf.png",
      "attributes": { "cost": "11", "level": "Lv.6", "card_type": "Digimon" },
      "updated_at": "2026-10-12T00:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1,
    "total_is_estimate": false
  }
}

Error Response

{
  "error": "unauthorized"
}

Not Found

{
  "error": "set_not_found"
}

API Reference

Public Endpoints

GET/healthPUBLIC

Service health

Checks that the API is up. No API key needed.

Response fields

Field	Type	Description
ok	boolean	true when the API is running.
database	boolean	true when catalog data can be read.
release	string \| null	Current API release, or null.

Example Request

curl "https://api.tradingcardstudio.com/v1/health"

Response Example

{
  "ok": true,
  "database": true,
  "release": null
}

GET/catalog/gamesPUBLIC

Public catalog titles

Lists every game in the catalog with its set, print, card, and sealed-product counts. No API key needed.

Response fields

Field	Type	Description
data[].slug	string	Game slug. Use it as the game filter on other endpoints.
data[].name	string	Game name.
data[].sets	integer	Number of sets.
data[].prints	integer	Number of card prints.
data[].concepts	integer	Number of unique cards. A card printed in several sets or languages counts once.
data[].sealed_products	integer	Number of sealed products, such as boosters and decks.

Example Request

curl "https://api.tradingcardstudio.com/v1/catalog/games"

Response Example

{
  "data": [
    {
      "slug": "pokemon",
      "name": "Pokemon TCG",
      "sets": 1717,
      "prints": 172457,
      "concepts": 154834,
      "sealed_products": 12534
    },
    {
      "slug": "one-piece-card-game",
      "name": "One Piece Card Game",
      "sets": 429,
      "prints": 28314,
      "concepts": 3039,
      "sealed_products": 668
    }
  ]
}

Catalog Endpoints

GET/gamesAUTH

Supported games

Lists the games you can query, with the slug to use as the game filter.

Response fields

Field	Type	Description
data[].id	string	Game id (UUID).
data[].slug	string	Game slug. Use it as the game filter on other endpoints.
data[].name	string	Game name.
data[].release_continuity_status	string	Whether the game is still releasing: continuing, ended, or unknown.
data[].latest_release_date, data[].latest_release_title, data[].next_release_date, data[].next_release_title	string \| null	Latest and next release dates and titles, or null.

Example Request

curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/games"

Response Example

{
  "data": [
    {
      "id": "6f1d2c3b-4a59-4e8d-9c7b-1a2b3c4d5e6f",
      "slug": "one-piece-card-game",
      "name": "One Piece Card Game",
      "release_continuity_status": "continuing",
      "latest_release_date": "2026-09-26",
      "latest_release_title": "Booster Pack",
      "next_release_date": null,
      "next_release_title": null
    }
  ]
}

GET/setsAUTH

Sets by game

Lists sets, sorted by game and then newest first. Filter by game or language, and page with limit and offset.

Parameters

Parameter	Type	Required	Description
game	string	Optional	Catalog slug such as pokemon, one-piece-card-game, or yugioh.
language	string	Optional	Language code stored on the set, such as en or ja.
limit	integer	Optional	Defaults to 50. Values below 1 are read as 1, values above 200 are read as 200, and a non-numeric value is read as 50.
offset	integer	Optional	Zero-based row offset. Defaults to 0.

Response fields

Field	Type	Description
data[].id	string	Set id (UUID).
data[].code, data[].name	string	Set code and name.
data[].release_date	string \| null	Release date (YYYY-MM-DD), or null.
data[].game_slug	string	Game slug. Use it as the game filter on other endpoints.
data[].release_status, data[].catalog_status	string	release_status is unknown, announced, preorder, released, delayed, or cancelled. catalog_status shows how complete the card list is, such as partial or complete.
data[].known_card_count, data[].expected_card_count	integer \| null	Cards in the catalog for this set, and the number expected (null when unknown).
data[].metadata	object	Extra set details, such as series and printed total.
pagination	object	limit, offset, total, and total_is_estimate (true when total is an estimate).

Example Request

curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/sets?game=pokemon"

Response Example

{
  "data": [
    {
      "id": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
      "code": "EX-09",
      "name": "EXTRA BOOSTER VERSUS MONSTERS",
      "release_date": null,
      "game_slug": "digimon-card-game",
      "release_status": "released",
      "catalog_status": "complete",
      "known_card_count": 74,
      "expected_card_count": 74,
      "metadata": { "languageCode": "en" }
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1,
    "total_is_estimate": false
  }
}

GET/sets/{setRef}AUTH

Set detail

Returns one set by code or id. Add game when the same code exists in more than one game.

Parameters

Parameter	Type	Required	Description
setRef	string	Required	Set code or set id, such as EX-09. An unknown set returns 404 set_not_found.
game	string	Optional	Catalog slug when the set code is shared across games.

Response fields

Field	Type	Description
data.id	string	Set id (UUID).
data.code, data.name	string	Set code and name.
data.release_date	string \| null	Release date (YYYY-MM-DD), or null.
data.game_slug	string	Game slug. Use it as the game filter on other endpoints.
data.release_status, data.catalog_status	string	release_status is unknown, announced, preorder, released, delayed, or cancelled. catalog_status shows how complete the card list is, such as partial or complete.
data.known_card_count, data.expected_card_count	integer \| null	Cards in the catalog for this set, and the number expected (null when unknown).
data.metadata	object	Extra set details, such as series and printed total.

Example Request

curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/sets/EX-09?game=digimon-card-game"

Response Example

{
  "data": {
    "id": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
    "code": "EX-09",
    "name": "EXTRA BOOSTER VERSUS MONSTERS",
    "release_date": null,
    "game_slug": "digimon-card-game",
    "release_status": "released",
    "catalog_status": "complete",
    "known_card_count": 74,
    "expected_card_count": 74,
    "metadata": { "languageCode": "en" }
  }
}

Cards Endpoints

GET/cardsAUTH

Search cards

Searches cards by game, set, language, or name. Results are sorted by name and paged with limit and offset.

Parameters

Parameter	Type	Required	Description
game	string	Optional	Game slug, such as pokemon.
setCode	string	Optional	Set code, such as EX-09.
language	string	Optional	Card language code, such as en or ja.
q	string	Optional	Part of the card name. Case-insensitive. name also works.
limit	integer	Optional	Defaults to 50. Values below 1 are read as 1, values above 200 are read as 200, and a non-numeric value is read as 50.
offset	integer	Optional	Zero-based row offset. Defaults to 0.

Response fields

Field	Type	Description
data[].id	string	Card id, 32-character hex.
data[].name, data[].card_number, data[].rarity	string	Card name, printed number, and rarity.
data[].language_code	string	Language code, such as en or ja.
data[].game_slug	string	Game the card belongs to.
data[].set_code, data[].set_name	string \| null	Set the card was released in.
data[].image_url	string \| null	Card image URL.
data[].attributes	object	Game-specific details, such as cost, type, or card text.
data[].updated_at	string	When the record was last updated (ISO 8601).
pagination	object	limit, offset, total, and total_is_estimate (true when total is an estimate).

Example Request

curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/cards?game=pokemon&limit=25&offset=0"

Response Example

{
  "data": [
    {
      "id": "97997e2be098df0ff51e0e945dda577a",
      "name": "Abbadomon",
      "card_number": "EX9-055 R",
      "rarity": "r",
      "language_code": "en",
      "game_slug": "digimon-card-game",
      "set_code": "EX-09",
      "set_name": "EXTRA BOOSTER VERSUS MONSTERS",
      "image_url": "https://images.tradingcardstudio.com/card-images/faa8f84b5d4e091fc3bf2257080f9c1600b9d10e13ab84f59113026a32845cdf.png",
      "attributes": { "cost": "11", "level": "Lv.6", "card_type": "Digimon" },
      "updated_at": "2026-10-12T00:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1,
    "total_is_estimate": false
  }
}

GET/cards/{cardId}AUTH

Card detail

Returns one card with its details, latest prices, and links to the same card in other languages and sets.

Price fields are empty on the Free plan; upgrade to Hobbyist or Builder for prices.

Price data is included on Hobbyist and Builder for select cards where available. Many cards have no price data.

Parameters

Parameter	Type	Required	Description
cardId	string	Required	Compact 32-character hex or dashed UUID. The response id is compact hex.
locale	string	Optional	Preferred locale for translated text, such as ja-JP.
language	string	Optional	Preferred language for translated text, such as ja.

Response fields

Field	Type	Description
data.id	string	Card id, 32-character hex.
data.name, data.card_number, data.rarity	string	Card name, printed number, and rarity.
data.language_code	string	Language code, such as en or ja.
data.game_slug, data.game_name	string	Game the card belongs to.
data.set_code, data.set_name	string \| null	Set the card was released in.
data.image_url	string \| null	Card image URL.
data.attributes	object	Game-specific details, such as cost, type, or card text.
data.game_id, data.set_id	string	Game id and set id.
data.created_at, data.updated_at	string	When the record was created and last updated (ISO 8601).
data.latest_prices	array	Current prices, in the same row format as Latest prices. Price data covers select cards where data is available, not every card.
data.association	object \| null	How this card links to its other prints: print_count, sibling_count, available_language_codes, and sibling_prints.
data.localizations	object \| null	Card text in other languages. resolved holds the best match for the requested locale or language.
prices_included	boolean	true when your plan includes prices.
upgrade_hint	string \| null	How to get prices when they are not included; otherwise null.

Example Request

curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/cards/97997e2be098df0ff51e0e945dda577a"

Response Example

{
  "data": {
    "id": "97997e2be098df0ff51e0e945dda577a",
    "game_id": "6f1d2c3b-4a59-4e8d-9c7b-1a2b3c4d5e6f",
    "set_id": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
    "name": "Abbadomon",
    "card_number": "EX9-055 R",
    "rarity": "r",
    "language_code": "en",
    "game_slug": "digimon-card-game",
    "game_name": "Digimon Card Game",
    "set_code": "EX-09",
    "set_name": "EXTRA BOOSTER VERSUS MONSTERS",
    "image_url": "https://images.tradingcardstudio.com/card-images/faa8f84b5d4e091fc3bf2257080f9c1600b9d10e13ab84f59113026a32845cdf.png",
    "attributes": { "cost": "11", "level": "Lv.6", "card_type": "Digimon" },
    "created_at": "2026-01-15T00:00:00.000Z",
    "updated_at": "2026-10-12T00:00:00.000Z",
    "latest_prices": [
      {
        "card_id": "97997e2be098df0ff51e0e945dda577a",
        "market": "US",
        "currency_code": "USD",
        "condition": null,
        "price_amount": "4.25",
        "price_type": "market",
        "source_variant": null,
        "mapping_scope": "exact_print",
        "captured_at": "2026-10-12T00:00:00.000Z",
        "updated_at": "2026-10-12T00:00:00.000Z"
    }
    ],
    "association": {
      "mapped": true,
      "card_concept_id": "ad759f77-32eb-501b-8aa5-5b5c7e15e2d0",
      "print_count": 2,
      "sibling_count": 1,
      "available_language_codes": ["en", "ja"],
      "sibling_prints": [
        { "card_print_id": "3c5e7a91-2b4d-4f6a-8c1e-9d0b2a4c6e81", "name": "アバドモン", "language_code": "ja", "card_number": "EX9-055" }
      ]
    },
    "localizations": {
      "requested_locale": "en-US",
      "requested_language": "en",
      "available": [
        { "source_kind": "official_print", "language_code": "en", "locale_code": "en-US", "fields": { "name": "Abbadomon" } },
        { "source_kind": "official_print", "language_code": "ja", "locale_code": "ja-JP", "fields": { "name": "アバドモン" } }
      ],
      "resolved": { "source_kind": "official_print", "language_code": "en", "locale_code": "en-US", "fields": { "name": "Abbadomon" } }
    }
  },
  "prices_included": true,
  "upgrade_hint": null
}

GET/cards/{cardId}/siblingsAUTH

Sibling prints

Returns the other prints of the same card, such as other languages and reprints in other sets.

Parameters

Parameter	Type	Required	Description
cardId	string	Required	Card id. 32-character hex or dashed UUID.
locale	string	Optional	Preferred locale for translated text, such as ja-JP.
language	string	Optional	Preferred language for translated text, such as ja.

Response fields

Field	Type	Description
data	array	Other prints of the same card, in the same format as prints on Card concept.
association	object	How this card links to its other prints: card_concept_id, print_count, sibling_count, and available_language_codes.
localizations	object	Card text in other languages. resolved holds the best match for the requested locale or language.

Example Request

curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/cards/97997e2be098df0ff51e0e945dda577a/siblings"

Response Example

{
  "data": [
    {
      "card_id": "97997e2be098df0ff51e0e945dda577a",
      "card_print_id": "3c5e7a91-2b4d-4f6a-8c1e-9d0b2a4c6e81",
      "card_concept_id": "ad759f77-32eb-501b-8aa5-5b5c7e15e2d0",
      "is_source": false,
      "name": "アバドモン",
      "card_number": "EX9-055",
      "language_code": "ja",
      "locale_code": "ja-JP",
      "rarity": "r",
      "variant_key": "base",
      "image_url": "https://images.tradingcardstudio.com/card-images/faa8f84b5d4e091fc3bf2257080f9c1600b9d10e13ab84f59113026a32845cdf.png",
      "set": {
        "id": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
        "code": "EX-09",
        "name": "エクストラブースター VERSUS MONSTERS",
        "release_date": null
      }
    }
  ],
  "association": {
    "mapped": true,
    "card_concept_id": "ad759f77-32eb-501b-8aa5-5b5c7e15e2d0",
    "source_card_print_id": "3c5e7a91-2b4d-4f6a-8c1e-9d0b2a4c6e81",
    "print_count": 2,
    "sibling_count": 1,
    "available_language_codes": ["en", "ja"],
    "available_locale_codes": ["en-US", "ja-JP"]
  },
  "localizations": {
    "requested_locale": "ja-JP",
    "requested_language": null,
    "available": [
      { "source_kind": "official_print", "language_code": "ja", "locale_code": "ja-JP", "fields": { "name": "アバドモン" } }
    ],
    "resolved": { "source_kind": "official_print", "language_code": "ja", "locale_code": "ja-JP", "fields": { "name": "アバドモン" } }
  }
}

GET/cards/{cardId}/localizationsAUTH

Card localizations

Returns the card's name and text in other languages, including the best match for the language you ask for.

Parameters

Parameter	Type	Required	Description
cardId	string	Required	Card id. 32-character hex or dashed UUID.
locale	string	Optional	Preferred locale for translated text, such as ja-JP.
language	string	Optional	Preferred language for translated text, such as ja.

Response fields

Field	Type	Description
data.requested_locale, data.requested_language	string \| null	Locale and language used to choose resolved.
data.available	array	Every available translation, each with language_code, locale_code, and fields.
data.resolved	object \| null	Best match for the requested locale or language, or null.
association	object	How this card links to its other prints: card_concept_id, print_count, sibling_count, and available_language_codes.

Example Request

curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/cards/97997e2be098df0ff51e0e945dda577a/localizations"

Response Example

{
  "data": {
    "requested_locale": "ja-JP",
    "requested_language": null,
    "available": [
      { "source_kind": "official_print", "language_code": "ja", "locale_code": "ja-JP", "fields": { "name": "アバドモン" } }
    ],
    "resolved": { "source_kind": "official_print", "language_code": "ja", "locale_code": "ja-JP", "fields": { "name": "アバドモン" } }
  },
  "association": {
    "mapped": true,
    "card_concept_id": "ad759f77-32eb-501b-8aa5-5b5c7e15e2d0",
    "source_card_print_id": "3c5e7a91-2b4d-4f6a-8c1e-9d0b2a4c6e81",
    "print_count": 2,
    "sibling_count": 1,
    "available_language_codes": ["en", "ja"],
    "available_locale_codes": ["en-US", "ja-JP"]
  }
}

GET/cards/{cardId}/pricesAUTH

Latest prices

Returns the latest prices for one card. You can pass a card id or a print id.

Price fields are empty on the Free plan; upgrade to Hobbyist or Builder for prices.

Price data is included on Hobbyist and Builder for select cards where available. Many cards have no price data.

Parameters

Parameter	Type	Required	Description
cardId	string	Required	Card id or print id. 32-character hex or dashed UUID.
market	string	Optional	US, EU, JAPAN, or JP. JP is the same market as JAPAN. Leave it out for every market. An unknown value returns 400 invalid_market.
condition	string	Optional	Leave it out for near mint (NM) or raw prices. Also accepts NM, S, A, A-, B, C, D, PL, a grade such as PSA10 or BGS9.5, or all. An unknown value returns 400 invalid_condition.

Response fields

Field	Type	Description
data[].card_id	string	Card id, 32-character hex.
data[].market	string	US, EU, or JAPAN.
data[].currency_code	string	Currency, such as USD, EUR, or JPY.
data[].price_amount	string	Price as a decimal string. Price data covers select cards where data is available, not every card.
data[].price_type	string	market, low, mid, or high.
data[].condition	string \| null	null for near mint (NM) or raw. Otherwise the condition, such as A or PSA:10.
data[].grader, data[].grade	string	Only on graded rows, for example PSA and 10.
data[].source_variant	string \| null	Finish, such as holofoil, or null.
data[].mapping_scope	string	What the price covers, such as exact_print (this print), shared_across_variants (every finish), listing_aggregate (current listings), or sale_aggregate (recent sales).
data[].price_min, data[].price_max, data[].price_median, data[].sample_count, data[].region	mixed	Only on listing_aggregate and sale_aggregate rows: price range, median, number of prices, and region (jp or us).
data[].last_sale_price, data[].last_sale_on, data[].window_days	mixed	Only on sale_aggregate rows: the most recent sale price and date, and the number of days covered.
data[].captured_at, data[].updated_at	string	When the price was recorded and last updated.
prices_included	boolean	true when your plan includes prices.
upgrade_hint	string \| null	How to get prices when they are not included; otherwise null.

Example Request

curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/cards/97997e2be098df0ff51e0e945dda577a/prices"

Response Example

{
  "data": [
    {
      "card_id": "97997e2be098df0ff51e0e945dda577a",
      "market": "US",
      "currency_code": "USD",
      "condition": null,
      "price_amount": "4.25",
      "price_type": "market",
      "source_variant": null,
      "mapping_scope": "exact_print",
      "captured_at": "2026-10-12T00:00:00.000Z",
      "updated_at": "2026-10-12T00:00:00.000Z"
    }
  ],
  "prices_included": true,
  "upgrade_hint": null
}

GET/concepts/{conceptId}AUTH

Card concept

Returns one unique card with every print of it and its text in other languages.

Parameters

Parameter	Type	Required	Description
conceptId	string	Required	Concept id, as returned in concept.id or association.card_concept_id.
locale	string	Optional	Preferred locale for translated text, such as ja-JP.
language	string	Optional	Preferred language for translated text, such as ja.

Response fields

Field	Type	Description
data.id	string	Concept id.
data.name, data.concept_type	string	Card name and concept type.
data.game_slug, data.game_name	string	Game the card belongs to.
data.prints	array	Every print of this card, with card_id, card_print_id, number, language, rarity, image, and set.
data.localizations	object	Card text in other languages. resolved holds the best match for the requested locale or language.
association	object	How this card links to its other prints: card_concept_id, print_count, sibling_count, and available_language_codes.

Example Request

curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/concepts/ad759f7732eb501b8aa55b5c7e15e2d0"

Response Example

{
  "data": {
    "id": "ad759f77-32eb-501b-8aa5-5b5c7e15e2d0",
    "game_slug": "digimon-card-game",
    "game_name": "Digimon Card Game",
    "name": "Abbadomon",
    "concept_type": "card",
    "prints": [
      {
        "card_id": "97997e2be098df0ff51e0e945dda577a",
        "card_print_id": "3c5e7a91-2b4d-4f6a-8c1e-9d0b2a4c6e81",
        "card_concept_id": "ad759f77-32eb-501b-8aa5-5b5c7e15e2d0",
        "is_source": false,
        "name": "アバドモン",
        "card_number": "EX9-055",
        "language_code": "ja",
        "locale_code": "ja-JP",
        "rarity": "r",
        "variant_key": "base",
        "image_url": "https://images.tradingcardstudio.com/card-images/faa8f84b5d4e091fc3bf2257080f9c1600b9d10e13ab84f59113026a32845cdf.png",
        "set": {
          "id": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
          "code": "EX-09",
          "name": "エクストラブースター VERSUS MONSTERS",
          "release_date": null
        }
      }
    ],
    "localizations": {
      "available": [
        { "source_kind": "official_print", "language_code": "ja", "locale_code": "ja-JP", "fields": { "name": "アバドモン" } }
      ],
      "resolved": null
    }
  },
  "association": {
    "mapped": true,
    "card_concept_id": "ad759f77-32eb-501b-8aa5-5b5c7e15e2d0",
    "source_card_print_id": "3c5e7a91-2b4d-4f6a-8c1e-9d0b2a4c6e81",
    "print_count": 2,
    "sibling_count": 1,
    "available_language_codes": ["en", "ja"],
    "available_locale_codes": ["en-US", "ja-JP"]
  }
}

GET/prints/{cardPrintId}AUTH

Print detail

Returns one physical print with its set, number, rarity, images, and game-specific details. Add include=current_prices to get its current prices.

Price fields are empty on the Free plan; upgrade to Hobbyist or Builder for prices.

Price data is included on Hobbyist and Builder for select cards where available. Many cards have no price data.

Parameters

Parameter	Type	Required	Description
cardPrintId	string	Required	Print id. 32-character hex or dashed UUID.
include	string	Optional	Pass current_prices to add current prices. Any other value returns 400 invalid_include.
condition	string	Optional	Filters the prices from include=current_prices. Takes the same values as condition on Latest prices.

Response fields

Field	Type	Description
data.id	string	Print id (UUID).
data.concept_id	string	Unique card this print belongs to. Use it with Card concept.
data.game_id, data.set_id	string	Game id and set id.
data.language_code, data.locale_code	string	Language and locale, such as ja and ja-JP.
data.game	object	Game slug and name.
data.set	object \| null	Set code, name, series, and release date, or null.
data.card_metadata	object	Printed number, title, rarity, variant, and images. Pokémon prints also include a pokemon block with HP, types, attacks, and more.
data.pricing_metadata	object	as_of (latest price date), products (prices by scope and finish, filled when include=current_prices is sent), and history_url (path to Print prices). Price data covers select cards where data is available, not every card.
data.created_at, data.updated_at	string	When the record was created and last updated (ISO 8601).
prices_included	boolean	true when your plan includes prices.
upgrade_hint	string \| null	How to get prices when they are not included; otherwise null.

Example Request

curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/prints/{cardPrintId}?include=current_prices"

Response Example

{
  "data": {
    "id": "3c5e7a91-2b4d-4f6a-8c1e-9d0b2a4c6e81",
    "game_id": "6f1d2c3b-4a59-4e8d-9c7b-1a2b3c4d5e6f",
    "set_id": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
    "concept_id": "ad759f77-32eb-501b-8aa5-5b5c7e15e2d0",
    "language_code": "en",
    "locale_code": "en-US",
    "game": { "slug": "digimon-card-game", "name": "Digimon Card Game" },
    "set": { "code": "EX-09", "name": "EXTRA BOOSTER VERSUS MONSTERS", "series": null, "release_date": null },
    "card_metadata": {
      "number": { "printed": "EX9-055", "set_total": null, "display": "EX9-055" },
      "title": "Abbadomon",
      "rarity": { "key": "r", "name": "r", "short_code": null },
      "variant": "base",
      "images": { "primary": "https://images.tradingcardstudio.com/card-images/faa8f84b5d4e091fc3bf2257080f9c1600b9d10e13ab84f59113026a32845cdf.png", "small": null },
      "pokemon": null
    },
    "pricing_metadata": {
      "as_of": "2026-10-12",
      "products": [
        {
          "mapping_status": "verified",
          "mapping_scope": "exact_print",
          "variants": [
            {
              "variant": "default",
              "condition": null,
              "market": "US",
              "currency": "USD",
              "prices": { "market": "4.25" },
              "observed_on": "2026-10-12",
              "captured_at": "2026-10-12T00:00:00.000Z",
              "updated_at": "2026-10-12T00:00:00.000Z"
            }
          ]
        }
      ],
      "history_url": "/v1/prints/3c5e7a91-2b4d-4f6a-8c1e-9d0b2a4c6e81/prices"
    },
    "created_at": "2026-01-15T00:00:00.000Z",
    "updated_at": "2026-10-12T00:00:00.000Z"
  },
  "prices_included": true,
  "upgrade_hint": null
}

GET/prints/{cardPrintId}/pricesAUTH

Print prices

Returns the latest prices for one print.

Price fields are empty on the Free plan; upgrade to Hobbyist or Builder for prices.

Price data is included on Hobbyist and Builder for select cards where available. Many cards have no price data.

Parameters

Parameter	Type	Required	Description
cardPrintId	string	Required	Print id. 32-character hex or dashed UUID.
market	string	Optional	US, EU, JAPAN, or JP. JP is the same market as JAPAN. Leave it out for every market. An unknown value returns 400 invalid_market.
condition	string	Optional	Leave it out for near mint (NM) or raw prices. Also accepts NM, S, A, A-, B, C, D, PL, a grade such as PSA10 or BGS9.5, or all. An unknown value returns 400 invalid_condition.
price_type	string	Optional	Only return one price type, such as market, low, mid, or high.

Response fields

Field	Type	Description
data[].card_print_id	string	Print id (UUID).
data[].market	string	US, EU, or JAPAN.
data[].currency_code	string	Currency, such as USD, EUR, or JPY.
data[].price_amount	string	Price as a decimal string. Price data covers select cards where data is available, not every card.
data[].price_type	string	market, low, mid, or high.
data[].condition	string \| null	null for near mint (NM) or raw. Otherwise the condition, such as A or PSA:10.
data[].grader, data[].grade	string	Only on graded rows, for example PSA and 10.
data[].source_variant	string \| null	Finish, such as holofoil, or null.
data[].mapping_scope	string	What the price covers, such as exact_print (this print), shared_across_variants (every finish), listing_aggregate (current listings), or sale_aggregate (recent sales).
data[].price_min, data[].price_max, data[].price_median, data[].sample_count, data[].region	mixed	Only on listing_aggregate and sale_aggregate rows: price range, median, number of prices, and region (jp or us).
data[].last_sale_price, data[].last_sale_on, data[].window_days	mixed	Only on sale_aggregate rows: the most recent sale price and date, and the number of days covered.
data[].observed_on	string	Date the price applies to.
data[].captured_at, data[].updated_at	string	When the price was recorded and last updated.
prices_included	boolean	true when your plan includes prices.
upgrade_hint	string \| null	How to get prices when they are not included; otherwise null.

Example Request

curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/prints/{cardPrintId}/prices"

Response Example

{
  "data": [
    {
      "card_print_id": "3c5e7a91-2b4d-4f6a-8c1e-9d0b2a4c6e81",
      "market": "US",
      "currency_code": "USD",
      "condition": null,
      "price_amount": "4.25",
      "price_type": "market",
      "source_variant": null,
      "mapping_scope": "exact_print",
      "observed_on": "2026-10-12",
      "captured_at": "2026-10-12T00:00:00.000Z",
      "updated_at": "2026-10-12T00:00:00.000Z"
    }
  ],
  "prices_included": true,
  "upgrade_hint": null
}

Code Examples

Search cards

curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/cards?game=pokemon&limit=25&offset=0"

Read Latest Prices

curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/cards/97997e2be098df0ff51e0e945dda577a/prices"

Error Handling

400

Invalid Request

Malformed JSON or a query the route rejects. On price routes, an unknown condition returns error invalid_condition, and an unknown market returns error invalid_market.

401

Unauthenticated

A catalog call without a valid API key returns 401 with error unauthorized. Create a key in the dashboard and send it as X-API-Key.

403

Forbidden

Price routes do not return 403 when the plan does not include price data. Free keys get 200 with empty price fields and prices_included set to false.

404

Not Found

An unknown set returns error set_not_found.

429

Too Many Requests

The account has used its monthly catalog allowance. The body uses error rate_limited and message "This account has used its monthly catalog request allowance." Retry-After is the number of seconds until 00:00 UTC on the 1st of the next month. Wait that long before you call again. A 429 still counts toward the allowance.

Best Practices

Filter narrowly

Send game, setCode, and q before increasing page size.

Cache images

Use the image_url on each card. Samples on this page use https://images.tradingcardstudio.com.