# MTG API
> The complete Magic: The Gathering card database as an API — every card ever printed, backed by Scryfall. Look up a card by name (exact, with automatic fuzzy fallback, e.g. "Black Lotus" → mana cost {0}, type, oracle text, rarity, set, format legalities and current market prices), search the entire pool with Scryfall's powerful query syntax (e.g. q=goblin, q=c:red type:creature cmc<=3, ordered by name/cmc/usd/rarity), pull a random card with an optional filter, browse all 1,000+ sets, and list every mana/cost symbol with its glyph. Each card carries colors, color identity, keywords, power/toughness/loyalty, collector number, artist, release date, high-resolution image and prices in USD/EUR/TIX. Ideal for deckbuilders, collection trackers, price-checkers, Discord bots, judges and MTG content tools.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/mtg-api/..."
```

## Pricing
- **Free** (Free) — 3,000 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 50,000 calls/Mo, 8 req/s
- **Pro** ($20/Mo) — 250,000 calls/Mo, 20 req/s
- **Mega** ($50/Mo) — 1,300,000 calls/Mo, 50 req/s

## Endpoints

### Cards

#### `GET /v1/card` — A card by name (exact, then fuzzy)

**Parameters:**
- `name` (query, required, string) — Card name, e.g. Black Lotus (exact match preferred, fuzzy fallback) Example: `Black Lotus`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mtg-api/v1/card?name=Black+Lotus"
```

**Response:**
```json
{
    "data": {
        "card": {
            "id": "bd8fa327-dd41-4737-8f19-2cf5eb1f7cdd",
            "cmc": 0,
            "set": "vma",
            "name": "Black Lotus",
            "image": "https://cards.scryfall.io/normal/front/b/d/bd8fa327-dd41-4737-8f19-2cf5eb1f7cdd.jpg?1614638838",
            "power": null,
            "artist": "Chris Rahn",
            "colors": [],
            "prices": {
                "eur": null,
                "tix": "75.20",
                "usd": null,
                "eur_foil": null,
                "usd_foil": null,
                "usd_etched": null
            },
            "rarity": "bonus",
            "loyalty": null,
            "keywords": [],
            "set_name": "Vintage Masters",
            "mana_cost": "{0}",
            "toughness": null,
            "type_line": "Artifact",
            "legalities": {
                "tlr": "banned",
                "duel": "banned",
                "brawl": "not_legal",
                "penny": "not_legal",
                "predh": "banned",
                "future": "not_legal",
                "legacy": "banned",
                "modern": "not_legal",
                "pauper": "not_legal",
                "alchemy": "not_legal",
                "pioneer": "not_legal",
                "vintage": "restricted",
                "historic": "not_legal",
                "standard": "not_legal",
                "timeless": "not_legal",
                "commander": "banned",
            
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/random` — A random card (optional Scryfall filter)

**Parameters:**
- `q` (query, optional, string) — Optional Scryfall filter, e.g. t:land Example: `t:land`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mtg-api/v1/random?q=t%3Aland"
```

**Response:**
```json
{
    "data": {
        "card": {
            "id": "a249b1f4-2b22-4b67-a207-e0c4ae95d2e1",
            "cmc": 0,
            "set": "iko",
            "name": "Ketria Triome",
            "image": "https://cards.scryfall.io/normal/front/a/2/a249b1f4-2b22-4b67-a207-e0c4ae95d2e1.jpg?1601241399",
            "power": null,
            "artist": "Sam Burley",
            "colors": [],
            "prices": {
                "eur": "13.05",
                "tix": "0.15",
                "usd": "17.56",
                "eur_foil": "13.73",
                "usd_foil": "18.35",
                "usd_etched": null
            },
            "rarity": "rare",
            "loyalty": null,
            "keywords": [
                "Cycling"
            ],
            "set_name": "Ikoria: Lair of Behemoths",
            "mana_cost": "",
            "toughness": null,
            "type_line": "Land — Forest Island Mountain",
            "legalities": {
                "tlr": "legal",
                "duel": "legal",
                "brawl": "legal",
                "penny": "not_legal",
                "predh": "not_legal",
                "future": "not_legal",
                "legacy": "legal",
                "modern": "legal",
                "pauper": "not_legal",
                "alchemy": "not_legal",
                "pioneer": "legal",
                "vintage": "legal",
                "historic": "legal",
                "standard": "not_legal",
                "timeless": "leg
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search` — Search the card pool with Scryfall query syntax

**Parameters:**
- `q` (query, required, string) — Scryfall query, e.g. goblin or c:red type:creature cmc<=3 Example: `goblin`
- `order` (query, optional, string) — name|released|set|rarity|color|usd|cmc|power|toughness|edhrec (default name) Example: `cmc`
- `page` (query, optional, string) — Result page (1-100, default 1) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mtg-api/v1/search?q=goblin&order=cmc&page=1"
```

**Response:**
```json
{
    "data": {
        "page": 1,
        "cards": [
            {
                "id": "dc36acc6-db4b-45b7-b526-7966ff82a44f",
                "cmc": 0,
                "set": "evg",
                "name": "Goblin Burrows",
                "image": "https://cards.scryfall.io/normal/front/d/c/dc36acc6-db4b-45b7-b526-7966ff82a44f.jpg?1562939268",
                "power": null,
                "artist": "David Martin",
                "colors": [],
                "prices": {
                    "eur": "0.49",
                    "tix": null,
                    "usd": "0.76",
                    "eur_foil": null,
                    "usd_foil": null,
                    "usd_etched": null
                },
                "rarity": "uncommon",
                "loyalty": null,
                "keywords": [],
                "set_name": "Duel Decks Anthology: Elves vs. Goblins",
                "mana_cost": "",
                "toughness": null,
                "type_line": "Land",
                "legalities": {
                    "tlr": "legal",
                    "duel": "legal",
                    "brawl": "not_legal",
                    "penny": "not_legal",
                    "predh": "legal",
                    "future": "not_legal",
                    "legacy": "legal",
                    "modern": "not_legal",
                    "pauper": "not_legal",
                    "alchemy": "not_legal",
                    "pioneer": "not_legal",
                   
…(truncated, see openapi.json for full schema)
```

### Sets

#### `GET /v1/sets` — Every MTG set with paging

**Parameters:**
- `limit` (query, optional, string) — Page size (1-1000, default 50) Example: `50`
- `offset` (query, optional, string) — Pagination offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mtg-api/v1/sets?limit=50&offset=0"
```

**Response:**
```json
{
    "data": {
        "sets": [
            {
                "code": "trk",
                "icon": "https://svgs.scryfall.io/sets/default.svg?1779681600",
                "name": "Star Trek",
                "digital": false,
                "set_type": "expansion",
                "card_count": 0,
                "released_at": "2026-11-20"
            },
            {
                "code": "trc",
                "icon": "https://svgs.scryfall.io/sets/default.svg?1779681600",
                "name": "Star Trek Commander",
                "digital": false,
                "set_type": "commander",
                "card_count": 1,
                "released_at": "2026-11-20"
            },
            {
                "code": "fra",
                "icon": "https://svgs.scryfall.io/sets/fra.svg?1779681600",
                "name": "Reality Fracture",
                "digital": false,
                "set_type": "expansion",
                "card_count": 7,
                "released_at": "2026-10-02"
            },
            {
                "code": "hoc",
                "icon": "https://svgs.scryfall.io/sets/hoc.svg?1779681600",
                "name": "The Hobbit Commander",
                "digital": false,
                "set_type": "commander",
                "card_count": 7,
                "released_at": "2026-08-14"
            },
            {
                "code": "thob",
                "icon": "https://svgs.scryfall.io/sets/hob.svg?1779681600",
        
…(truncated, see openapi.json for full schema)
```

### Reference

#### `GET /v1/symbology` — Mana & cost symbols

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mtg-api/v1/symbology"
```

**Response:**
```json
{
    "data": {
        "count": 84,
        "symbols": [
            {
                "colors": [],
                "symbol": "{T}",
                "english": "tap this permanent",
                "mana_value": 0,
                "represents_mana": false
            },
            {
                "colors": [],
                "symbol": "{Q}",
                "english": "untap this permanent",
                "mana_value": 0,
                "represents_mana": false
            },
            {
                "colors": [],
                "symbol": "{E}",
                "english": "an energy counter",
                "mana_value": 0,
                "represents_mana": false
            },
            {
                "colors": [],
                "symbol": "{P}",
                "english": "modal budget pawprint",
                "mana_value": 0,
                "represents_mana": false
            },
            {
                "colors": [],
                "symbol": "{PW}",
                "english": "planeswalker",
                "mana_value": 0,
                "represents_mana": false
            },
            {
                "colors": [],
                "symbol": "{CHAOS}",
                "english": "chaos",
                "mana_value": 0,
                "represents_mana": false
            },
            {
                "colors": [],
                "symbol": "{A}",
                "english": "an acorn counter",
                "mana_value": 0,
     
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Source & usage notes

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mtg-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Magic: The Gathering cards. /v1/card = a card by name (exact then fuzzy, e.g. name=Black Lotus) with mana cost, type, oracle text, rarity, set, legalities and prices; /v1/search = the card pool via Scryfall query syntax (e.g. q=goblin, q=c:red type:creature, order=cmc, page=2); /v1/random = a random card (optional q filter); /v1/sets = every set with paging; /v1/symbology = mana symbols. Data & images © Wizards of the Coast via Scryfall.",
        "source": "Scryfall (api.scryfall.com)",
        "endpoints": [
            "/v1/card",
            "/v1/search",
            "/v1/random",
            "/v1/sets",
            "/v1/symbology",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:44.147Z",
        "request_id": "4bad15e7-6dd9-4f40-9210-53d7f49686c3"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/mtg-api
OpenAPI spec: https://www.oanor.com/api/mtg-api/openapi.json