A RESTful API for Magic: The Gathering card data with the same structure and conventions as the Pokemon TCG API โ powered by Scryfall-format data with embedded TCGPlayer and CardMarket pricing.
http://proxysuper.com/mtg
Local Testing: http://localhost:5000/mtg
tcgplayer_prices array: Normal / Foil entries, plus a cardmarket object)/mtg/ routes, no interferenceCard responses are the native Scryfall format โ fields like mana_cost, colors, type_line, and legalities are identical to Scryfall data. Pricing comes from TCGPlayer (via TCGCSV) and CardMarket: each card carries a tcgplayer_prices array, a cardmarket object, and local_image_url when local art exists.
No separate pricing call is needed: every card carries its own tcgplayer_prices array (one entry per condition: Normal, Foil) and cardmarket.prices (avg1/avg7/avg30, lowPrice, trendPrice, foil prices), so pricing is always in sync with the card data.
This API is currently open and does not require authentication. All MTG endpoints are publicly accessible โ the login system only protects the Pokemon documentation pages (/api/docs), not the MTG API itself.
All MTG endpoints live under the /mtg/ prefix:
/mtg/{endpoint}
/mtg/sets - Set metadata (from the project-root mtg_sets.json)/mtg/cards - Card data (from mtg_en/<set_code>.json)/mtg/images - Card images (from images/en/<set_code>/)Every card has a stable string ID of the form <set_code>-<collector_number> (e.g. 10e-218). Use it with /mtg/cards/id/<card_id> for fast lookups.
List endpoints support optional pagination using the following parameters:
page - Page number (default: 1)pageSize - Number of items per page (optional, max: 250). If not provided, all items are returned./mtg/cards without pageSize returns the entire corpus (~117,000 cards, hundreds of MB uncompressed). Always use pageSize when querying this endpoint.
Set-level endpoints (/mtg/cards/10e) are comfortable without pagination since single sets are small (typically 20-500 cards).
[
{ "id": "khm-1", ... },
{ "id": "khm-2", ... }
]
MTG endpoints return plain JSON arrays (Scryfall-compatible), not pagination envelopes.
The /mtg/cards endpoint supports filtering and search capabilities:
q - General search (name, id, type_line)colors - Comma-separated color letters (OR logic)cmc - Exact value (4) or inclusive range (2-5)orderBy - Sort fieldorder - Sort direction (asc, desc)set loads only that set's file from disk and skips building the full in-memory corpus โ it is the fastest filter available.
colors=W,R) use OR logicGet all MTG sets (1,066 sets) from the project-root mtg_sets.json, sorted by release date (newest first by default)
| Parameter | Type | Description | Example |
|---|---|---|---|
| page | integer | Page number (starts from 1) | 1 |
| pageSize | integer | Sets per page (optional, max 250) | 50 |
| set_type | string | Filter by set type (exact match) | expansion, core, commander, token, promo, masters |
| q | string | Search query - searches set code and name (case-insensitive) | khm |
| orderBy | string | Sort field (code, name, released_at, card_count). Default: released_at | code |
| order | string | Sort direction (asc for ascending, desc for descending). Default: desc | asc |
Each set object contains (all fields from the project-root mtg_sets.json, plus two convenience URLs):
| Field | Type | Description |
|---|---|---|
| code | string | Set code (lowercase, e.g. "khm") โ used in all other endpoints |
| name | string | Full set name |
| released_at | string | Release date (ISO 8601) |
| set_type | string | Set type (expansion, core, commander, ...) |
| card_count | integer | Number of cards printed in the set |
| tcgplayer_id | integer | TCGPlayer group ID for the set (may be absent) |
| icon_svg | string | Set symbol icon URL (Scryfall SVG) |
| block_code / block | string | Block information (may be absent) |
| digital | boolean | True for digital-only sets |
| json_url | string | Added by API - URL to fetch this set's cards |
| image_base_url | string | Added by API - Base URL for this set's images |
GET /mtg/sets?pageSize=2&orderBy=code&order=asc
[
{
"code": "10e",
"name": "Tenth Edition",
"set_name": "tenth-edition",
"series": "Core Set",
"released_at": "2007-07-13",
"set_type": "core",
"card_count": 510,
"digital": false,
"languages": {
"german": 375,
"english": 508,
"spanish": 374
},
"icon_svg": "https://svgs.scryfall.io/sets/10e.svg?...",
"tcgplayer_id": 1,
"json_url": "/mtg/cards/10e",
"image_base_url": "/mtg/images/10e"
},
{
"code": "2ed",
"name": "Unlimited Edition",
"released_at": "1993-12-01",
"set_type": "core",
"card_count": 302,
"...": "..."
}
]
Get metadata for a single MTG set by code โ returns 404 if the code is unknown
GET /mtg/sets/10e
{
"code": "10e",
"name": "Tenth Edition",
"set_name": "tenth-edition",
"series": "Core Set",
"released_at": "2007-07-13",
"set_type": "core",
"card_count": 510,
"digital": false,
"languages": {
"german": 375,
"english": 508,
"spanish": 374
},
"icon_svg": "https://svgs.scryfall.io/sets/10e.svg?...",
"tcgplayer_id": 1,
"json_url": "/mtg/cards/10e",
"image_base_url": "/mtg/images/10e"
}
{"error": "Set 'xyz' not found"}Search across the entire MTG corpus (~117,000 cards) with filtering and pagination. Always pass pageSize!
| Parameter | Type | Description | Example |
|---|---|---|---|
| page | integer | Page number (starts from 1) | 1 |
| pageSize | integer | Items per page (optional, max 250). If omitted, ALL matching cards are returned โ hundreds of MB! | 50 |
| q | string | Search query - searches in card name, id, and type_line (case-insensitive) | manabarbs |
| name | string | Filter by card name (case-insensitive, partial match) | lightning |
| colors | string | Filter by colors (comma-separated color letters, OR logic). W=white U=blue B=black R=red G=green | W,R |
| type | string | Filter by type_line (case-insensitive, partial match) | creature |
| cmc | string | Filter by converted mana cost - exact value or inclusive range | 4 or 2-5 |
| rarity | string | Filter by rarity (case-insensitive, partial match): common, uncommon, rare, mythic, special, bonus | mythic |
| set | string | Filter by set code (exact match). Fast โ loads only that set file | khm |
| artist | string | Filter by artist name (case-insensitive, partial match) | Jeff Miracola |
| orderBy | string | Sort field (id, name, cmc, rarity, released_at, set, collector) | name |
| order | string | Sort direction (asc for ascending, desc for descending) | asc |
cmc=4 - Returns cards with exactly 4 converted mana costcmc=2-5 - Returns cards with CMC between 2 and 5 (inclusive)GET /mtg/cards?name=manabarbs&page=1&pageSize=10
GET /mtg/cards?colors=W,R&cmc=3-5&rarity=rare&pageSize=10
GET /mtg/cards?q=goblin&colors=R&orderBy=name&order=desc&page=1&pageSize=10
GET /mtg/cards?set=khm&rarity=mythic&pageSize=3
[
{
"id": "10e-218",
"mtgo_id": 27158,
"tcgplayer_id": 15206,
"cardmarket_id": 16382,
"name": "Manabarbs",
"layout": "normal",
"mana_cost": "{3}{R}",
"cmc": 4.0,
"type_line": "Enchantment",
"oracle_text": "Whenever a player taps a land for mana, this enchantment deals 1 damage to that player.",
"colors": ["R"],
"color_identity": ["R"],
"keywords": [],
"legalities": {
"standard": "not_legal",
"pioneer": "not_legal",
"modern": "legal",
"legacy": "legal",
"vintage": "legal",
"commander": "legal"
},
"finishes": ["nonfoil", "foil"],
"set": "10e",
"set_name": "Tenth Edition",
"collector_number": "218",
"rarity": "rare",
"artist": "Jeff Miracola",
"image_uris": "https://proxysuper.com/images/mtg/en/10e/10e_218.jpg",
"tcgplayer_prices": [
{
"subTypeName": "Normal",
"lowPrice": 2.71,
"midPrice": 5.24,
"highPrice": 13.99,
"marketPrice": 5.36,
"directLowPrice": null
},
{
"subTypeName": "Foil",
"lowPrice": 18.91,
"midPrice": 23.03,
"highPrice": 32.0,
"marketPrice": 24.16,
"directLowPrice": null
}
],
"cardmarket": {
"prices": {
"avg1": "4.40",
"avg7": "2.84",
"avg30": "3.27",
"lowPrice": "0.25",
"trendPrice": "3.91",
"germanProLow": "0.00",
"lowPriceExPlus": "0.00",
"reverseHoloLow": "11.00",
"suggestedPrice": "0.00",
"reverseHoloAvg1": "8.00",
"reverseHoloAvg7": "12.79",
"reverseHoloSell": "8.00",
"averageSellPrice": "3.94",
"reverseHoloAvg30": "10.57",
"reverseHoloTrend": "16.34"
},
"updatedAt": "2026-11-11T02:45:23+0100"
},
"local_image_url": "/images/mtg/en/10e/10e_218.jpg"
}
]
All text-based filters (colors, type, rarity, artist, q, name) are case-insensitive.
Multiple filters use AND logic - cards must match ALL specified criteria to be returned.
Get all cards for a specific MTG set, enriched with local image URLs and served with gzip + ETag caching
| Parameter | Type | Description | Example |
|---|---|---|---|
| page | integer | Page number (starts from 1) | 1 |
| pageSize | integer | Cards per page (optional, max 250). If not provided, all cards are returned. | 50 |
Each card includes a local_image_url field pointing to this server's image library (or null when local art is missing). Responses carry an ETag header; send If-None-Match to revalidate and receive 304 Not Modified.
GET /mtg/cards/10e?pageSize=2
[
{
"id": "10e-218",
"name": "Manabarbs",
"mana_cost": "{3}{R}",
"tcgplayer_prices": [
{
"subTypeName": "Normal",
"marketPrice": 5.36
},
{
"subTypeName": "Foil",
"marketPrice": 24.16
}
],
"cardmarket": {
"prices": {
"trendPrice": "3.91",
"reverseHoloTrend": "16.34"
},
"updatedAt": "2026-11-11T02:45:23+0100"
},
"local_image_url": "/images/mtg/en/10e/10e_218.jpg",
"...": "..."
}
]
{"error": "Set 'xyz' not found"}{"error": "Error loading set data"}Get a card by name within a specific set โ dashes in the name are treated as spaces
/mtg/cards/10e/Manabarbs/mtg/cards/bbd/Sun Titan within a set containing multiple Sun Titan variants/mtg/cards/khm/sunA single match returns one card object; ambiguous matches return an array of candidates. Dashes in URL names are converted to spaces, so /mtg/cards/khm/sun-titan finds Sun Titan.
GET /mtg/cards/10e/Manabarbs
{
"id": "10e-218",
"name": "Manabarbs",
"tcgplayer_prices": [
{
"subTypeName": "Normal",
"marketPrice": 5.36
},
{
"subTypeName": "Foil",
"marketPrice": 24.16
}
],
"cardmarket": {
"prices": {
"trendPrice": "3.91",
"reverseHoloTrend": "16.34"
},
"updatedAt": "2026-11-11T02:45:23+0100"
},
"local_image_url": "/images/mtg/en/10e/10e_218.jpg",
"...": "..."
}
{"error": "Card 'xyz' not found in set '10e'"}{"error": "Set 'xyz' not found"}Get a single card by its ID (<set_code>-<collector_number>) โ O(1) index lookup, never builds the full search corpus
The card ID format is <set_code>-<collector_number>, e.g. 10e-218. Remember to URL-encode any characters where necessary.
GET /mtg/cards/id/10e-218
{
"id": "10e-218",
"name": "Manabarbs",
"set": "10e",
"collector_number": "218",
"tcgplayer_prices": [
{
"subTypeName": "Normal",
"marketPrice": 5.36
},
{
"subTypeName": "Foil",
"marketPrice": 24.16
}
],
"cardmarket": {
"prices": {
"trendPrice": "3.91",
"reverseHoloTrend": "16.34"
},
"updatedAt": "2026-11-11T02:45:23+0100"
},
"local_image_url": "/images/mtg/en/10e/10e_218.jpg",
"...": "..."
}
{"error": "Card 'xyz' not found"}Get the raw card data for a set with no enrichment โ identical to the disk payload
Same as /mtg/cards/{set_id} but without the added local_image_url field. Use this for exact data pipelines and ETag-based revalidation (it also responds with ETag/304 support).
GET /mtg/cards/10e/raw
Get all distinct color letters found across the corpus
{
"count": 5,
"colors": ["B", "G", "R", "U", "W"]
}
W = white, U = blue, B = black, R = red, G = green (use in the colors filter)
Get all distinct rarities in canonical order
{
"count": 6,
"rarities": ["special", "bonus", "common", "uncommon", "rare", "mythic"]
}
Get all distinct artists (sorted alphabetically); optional page/pageSize pagination โ the top-level count always reflects the full list
| Parameter | Type | Description | Example |
|---|---|---|---|
| page | integer | Page number | 1 |
| pageSize | integer | Artists per page (max 250) | 100 |
{
"count": 12480,
"page": 1,
"artists": ["A. Newman", "Aaron Jasinski", "..."]
}
MTG price history works the same way as the Pokemon price history: a snapshot of all TCGPlayer
prices is stored every day (automatically after the daily price refresh, and by
the server's internal 24h cycle) into price_history/mtg_history/daily_prices/<date>/<group_id>.json,
with trend analysis in price_history/mtg_history/price_trends.json.
group_id is the TCGPlayer set group id (same as tcgplayer_id in
/mtg/sets), product_id is the TCGPlayer product id (same as the card's
tcgplayer_id). Variants: Normal and Foil (etched products
report as Foil). History builds up over time โ day one is a single data point.
Manually trigger an MTG price history snapshot
| Parameter | Type | Description | Example |
|---|---|---|---|
| force | boolean | Re-snapshot even if one already exists for today | true |
{
"status": "success",
"message": "MTG price history snapshot completed successfully"
}
Overall MTG price history statistics and date range
{
"history_stats": {
"total_snapshots": 1,
"total_products_tracked": 155698,
"oldest_snapshot": "2026-11-15",
"newest_snapshot": "2026-11-15",
"storage_size_mb": 66.11
},
"date_range": {
"start_date": "2026-11-15",
"end_date": "2026-11-15",
"total_days": 1
},
"storage_dir": "price_history/mtg_history/"
}
Price history for all products in a set/group
| Parameter | Type | Description | Example |
|---|---|---|---|
| days | integer | Days of history (default 30) | 30 |
| subtype | string | Normal, Foil or all | all |
{
"group_id": "74",
"game": "mtg",
"history_days": 30,
"sub_type": "all",
"total_entries": 354,
"price_history": [
{
"date": "2026-11-15",
"timestamp": 1794681000,
"product_id": "121397",
"price": 272.59,
"low_price": 349.99,
"mid_price": 362.5,
"high_price": 450.0,
"sub_type": "Normal"
}
]
}
Responses cached for 5 minutes (X-Cache: HIT/MISS header). Returns 404 until at least one snapshot exists.
Price history + trend analysis for one card (by TCGPlayer product id)
| Parameter | Type | Description | Example |
|---|---|---|---|
| days | integer | Days of history (default 30) | 30 |
| subtype | string | Normal, Foil or all | Normal |
{
"group_id": "74",
"product_id": "121397",
"game": "mtg",
"price_history": [
{
"date": "2026-11-15",
"price": 272.59,
"low_price": 349.99,
"mid_price": 362.5,
"high_price": 450.0,
"sub_type": "Normal"
}
],
"trend_analysis": {
"current_price": 272.59,
"price_change": 0.0,
"price_change_percent": 0.0,
"avg_7d": 272.59,
"avg_30d": 272.59,
"min_price": 272.59,
"max_price": 272.59,
"data_points": 1
}
}
Detailed trend analysis only (all retained history, moving averages, min/max)
{
"group_id": "74",
"product_id": "121397",
"game": "mtg",
"sub_type": "Normal",
"trend_analysis": {
"current_price": 272.59,
"data_points": 1,
"price_history": [
{
"date": "2026-11-15",
"price": 272.59
}
]
}
}
Download a group's price history as CSV
| Parameter | Type | Description | Example |
|---|---|---|---|
| days | integer | Days of history (default 30) | 30 |
| subtype | string | Normal, Foil or all | all |
date,product_id,sub_type,price,low_price,mid_price,high_price
2026-11-15,4958,Normal,0.42,0.24,0.49,14.99
2026-11-15,4959,Normal,0.58,0.25,0.75,169.49
2026-11-15,4960,Normal,1.03,0.48,1.03,23.99
One row per product per day; foil products get their own sub_type=Foil rows (etched products also report as Foil). Add ?subtype=Normal or ?subtype=Foil to filter.
Response cache statistics / clear the cache after a manual snapshot
{
"cache_stats": {
"total_entries": 2,
"active_entries": 2,
"ttl_seconds": 300,
"max_size": 1000
}
}
Serve card art from the local image library (~12 GB, organized per set)
Filenames use underscore naming: hyphens in the card ID become underscores, e.g. card 10e-218 is stored as 10e_218.jpg. When you fetch cards via the JSON endpoints, each card's image_uris (and local_image_url) already contains a ready-to-use URL when local art exists.
https://proxysuper.com/images/mtg/en/{set_code}/{card_id_underscored}.jpg (used in card JSON data, e.g. .../10e/10e_218.jpg)
/mtg/images/{set_code}/{filename} (alias, same files)
GET /mtg/images/10e/10e_218.jpg
server_root/images/mtg/en/<set_code>/ on the server, keyed by card ID (hyphen โ underscore)import requests
# Get all MTG sets, newest first (first 10)
response = requests.get('http://proxysuper.com/mtg/sets?pageSize=10&orderBy=released_at&order=desc')
recent_sets = response.json()
print(f"Got {len(recent_sets)} recent sets")
# Get all cards of a set with local image URLs
response = requests.get('http://proxysuper.com/mtg/cards/10e?pageSize=50')
tenth_edition = response.json()
for card in tenth_edition[:5]:
print(card['name'], '->', card.get('local_image_url'), '-> $', card['tcgplayer_prices'][0]['marketPrice'])
# Efficient lookup by card ID
response = requests.get('http://proxysuper.com/mtg/cards/id/10e-218')
manabarbs = response.json()
prices = {p['subTypeName']: p['marketPrice'] for p in manabarbs['tcgplayer_prices']}
print(f"{manabarbs['name']}: Normal ${prices.get('Normal')} (Foil: ${prices.get('Foil')})")
print('CardMarket trend:', manabarbs['cardmarket']['prices']['trendPrice'])
# Complex corpus filter: white/green mythic 3-drop creatures sorted by name
response = requests.get(
'http://proxysuper.com/mtg/cards',
params={'colors': 'W,G', 'cmc': '3', 'rarity': 'mythic',
'type': 'creature', 'orderBy': 'name', 'page': 1, 'pageSize': 10}
)
finds = response.json()
print(f"Found {len(finds)} mythic 3-drop creatures")
# Find a card by name in a set
response = requests.get('http://proxysuper.com/mtg/cards/khm/Sun Titan')
sun_titan = response.json()
print(f"{sun_titan['name']} in Kaldheim: {sun_titan.get('local_image_url')}")
# Get recent sets
curl "http://proxysuper.com/mtg/sets?pageSize=10&orderBy=released_at&order=desc"
# Get cards of a set (gzipped automatically)
curl --compressed "http://proxysuper.com/mtg/cards/10e?pageSize=25"
# Lookup by card ID
curl --compressed "http://proxysuper.com/mtg/cards/id/10e-218"
# Complex filter: search + colors + cmc range + sorting + pagination
curl --compressed "http://proxysuper.com/mtg/cards?q=dragon&colors=W,R&cmc=4-6&orderBy=name&order=asc&page=1&pageSize=10"
# Fast single-set filter (skips corpus build)
curl --compressed "http://proxysuper.com/mtg/cards?set=khm&rarity=mythic&pageSize=3"
# Revalidate a cached set response (ETag)
curl --compressed -H "If-None-Match: <etag-from-previous-response>" -w "%{http_code}\n" "http://proxysuper.com/mtg/cards/10e/raw"
# Download a card image
curl "http://proxysuper.com/mtg/images/10e/10e_218.jpg" -o manabarbs.jpg
# Get API information
curl "http://proxysuper.com/mtg"
While there are no official SDKs yet, you can easily integrate this API using standard HTTP libraries in any programming language:
This is the MTG API. For Pokemon Trading Card Game endpoints, see the Pokemon TCG API Documentation, or visit /api/docs/mtg which redirects here.
Currently, there are no rate limits, but please be respectful with your API usage.