# Hearthstone API
> Hearthstone card data as an API, built on the open HearthstoneJSON dataset for Blizzard's collectible card game. Search and filter the full collectible card pool by name, class (Mage, Hunter, Priest, …), card type (minion, spell, weapon, hero), rarity, mana cost, set, minion race or mechanic (Battlecry, Deathrattle, Taunt and more). Fetch any card by its id or name for the full record: cost, attack, health/durability, rules text, flavour text, set, mechanics and rendered card art. List every class and set with card counts, or pull a random card (optionally matching a filter). Real data, no key needed upstream. Ideal for deck builders, collection trackers, card-search tools and Hearthstone fan apps.

## 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/hearthstone-api/..."
```

## Pricing
- **Free** (Free) — 10,500 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 142,000 calls/Mo, 8 req/s
- **Pro** ($17/Mo) — 730,000 calls/Mo, 25 req/s
- **Mega** ($62/Mo) — 3,400,000 calls/Mo, 50 req/s

## Endpoints

### Hearthstone

#### `GET /v1/card` — A single card by id or name

**Parameters:**
- `id` (query, required, string) — Card id or name, e.g. EX1_277 Example: `EX1_277`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hearthstone-api/v1/card?id=EX1_277"
```

**Response:**
```json
{
    "data": {
        "card": {
            "id": "EX1_277",
            "set": "Legacy",
            "cost": 1,
            "name": "Arcane Missiles",
            "text": "Deal 3 damage randomly split among all enemies.",
            "type": "Spell",
            "armor": null,
            "elite": false,
            "image": "https://art.hearthstonejson.com/v1/render/latest/enUS/256x/EX1_277.png",
            "races": [],
            "artist": "Warren Mahy",
            "attack": null,
            "dbf_id": 564,
            "flavor": "You'd think you'd be able to control your missiles a little better since you're a powerful mage and all.",
            "health": null,
            "rarity": "Free",
            "mechanics": [
                "Immunetospellpower"
            ],
            "card_class": "Mage",
            "durability": null,
            "collectible": true,
            "spell_school": "Arcane"
        }
    },
    "meta": {
        "timestamp": "2026-06-08T01:18:33.013Z",
        "request_id": "17951487-0021-4433-b63d-a425c32abba3"
    },
    "status": "ok",
    "message": "Card retrieved successfully",
    "success": true
}
```

#### `GET /v1/classes` — All classes with card counts

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

**Response:**
```json
{
    "data": {
        "count": 12,
        "classes": [
            {
                "name": "Neutral",
                "cards": 2097
            },
            {
                "name": "Mage",
                "cards": 583
            },
            {
                "name": "Paladin",
                "cards": 583
            },
            {
                "name": "Priest",
                "cards": 580
            },
            {
                "name": "Druid",
                "cards": 579
            },
            {
                "name": "Warlock",
                "cards": 574
            },
            {
                "name": "Hunter",
                "cards": 573
            },
            {
                "name": "Warrior",
                "cards": 570
            },
            {
                "name": "Shaman",
                "cards": 564
            },
            {
                "name": "Rogue",
                "cards": 561
            },
            {
                "name": "Demonhunter",
                "cards": 389
            },
            {
                "name": "Deathknight",
                "cards": 295
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-08T01:18:33.115Z",
        "request_id": "b6d38a4f-0e1f-4162-8211-feec2db730e8"
    },
    "status": "ok",
    "message": "Classes retrieved successfully",
    "success": true
}
```

#### `GET /v1/random` — A random card (accepts search filters)

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

**Response:**
```json
{
    "data": {
        "card": {
            "id": "FP1_017",
            "set": "Naxx",
            "cost": 2,
            "name": "Nerub'ar Weblord",
            "race": "Undead",
            "text": "Minions with Battlecry cost (2) more.",
            "type": "Minion",
            "armor": null,
            "elite": false,
            "image": "https://art.hearthstonejson.com/v1/render/latest/enUS/256x/FP1_017.png",
            "races": [
                "Undead"
            ],
            "artist": "Alex Horley Orlandelli",
            "attack": 1,
            "dbf_id": 1800,
            "flavor": "Weblords spend all day making giant trampoline parks.",
            "health": 4,
            "rarity": "Common",
            "mechanics": [
                "Aura"
            ],
            "card_class": "Neutral",
            "durability": null,
            "collectible": true
        }
    },
    "meta": {
        "timestamp": "2026-06-08T01:18:33.167Z",
        "request_id": "f3558ce8-f9f9-4cbc-9eec-2fbda026b543"
    },
    "status": "ok",
    "message": "Random card retrieved successfully",
    "success": true
}
```

#### `GET /v1/search` — Search & filter cards

**Parameters:**
- `name` (query, optional, string) — Name contains
- `class` (query, optional, string) — Class, e.g. mage Example: `mage`
- `type` (query, optional, string) — minion | spell | weapon | hero
- `rarity` (query, optional, string) — common | rare | epic | legendary Example: `legendary`
- `cost` (query, optional, string) — Exact mana cost
- `set` (query, optional, string) — Card set
- `race` (query, optional, string) — Minion race, e.g. dragon
- `mechanic` (query, optional, string) — Mechanic, e.g. taunt
- `limit` (query, optional, string) — Max results (default 30, max 200) Example: `30`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hearthstone-api/v1/search?class=mage&rarity=legendary&limit=30"
```

**Response:**
```json
{
    "data": {
        "cards": [
            {
                "id": "BT_006",
                "set": "Black Temple",
                "cost": 1,
                "name": "Evocation",
                "text": "Fill your hand with random Mage spells. They are Temporary.",
                "type": "Spell",
                "armor": null,
                "elite": true,
                "image": "https://art.hearthstonejson.com/v1/render/latest/enUS/256x/BT_006.png",
                "races": [],
                "artist": "Gonzalo Ordonez",
                "attack": null,
                "dbf_id": 56389,
                "flavor": "You too could be the winner of the national spelling spree!",
                "health": null,
                "rarity": "Legendary",
                "mechanics": [],
                "card_class": "Mage",
                "durability": null,
                "collectible": true,
                "spell_school": "Arcane"
            },
            {
                "id": "UNG_028",
                "set": "Ungoro",
                "cost": 1,
                "name": "Open the Waygate",
                "text": "Quest: Cast 8 spells that didn't start in your deck. Reward: Time Warp.",
                "type": "Spell",
                "armor": null,
                "elite": true,
                "image": "https://art.hearthstonejson.com/v1/render/latest/enUS/256x/UNG_028.png",
                "races": [],
                "artist": "Rafael Zanchetin",
                "a
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/sets` — All sets with card counts

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

**Response:**
```json
{
    "data": {
        "sets": [
            {
                "name": "Hero Skins",
                "cards": 714
            },
            {
                "name": "Placeholder 202204",
                "cards": 654
            },
            {
                "name": "Vanilla",
                "cards": 382
            },
            {
                "name": "Core",
                "cards": 289
            },
            {
                "name": "Expert1",
                "cards": 245
            },
            {
                "name": "Legacy",
                "cards": 230
            },
            {
                "name": "Space",
                "cards": 194
            },
            {
                "name": "Wild West",
                "cards": 183
            },
            {
                "name": "The Lost City",
                "cards": 183
            },
            {
                "name": "Emerald Dream",
                "cards": 183
            },
            {
                "name": "Time Travel",
                "cards": 183
            },
            {
                "name": "Battle Of The Bands",
                "cards": 183
            },
            {
                "name": "Whizbangs Workshop",
                "cards": 183
            },
            {
                "name": "Return Of The Lich King",
                "cards": 183
            },
            {
                "name": "Titans",
                "cards": 183
            },
       
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service description & endpoints

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

**Response:**
```json
{
    "data": {
        "service": "hearthstone-api",
        "endpoints": {
            "GET /v1/card": "A single card by id or name (id=, e.g. EX1_277 or Arcane Missiles).",
            "GET /v1/meta": "This document.",
            "GET /v1/sets": "All sets with card counts.",
            "GET /v1/random": "A random card (accepts the same filters as search).",
            "GET /v1/search": "Search/filter cards (name=, class=, type=, rarity=, cost=, set=, race=, mechanic=, limit=).",
            "GET /v1/classes": "All classes with card counts."
        },
        "description": "Hearthstone card data via the open HearthstoneJSON dataset: search and filter every collectible card by name, class, type, rarity, cost, set, minion race or mechanic; fetch a single card with its stats, text and rendered art; list the classes and sets; and pull a random card. Real data, no key."
    },
    "meta": {
        "timestamp": "2026-06-08T01:18:33.441Z",
        "request_id": "4ddc91e8-272f-4048-ac4c-7cf78470dc6f"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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