MTG Mate API & Scraper: parameters and responses
This is the reference for the 10 MTG Mate endpoints under /mtgmate/v1 (search, printings, set, sets, card, stock, buylist, decklist, recently_added and staples) and their 21 parameters. Each endpoint lists its parameters, required or optional, with allowed values and defaults, and comes with a cURL, Python and JavaScript call; every response uses the same { ok, data, meta, error } envelope.
The MTG Mate API returns Australia's mtgmate.com.au Magic: The Gathering singles store as clean JSON in Australian dollars.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
Each row is one SKU, so every finish of a printing has its own row with its own price: search by name, printings for every version of one exact card, and set for a whole set of up to 2000 rows, each with set, card number, rarity, finish, foil flag, AUD price, units in stock, in_stock, type line and image. Filters cover finish, rarity, color, type line, price range, language and in-stock only; sort by price, name or stock. card returns one printing in full, with the store's live price and units, mana cost, rules text, the other printings in stock with their prices, and what buyers of that card also bought. stock is the small call for watching one SKU you already know. buylist is what the store pays, in cash and in store credit, with how many it wants, as a hot list or per set. decklist prices a pasted deck: up to 10 in-stock printings per card, the store's suggested pick, the deck total and the cards it cannot fill. sets lists every set with its code, release date and parent, recently_added returns the newest stock by day, and staples returns the cards the store lists for a format. No account, no browser - one ReefAPI key and the standard { ok, data, meta, error } envelope.
Foil and non-foil are separate rows, so a printing never shows one blended price
MTG Mate lists each finish of a printing as its own item. Lightning Bolt alone has 71 listings, 27 of them in stock on 2026-11-08: 38 non-foil, 31 foil and 2 etched. On 96 items we compared on 2026-11-08 the price and units in the API rows equalled the store's live buying panel on all 96.
| Card (set) | finish | price_aud | stock |
|---|---|---|---|
| Lightning Bolt (Commander Legends: Battle for Baldur's Gate) | Nonfoil | 4.00 | 4 |
| Lightning Bolt (Magic Player Rewards 2010, promo) | Foil | 60.00 | 2 |
| Lightning Bolt (Judge Gift Cards 1998, promo) | Foil | 1,275.00 | 1 |
| Sword of Feast and Famine (Double Masters) | Nonfoil | 83.00 | 4 |
| Sword of Feast and Famine (Double Masters) | Foil | 100.00 | 1 |
Prices are the store's asking prices in AUD and exclude shipping. MTG Mate says it does not grade its singles, so condition is returned as the store lists it (Regular on every row we surveyed) and there are no separate Near Mint and Played prices. Sold-out printings stay in the results with their last price and stock 0, unless you ask for in-stock only.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/mtgmate/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "lightning bolt",
"limit": 5
}
}{
"ok": true,
"meta": {
"api": "mtgmate",
"endpoint": "search",
"mode": "live",
"latency_ms": 912.2,
"record_count": 5,
"bytes": 110950,
"cache_hit": false,
"requests": 1,
"charged_credits": 2,
"version": "0.1.0",
"request_id": "fb0b6c4a7a424b33",
"queue_ms": 1.5,
"fetched_at": "2026-11-08T13:04:29.025Z"
},
"data": {
"query": "lightning bolt",
"results": [
{
"sku": "47baa1e6-8200-5a19-a865-8b8c52ad228d",
"name": "Emeritus of Conflict // Lightning Bolt",
"set": "Secrets of Strixhaven",
"set_code": "sos",
"card_number": "113",
"rarity": "mythic",
"finish": "Nonfoil",
"foil": false,
"language": null,
"condition": "Regular",
"price_aud": 5,
"stock": 4,
"in_stock": true,
"colors": [
"R"
],
"type_line": "Creature — Human Wizard // Instant",
"preorder": false,
"is_unique_item": false,
"unique_item_note": null,
"image_url": "https://df379stvi8n1.cloudfront.net/assets/images/940dbb0f-3cc7-5d76-ba48-85952d16508d",
"url": "https://www.mtgmate.com.au/cards/Emeritus_of_Conflict_//_Lightning_Bolt/SOS/113"
},
{
"sku": "74e0dd52-f6cf-5f73-bade-5c4e717e327d",
"name": "Emeritus of Conflict // Lightning Bolt",
"set": "Secrets of Strixhaven",
"set_code": "sos",
"card_number": "113",
"rarity": "mythic",
"finish": "Foil",
"foil": true,
"language": null,
"condition": "Regular",
"price_aud": 5,
"stock": 1,
"in_stock": true,
"colors": [
"R"
],
"type_line": "Creature — Human Wizard // Instant",
"preorder": false,
"is_unique_item": false,
"unique_item_note": null,
"image_url": "https://df379stvi8n1.cloudfront.net/assets/images/940dbb0f-3cc7-5d76-ba48-85952d16508d",
"url": "https://www.mtgmate.com.au/cards/Emeritus_of_Conflict_//_Lightning_Bolt/SOS/113:foil"
},
{
"sku": "f4bb64cc-9939-5c55-9aaf-1d980ade7e14",
"name": "Emeritus of Conflict // Lightning Bolt (Extended Art)",
"set": "Secrets of Strixhaven",
"set_code": "sos",
"card_number": "332",
"rarity": "mythic",
"finish": "Nonfoil",
"foil": false,
"language": null,
"condition": "Regular",
"price_aud": 9,
"stock": 0,
"in_stock": false,
"colors": [
"R"
],
"type_line": "Creature — Human Wizard // Instant",
"preorder": false,
"is_unique_item": false,
"unique_item_note": null,
"image_url": "https://df379stvi8n1.cloudfront.net/assets/images/5d9f3ef6-cb47-5a81-ace4-ef02b456f253",
"url": "https://www.mtgmate.com.au/cards/Emeritus_of_Conflict_//_Lightning_Bolt/SOS/332"
}
],
"count": 5,
"total": 75,
"site_total": 75,
"page": 1,
"pages": 15,
"limit": 5,
"has_more": true,
"sort": "relevance",
"truncated": false
}
}What the MTG Mate API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Find cards by name across the store: every matching SKU with set, card number, rarity, finish, AUD price, units in stock and image. Foil and non-foil are separate rows. Needs at least 3 characters. The store caps one search at 1000 SKUs; truncated says when that was reached. Filter, sort and page the answer with the parameters below. | Pricing teams call search to find cards by name across the store. | query, set_code, finish, rarity, color, ... |
| printings | Every printing of one exact card name, including sold-out ones with their last price: set, number, rarity, finish, AUD price and stock per SKU. Use it to find the cheapest copy of a card in Australia or to watch every version of one card. | Marketplace operators call printings to get every printing of one exact card name, including sold-out ones with their last price. | name, set_code, finish, rarity, color, ... |
| set | One whole Magic set as the store lists it: every card in every finish with AUD price and stock. Filter, sort and page the answer, or ask up to 2000 rows at once. | Catalog enrichment teams call set to get one whole Magic set as the store lists it. | set_code, finish, rarity, color, type, ... |
| sets | The store's set directory, newest first: name, code, number of SKUs listed, release date and parent set for commander decks, tokens and bonus sheets. | Retail analysts call sets to get the store's set directory, newest first. | query |
| card | One printing in full: AUD price, units in stock, finish, rarity, mana cost, rules text, set and number, plus the other printings in stock with their prices and what buyers of this card also bought. Give url, or name + set_code + card_number. | Pricing teams call card to get one printing in full. | url, name, set_code, card_number, finish, ... |
| stock | Live AUD price and units in stock for one SKU (the sku on any row). The cheapest way to watch a card you already know. | Marketplace operators call stock to get live AUD price and units in stock for one SKU (the sku on any row). | sku |
| buylist | What MTG Mate pays for cards: cash and store-credit price in AUD and how many it wants, for Near Mint copies. Without set_code it returns the store's hot list; with set_code, the cards it is buying from that set. | Catalog enrichment teams call buylist to get what MTG Mate pays for cards. | set_code, min_cash, limit |
| decklist | Price a whole deck at MTG Mate. Paste one card per line (4 Lightning Bolt); the answer lists up to 10 in-stock printings per card with price and stock, the store's suggested pick, the deck total at that pick, and the cards it cannot fill. | Retail analysts call decklist to get price a whole deck at MTG Mate. | decklist |
| recently_added | The newest stock added to the store, with the day it was added: name, set, number, finish and link. The store's feed carries no price; use card or stock for one. Last 100 or last 1000. | Pricing teams call recently_added to get the newest stock added to the store, with the day it was added. | count |
| staples | The cards MTG Mate lists as staples for a format, grouped by card type, with the store's last update date. Use printings for prices. | Marketplace operators call staples to get the cards MTG Mate lists as staples for a format, grouped by card type, with the store's last…. | format |
Call search from your stack
curl -X POST https://api.reefapi.com/mtgmate/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"lightning bolt","limit":5}'import os
import requests
REEF_KEY = os.environ["REEF_KEY"]
r = requests.post(
"https://api.reefapi.com/mtgmate/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "lightning bolt",
"limit": 5
},
timeout=90,
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/mtgmate/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "lightning bolt",
"limit": 5
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.mtgmate.search with {"query":"lightning bolt","limit":5}.Who uses this API and why
- Track Australian retail prices for Magic singles, one printing and finish at a time
- Find the cheapest copy of a card in Australia across all its printings, with units in stock
- Compare what MTG Mate sells a card for with what it buys it for, in cash and credit
- Price a Commander or Modern deck in AUD before buying
Questions developers ask before integrating
Does the API separate foil and non-foil prices?
Yes. Each finish is its own row with its own sku, price and stock: finish is Nonfoil, Foil, Etched or Glossy, and foil is true or false. Filter with finish=foil, or finish=nonfoil.
Are these prices in Australian dollars?
Yes, every price field ends in _aud and is the store's listed price in AUD. Shipping is not included.
Can I get the condition of a card?
Only what the store publishes. MTG Mate states that it does not grade its singles, so list rows carry the store's value, Regular, on every row we surveyed. There are no separate prices per condition. The buylist is for Near Mint copies only, as the store's own instructions say.
How do I watch a card's price and stock?
Take its sku from search or printings and call stock. It returns the live AUD price, units and in_stock, and costs less than a full card call. Use card when you also want rules text, mana cost and the other printings.
What does MTG Mate pay for cards?
buylist returns cash and store credit in AUD plus how many the store wants. The hot list had 186 cards on 2026-11-08, cash from A$1.50 to A$40 (median A$3.00) and store credit about 25% higher. Pass set_code for one set, or min_cash to keep only the better offers. Looking up the buy price of any single card needs a store account and is not offered.
Can I price a whole deck?
Yes. decklist takes the deck as text, one card per line, up to 5000 characters. It returns up to 10 in-stock printings per card, the store's suggested pick, the total at that pick, and the cards it cannot fill. Names must be exact.
How many results does a search return?
The store caps one search at 1000 listings; truncated is true when that happens, and narrowing the name, set or finish gets the rest. Short searches need at least three letters. set has no such cap (Commander Masters returned 1630 rows in one call).
What is the MTG Mate API?
MTG Mate API is a ReefAPI endpoint group for australian magic: the gathering singles in aud: foil and non-foil apart, live stock, whole sets, buylist and deck pricing. It returns live JSON through POST requests under /mtgmate/v1.
Is the MTG Mate API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. MTG Mate calls use the same shared credit balance as every other ReefAPI engine.
Do I need a MTG Mate login or account?
No login to MTG Mate is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the MTG Mate data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the MTG Mate API use?
MTG Mate actions currently cost 1-3 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call MTG Mate from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call mtgmate actions with the same key, credit pool and JSON envelope used by normal REST requests.
Is the MTG Mate API a MTG Mate scraper?
It is the managed alternative to a DIY MTG Mate scraper. Instead of building and maintaining your own scraper — proxies, headless browsers, captcha and constant breakage — you call one ReefAPI endpoint and get the same australian magic: the gathering singles in aud: foil and non-foil apart, live stock, whole sets, buylist and deck pricing back as clean JSON.