API Documentation

The Magic Price API returns fair market values for Magic: The Gathering cards. A machine learning model was trained to understand what a card is truly worth by studying every card, set, variation, and market listing across the game's entire history.

Authentication

All valuation endpoints require an API key passed via the X-API-Key header. Get a free key here. The public preview endpoint (/api/preview) does not require authentication.

curl -H "X-API-Key: mtg_your_key_here" \
  https://mtg-ai-api.fly.dev/api/prices?q=Lightning+Bolt

Endpoints

GET /api/preview

Public preview search. Same response shape as /api/prices but capped at 5 results. No authentication required.

Parameter	Type		Description
q	string	required	Card name search (partial match)
set	string	optional	Filter by set code
finish	string	optional	Filter by finish: normal, foil, etched
provider	string	optional	Filter by provider

GET /api/prices

Search for card fair market values by name. Returns results grouped by card with values across finishes, providers, and listings. Requires API key.

Parameter	Type		Description
q	string	required	Card name search (partial match)
set	string	optional	Filter by set code (e.g. LEA)
finish	string	optional	Filter by finish: normal, foil, etched
provider	string	optional	Filter by provider: tcgplayer, cardkingdom, cardmarket, cardhoarder, manapool
limit	int	optional	Max results (default 50)
offset	int	optional	Pagination offset (default 0)

curl -H "X-API-Key: mtg_..." \
  "https://mtg-ai-api.fly.dev/api/prices?q=Lightning+Bolt&set=LEA"

{
  "results": [
    {
      "uuid": "5f8287b1-5bb6-5f4c-ad17-316a40d5b0c",
      "name": "Lightning Bolt",
      "set_code": "LEA",
      "number": "161",
      "rarity": "common",
      "artist": "Christopher Rush",
      "layout": "normal",
      "mana_cost": "{R}",
      "mana_value": 1.0,
      "colors": ["R"],
      "color_identity": ["R"],
      "type_line": "Instant",
      "subtypes": [],
      "supertypes": [],
      "keywords": [],
      "power": "",
      "toughness": "",
      "loyalty": "",
      "defense": "",
      "finishes": ["nonfoil"],
      "border_color": "black",
      "frame_version": "1993",
      "watermark": "",
      "flavor_name": "",
      "flavor_text": "",
      "is_full_art": false,
      "is_promo": false,
      "is_reprint": false,
      "is_reserved": true,
      "is_textless": false,
      "is_alternative": false,
      "predictions": [
        {
          "finish": "normal",
          "provider": "tcgplayer",
          "listing": "retail",
          "price": 485.20
        }
      ]
    }
  ],
  "count": 1,
  "model_version": "2026-03-18T12:00:00"
}

GET /api/prices/{uuid}

Get the fair market value for a specific card by its MTGJSON UUID. Requires API key. Returns the same response shape as /api/prices.

curl -H "X-API-Key: mtg_..." \
  https://mtg-ai-api.fly.dev/api/prices/5f8287b1-5bb6-5f4c-ad17-316a40d5b0c

GET /api/health

Lightweight health check. No authentication required.

{
  "status": "ok"
}

GET /api/model

Returns metadata about the machine learning model currently powering valuations. No authentication required.

{
  "model_type": "XGBRegressor",
  "test_r2": 0.8942,
  "test_rmse_original": 3.21,
  "training_date": "2026-03-18T12:00:00",
  "feature_count": 121,
  "training_samples": 684000
}

Response Fields

Each card in the results array includes the following fields.

Field	Type	Description
uuid	string	Unique card identifier (MTGJSON)
name	string	Card name
set_code	string	Set code (e.g. LEA, MH2)
number	string	Collector number within the set
rarity	string	common, uncommon, rare, mythic, bonus, special
artist	string	Card artist
layout	string	Card layout (normal, split, flip, transform, modal_dfc, etc.)
mana_cost	string	Mana cost in brace notation (e.g. {2}{U}{U})
mana_value	number?	Converted mana cost (omitted if not applicable)
colors	string[]	Card colors: W, U, B, R, G
color_identity	string[]	Color identity (for Commander)
type_line	string	Full type line (e.g. Legendary Creature — Dragon)
subtypes	string[]	Subtypes (e.g. ["Dragon", "Spirit"])
supertypes	string[]	Supertypes (e.g. ["Legendary", "Snow"])
keywords	string[]	Keyword abilities (e.g. ["Flying", "Haste"])
power	string	Power (creatures only, empty otherwise)
toughness	string	Toughness (creatures only, empty otherwise)
loyalty	string	Starting loyalty (planeswalkers only)
defense	string	Defense value (battles only)
finishes	string[]	Available finishes: nonfoil, foil, etched
border_color	string	black, borderless, gold, silver, white
frame_version	string	Frame era: 1993, 1997, 2003, 2015
watermark	string	Watermark name (if any)
flavor_name	string	Alternate flavor name (e.g. Godzilla series)
flavor_text	string	Flavor text
is_full_art	bool	Full art printing
is_promo	bool	Promotional printing
is_reprint	bool	Card has been printed before
is_reserved	bool	On the Reserved List
is_textless	bool	Textless printing
is_alternative	bool	Alternate art printing

Each card's predictions array contains one entry per finish/provider/listing combination:

Field	Type	Description
finish	string	normal, foil, or etched
provider	string	Price source: tcgplayer, cardkingdom, cardmarket, cardhoarder, manapool
listing	string	retail or buylist
price	number	Fair market value in USD

Rate Limits

Requests are tracked per API key on a daily basis (UTC). When you exceed your limit, the API returns 429 Too Many Requests. Upgrade from your account page.

Tier	Daily Limit	Price
Free	30 requests	$0
Basic	50,000 requests	$10/mo
Unlimited	Unlimited	Custom

Errors

All errors return JSON with an error field.

Status	Meaning
400	Missing or invalid query parameter
401	Missing or invalid API key
404	No card found for that UUID
429	Daily rate limit exceeded
503	Service not configured (auth or billing disabled)

{
  "error": "daily limit exceeded (30 req/day for free tier)"
}