MTG TCG API Documentation

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.

Base URL
http://proxysuper.com/mtg

Local Testing: http://localhost:5000/mtg

Features

  • Complete MTG database: 1,031 sets / ~117,000 cards
  • Scryfall-native card format with embedded dual pricing (tcgplayer_prices array: Normal / Foil entries, plus a cardmarket object)
  • Advanced filtering and search (colors, mana cost, type, rarity, artist, set)
  • Pagination support
  • Local image serving per set
  • Metadata endpoints: colors, rarities, artists
  • Gzip compression, ETag revalidation, and cache-friendly headers
  • Runs alongside the Pokemon API โ€” separate /mtg/ routes, no interference
Card Format:

Card 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.

Authentication

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.

Card Format & URL Structure

All MTG endpoints live under the /mtg/ prefix:

URL Structure
/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>/)
Card ID Format

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.

Pagination

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.
Important:

/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.

Filtering & Search

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 field
  • order - Sort direction (asc, desc)
Performance tip: filtering by set loads only that set's file from disk and skips building the full in-memory corpus โ€” it is the fastest filter available.
Filter Behavior:
  • All text filters are case-insensitive
  • Multiple filters use AND logic; values inside one filter (e.g. colors=W,R) use OR logic
  • Empty or missing filter values are ignored
  • Invalid values return no results (empty array)

Sets

GET /mtg/sets

Get all MTG sets (1,066 sets) from the project-root mtg_sets.json, sorted by release date (newest first by default)

Query Parameters
Parameter Type Description Example
pageintegerPage number (starts from 1)1
pageSizeintegerSets per page (optional, max 250)50
set_typestringFilter by set type (exact match)expansion, core, commander, token, promo, masters
qstringSearch query - searches set code and name (case-insensitive)khm
orderBystringSort field (code, name, released_at, card_count). Default: released_atcode
orderstringSort direction (asc for ascending, desc for descending). Default: descasc
Response Fields

Each set object contains (all fields from the project-root mtg_sets.json, plus two convenience URLs):

Field Type Description
codestringSet code (lowercase, e.g. "khm") โ€” used in all other endpoints
namestringFull set name
released_atstringRelease date (ISO 8601)
set_typestringSet type (expansion, core, commander, ...)
card_countintegerNumber of cards printed in the set
tcgplayer_idintegerTCGPlayer group ID for the set (may be absent)
icon_svgstringSet symbol icon URL (Scryfall SVG)
block_code / blockstringBlock information (may be absent)
digitalbooleanTrue for digital-only sets
json_urlstringAdded by API - URL to fetch this set's cards
image_base_urlstringAdded by API - Base URL for this set's images
Example Request
GET /mtg/sets?pageSize=2&orderBy=code&order=asc
Example Response
[
  {
    "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 /mtg/sets/{set_code}

Get metadata for a single MTG set by code โ€” returns 404 if the code is unknown

Example Request
GET /mtg/sets/10e
Example Response
{
  "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 Responses:
  • 404: {"error": "Set 'xyz' not found"}

Cards

GET /mtg/cards

Search across the entire MTG corpus (~117,000 cards) with filtering and pagination. Always pass pageSize!

Query Parameters
Parameter Type Description Example
pageintegerPage number (starts from 1)1
pageSizeintegerItems per page (optional, max 250). If omitted, ALL matching cards are returned โ€” hundreds of MB!50
qstringSearch query - searches in card name, id, and type_line (case-insensitive)manabarbs
namestringFilter by card name (case-insensitive, partial match)lightning
colorsstringFilter by colors (comma-separated color letters, OR logic). W=white U=blue B=black R=red G=greenW,R
typestringFilter by type_line (case-insensitive, partial match)creature
cmcstringFilter by converted mana cost - exact value or inclusive range4 or 2-5
raritystringFilter by rarity (case-insensitive, partial match): common, uncommon, rare, mythic, special, bonusmythic
setstringFilter by set code (exact match). Fast โ€” loads only that set filekhm
artiststringFilter by artist name (case-insensitive, partial match)Jeff Miracola
orderBystringSort field (id, name, cmc, rarity, released_at, set, collector)name
orderstringSort direction (asc for ascending, desc for descending)asc
CMC Filter Details
Converted Mana Cost Filtering Options:
  • Exact CMC: cmc=4 - Returns cards with exactly 4 converted mana cost
  • CMC Range: cmc=2-5 - Returns cards with CMC between 2 and 5 (inclusive)
  • Cards without a numeric CMC are excluded from CMC-based filtering
Example Requests
Basic Search and Filter
GET /mtg/cards?name=manabarbs&page=1&pageSize=10
Multiple Filters with CMC Range
GET /mtg/cards?colors=W,R&cmc=3-5&rarity=rare&pageSize=10
Search with Multiple Filters and Sorting
GET /mtg/cards?q=goblin&colors=R&orderBy=name&order=desc&page=1&pageSize=10
Fast Single-Set Search
GET /mtg/cards?set=khm&rarity=mythic&pageSize=3
Example Response
[
  {
    "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"
  }
]
Filter Behavior
Case Sensitivity:

All text-based filters (colors, type, rarity, artist, q, name) are case-insensitive.

Multiple Values:
  • Colors filter: Uses OR logic - cards matching ANY of the specified colors will be returned
  • Empty filters: Empty or missing filter values are ignored and return all cards
Combining Filters:

Multiple filters use AND logic - cards must match ALL specified criteria to be returned.

Edge Cases and Error Handling
Expected Behaviors:
  • Invalid color letters: Returns 0 results (empty array)
  • Invalid pageSize: Values exceeding 250 are capped at the maximum limit
  • Non-existent Pages: Returns empty array when page number exceeds available pages
  • Sorting: collector_number sorting handles alphanumeric numbers (e.g. "100a"); unknown rarities sort after mythic

GET /mtg/cards/{set_id}

Get all cards for a specific MTG set, enriched with local image URLs and served with gzip + ETag caching

Query Parameters
Parameter Type Description Example
pageintegerPage number (starts from 1)1
pageSizeintegerCards 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.

Example Request
GET /mtg/cards/10e?pageSize=2
Example Response
[
  {
    "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 Responses:
  • 404: {"error": "Set 'xyz' not found"}
  • 500: {"error": "Error loading set data"}

Card by Name

GET /mtg/cards/{set_id}/{card_name}

Get a card by name within a specific set โ€” dashes in the name are treated as spaces

Name Matching Priority:
  1. Exact match: /mtg/cards/10e/Manabarbs
  2. Starts-with match: /mtg/cards/bbd/Sun Titan within a set containing multiple Sun Titan variants
  3. Partial match: /mtg/cards/khm/sun

A 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.

Example Request
GET /mtg/cards/10e/Manabarbs
Example Response
{
  "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 Responses:
  • 404: {"error": "Card 'xyz' not found in set '10e'"}
  • 404: {"error": "Set 'xyz' not found"}

Card by ID

GET /mtg/cards/id/{card_id}

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.

Example Request
GET /mtg/cards/id/10e-218
Example Response
{
  "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 Responses:
  • 404: {"error": "Card 'xyz' not found"}

Raw Cards Data

GET /mtg/cards/{set_id}/raw

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).

Example Request
GET /mtg/cards/10e/raw

Colors, Rarities & Artists

GET /mtg/colors

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 /mtg/rarities

Get all distinct rarities in canonical order

{
  "count": 6,
  "rarities": ["special", "bonus", "common", "uncommon", "rare", "mythic"]
}

GET /mtg/artists

Get all distinct artists (sorted alphabetically); optional page/pageSize pagination โ€” the top-level count always reflects the full list

Query Parameters
ParameterTypeDescriptionExample
pageintegerPage number1
pageSizeintegerArtists per page (max 250)100
{
  "count": 12480,
  "page": 1,
  "artists": ["A. Newman", "Aaron Jasinski", "..."]
}

Price History

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.

GET /mtg/pricing/history/snapshot

Manually trigger an MTG price history snapshot

Query Parameters
ParameterTypeDescriptionExample
forcebooleanRe-snapshot even if one already exists for todaytrue
{
  "status": "success",
  "message": "MTG price history snapshot completed successfully"
}

GET /mtg/pricing/history/stats

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/"
}

GET /mtg/pricing/history/group/{group_id}

Price history for all products in a set/group

Query Parameters
ParameterTypeDescriptionExample
daysintegerDays of history (default 30)30
subtypestringNormal, Foil or allall
{
  "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.

GET /mtg/pricing/history/card/{group_id}/{product_id}

Price history + trend analysis for one card (by TCGPlayer product id)

Query Parameters
ParameterTypeDescriptionExample
daysintegerDays of history (default 30)30
subtypestringNormal, Foil or allNormal
{
  "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
  }
}

GET /mtg/pricing/history/trends/{group_id}/{product_id}

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
      }
    ]
  }
}

GET /mtg/pricing/history/export/{group_id}

Download a group's price history as CSV

Query Parameters
ParameterTypeDescriptionExample
daysintegerDays of history (default 30)30
subtypestringNormal, Foil or allall
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.

GET /mtg/pricing/history/cache POST /mtg/pricing/history/cache/clear

Response cache statistics / clear the cache after a manual snapshot

{
  "cache_stats": {
    "total_entries": 2,
    "active_entries": 2,
    "ttl_seconds": 300,
    "max_size": 1000
  }
}

Images

GET /mtg/images/{set_code}/{filename}

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.

Two URL Patterns
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)
Example Request
GET /mtg/images/10e/10e_218.jpg
Notes:
  • Missing images return a plain 404
  • Resolved paths are LRU-cached per worker for fast repeated lookups
  • Image files live in server_root/images/mtg/en/<set_code>/ on the server, keyed by card ID (hyphen โ†’ underscore)

Code Examples

Python

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')}")

cURL

# 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"

SDKs & Libraries

While there are no official SDKs yet, you can easily integrate this API using standard HTTP libraries in any programming language:

  • JavaScript: fetch(), axios, or any HTTP client
  • Python: requests, httpx, or urllib
  • Java: OkHttp, Apache HttpClient
  • C#: HttpClient
  • PHP: cURL, Guzzle
  • Go: net/http package
Related Documentation

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.

Rate Limiting

Currently, there are no rate limits, but please be respectful with your API usage.