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

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

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

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

### Reference

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

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

### Meta

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

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


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