API Documentation
Learn how to integrate the JustTCG API into your applications.
Overview
The JustTCG API provides real-time pricing data for trading card games including Magic: The Gathering, Pokémon, Yu-Gi-Oh!, Disney Lorcana, One Piece TCG, Digimon, and Union Arena. Our API is designed to be simple, fast, and reliable.
Notice: The card-search and variants endpoints are deprecated and will be phased out over time. Please migrate to the cards endpoint, which now supports both searching and direct lookups. This change is part of our effort to provide a more intuitive and seamless API experience. For most use-cases, you only need to use the games, sets, and cards endpoints.
Base URL
https://api.justtcg.com/v1
Authentication
All API requests require authentication using an API key. You can obtain an API key by signing up for an account and subscribing to a plan.
API Key Authentication
Include your API key in the request headers:
x-api-key:tcg_your_api_key_here
API Reference
API Architecture Update: Our API is now focused on three main endpoints for a more intuitive and seamless experience:
- Games and Sets: For discovering available games and sets.
- Cards: For searching and direct lookups. If you pass an
id
, you get a direct lookup. If you do not pass anid
, the endpoint serves as a flexible search.
The updated architecture is simple: use games and sets to discover, and cards for both searching and direct lookups. Direct lookups are triggered by passing an id
. If no id
is passed, the cards endpoint acts as a search endpoint.
Collection Resources
These endpoints provide information about the available trading card games and sets in our database. Start with these endpoints to understand what's available before diving into the card-specific endpoints.
Get All Games
Returns a list of all supported trading card games.
https://api.justtcg.com/v1/games
curl -X GET "https://api.justtcg.com/v1/games" \
-H "X-API-Key: your_api_key_here"
Get Sets
Returns a paginated list of sets for a specific game.
https://api.justtcg.com/v1/sets
Query Parameters
curl -X GET "https://api.justtcg.com/v1/sets?game=mtg" \
-H "X-API-Key: your_api_key_here"
Direct Lookups
These high-performance endpoints provide rapid access to card data when you already have identifier values. For the best performance when retrieving specific cards, use these endpoints with TCGplayer IDs obtained from the browsing endpoints.
Card by ID
Retrieve a card and all its variant prices by TCGplayer ID. You can optionally filter the returned variants by condition and printing type.
https://api.justtcg.com/v1/cards
Query Parameters
curl -X GET "https://api.justtcg.com/v1/cards?tcgplayerId=25788&condition=Near%20Mint&printing=1st%20Edition" \
-H "X-API-Key: your_api_key_here"
Batch Card Lookup
Retrieve multiple cards and their variants in a single request. For each card, you can optionally filter variants by specifying condition and printing parameters.
https://api.justtcg.com/v1/cards
Request Body
Send an array of objects, each containing the following properties:
curl -X POST "https://api.justtcg.com/v1/cards" \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '[
{
"tcgplayerId": "25788",
"condition": "Near Mint",
"printing": "1st Edition"
},
{
"tcgplayerId": "514475",
"condition": "Near Mint",
"printing": "Foil"
}
]'
Get Single Variant (Deprecated)
[DEPRECATED] The /variants endpoint is deprecated and will be phased out over time. Please use the /cards endpoint for all direct lookups and variant retrieval. The /cards endpoint now supports all previous functionality and more.
https://api.justtcg.com/v1/variants
Query Parameters
curl -X GET "https://api.justtcg.com/v1/variants?variantId=yugioh-force-of-the-breaker-lich-lord,-king-of-the-underworld_near-mint_1st-edition" \
-H "X-API-Key: your_api_key_here"
Batch Variant Lookup (Deprecated)
[DEPRECATED] The /variants endpoint is deprecated and will be phased out over time. Please use the /cards endpoint for all direct lookups and variant retrieval. The /cards endpoint now supports all previous functionality and more.
https://api.justtcg.com/v1/variants
Request Body
Send an array of objects, each containing the following property:
curl -X POST "https://api.justtcg.com/v1/variants" \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '[
{
"variantId": "yugioh-egyptian-god-deck-slifer-the-sky-dragon-lair-of-darkness_near-mint_foil"
},
{
"variantId": "magic-murders-at-karlov-manor-case-of-the-stashed-skeleton_played_normal"
}
]'
Browsing & Search
This endpoint lets you search and browse cards in our database with flexible filtering options. All results include complete card data with variant pricing. Use this endpoint when you need to discover cards or present users with search and browse interfaces.
Search Cards (Deprecated)
[DEPRECATED] This endpoint is deprecated. Please use the /cards endpoint for all search and lookup use-cases. The /cards endpoint now supports all previous functionality and more.
https://api.justtcg.com/v1/cards-search
Query Parameters
curl -X GET "https://api.justtcg.com/v1/cards-search?q=charizard&limit=2" \
-H "X-API-Key: your_api_key_here"
Card Objects
The Card object contains detailed information about a trading card, including its variants with pricing information.
Card Structure
Every card in our database has a standard structure that includes basic card information and an array of variants.
Card Properties
Variant Structure
Each variant represents a specific combination of condition and printing for a card, with its associated price.
Variant Properties
Example Card Object
{
"id": "pokemon-battle-academy-fire-energy-22-charizard-stamped",
"name": "Fire Energy (#22 Charizard Stamped)",
"game": "Pokemon",
"set": "Battle Academy",
"number": "N/A",
"tcgplayerId": "219042",
"rarity": "Promo",
"details": null,
"variants": [
{
"id": "pokemon-battle-academy-fire-energy-22-charizard-stamped_near-mint",
"printing": "Normal",
"condition": "Near Mint",
"price": 4.99,
"lastUpdated": 1743100261
},
{
"id": "pokemon-battle-academy-fire-energy-22-charizard-stamped_lightly-played",
"printing": "Normal",
"condition": "Lightly Played",
"price": 3.50,
"lastUpdated": 1743101175
}
]
}
Filtering Variants
When retrieving cards, you can filter the variants by adding optional printing
and condition
parameters to your requests. This helps reduce response size and narrow down results to specific variants you're interested in.
Variant IDs
Each variant has a unique id
which serves as the primary key in our database. The variant ID is structured as card-id_condition_printing
and can be used for direct, high-performance lookups using the /variants
endpoint. If you already have the variant ID, using it directly is the fastest way to retrieve pricing information.
Consistency Note
All endpoints that return card data use this same structure. Every card will have at least one variant in its variants array.
Response Format
All API responses follow a consistent format with a data
field containing the requested information and a meta
field with API usage statistics.
Response Structure
Error Handling
The JustTCG API uses standard HTTP status codes and returns consistent error response formats to help you quickly identify and resolve issues.
HTTP Status Codes
Error Response Format
All error responses follow a consistent format with an error
object containing details about the error.
{
"error": {
"code": "invalid_card_id",
"message": "The provided TCGplayer ID does not exist in our database.",
"status": 404,
"details": {
"tcgplayerId": "999999999"
}
},
"meta": {
"api_calls_used": 1,
"api_calls_remaining": 99991
}
}
Common Error Codes
Code Examples
Practical examples showing how to integrate the JustTCG API in real-world scenarios.
// Set your API key
const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.justtcg.com/v1';
// Fetch all cards from a set (automatically handles pagination)
async function updatePricesForSet(gameId, setId) {
console.log(`Updating prices for ${gameId} set: ${setId}...`);
let allCards = [];
let hasMoreResults = true;
let offset = 0;
const LIMIT = 50;
// Keep fetching until we've got all cards
while (hasMoreResults) {
try {
// Create URL with query parameters
const url = new URL(`${BASE_URL}/cards-search`);
url.searchParams.append('game', gameId);
url.searchParams.append('set', setId);
url.searchParams.append('limit', LIMIT);
url.searchParams.append('offset', offset);
// Make the API request
const response = await fetch(url, {
headers: { 'X-API-Key': API_KEY }
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message || 'API request failed');
}
const cards = result.data;
console.log(`Fetched ${cards.length} cards (offset: ${offset})`);
// Add cards to our collection
allCards = [...allCards, ...cards];
// Check if we've reached the end
hasMoreResults = cards.length === LIMIT;
offset += LIMIT;
// For demo purposes, just log first card's variants
if (offset === LIMIT && cards.length > 0) {
console.log('Sample card variation prices:');
cards[0].variants.forEach(v => {
console.log(`- ${v.condition} / ${v.printing}: $${v.price}`);
});
}
} catch (error) {
console.error('Error fetching cards:', error);
break;
}
}
console.log(`✅ Updated prices for ${allCards.length} cards`);
return allCards;
}
// Example usage
// updatePricesForSet('mtg', 'mh2');
// Set your API key
const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.justtcg.com/v1';
// Display a product page with multiple cards
async function fetchProductPageCards(cardIds) {
console.log('Fetching data for product display...');
try {
// Batch card lookup for efficiency
const response = await fetch(`${BASE_URL}/cards`, {
method: 'POST',
headers: {
'X-API-Key': API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify(cardIds.map(id => ({ tcgplayerId: id })))
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message || 'Failed to fetch cards');
}
// Display the cards (in a real app, you'd render these to the DOM)
console.log(`Displaying ${result.data.length} cards:`);
result.data.forEach(card => {
console.log(`${card.name} - ${card.set}`);
// Get the lowest price for display
const lowestPrice = Math.min(
...card.variants.map(v => v.price)
);
console.log(` Starting from: $${lowestPrice.toFixed(2)}`);
});
return result.data;
} catch (error) {
console.error('Error fetching product data:', error);
return [];
}
}
// Example usage
// fetchProductPageCards(['123456', '789012', '345678']);
// Set your API key
const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.justtcg.com/v1';
// Calculate shopping cart total with specific variants
async function calculateShoppingCart(cartItems) {
console.log('Calculating shopping cart total...');
try {
// Get up-to-date prices for all variants in cart
const response = await fetch(`${BASE_URL}/variants`, {
method: 'POST',
headers: {
'X-API-Key': API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify(cartItems)
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message || 'Failed to fetch prices');
}
// Calculate total (in a real app, you'd update the cart UI)
let total = 0;
result.data.forEach(item => {
const subtotal = item.price;
total += subtotal;
console.log(
`${item.card.name} (${item.condition}, ${item.printing}): $${item.price.toFixed(2)}`
);
});
console.log(`Cart Total: $${total.toFixed(2)}`);
return total;
} catch (error) {
console.error('Error calculating cart:', error);
return 0;
}
}
// Example usage
// calculateShoppingCart([
// { tcgplayerId: '123456', condition: 'Near Mint', printing: 'Foil' },
// { tcgplayerId: '789012', condition: 'Lightly Played', printing: 'Normal' }
// ]);
Rate Limits & Usage
The JustTCG API has rate limits based on your subscription plan. You can monitor your API usage in your dashboard.
Rate Limits by Plan
429 Too Many Requests
response. If you exceed your monthly limit, you'll need to upgrade your plan to continue using the API.Reset Times: Daily rate limits reset at midnight (00:00) UTC. Monthly usage limits reset on the first day of each month at midnight (00:00) UTC.
Support
If you have any questions or need help with the API, please contact our support team.