canonical: https://jentic.com/apis/hearthstoneapi.com/hearthstoneapi

# Hearthstone API

Jentic publishes the only available OpenAPI specification for Hearthstone API, keeping it validated and agent-ready. The Hearthstone API exposes Blizzard's Hearthstone card catalog as structured JSON covering individual cards, card backs, and master metadata such as classes, sets, races, qualities, types, and factions. Agents can fetch cards by name, browse them by class or set, search by partial name, and pull the full game info block in a single call. The service is hosted on the RapidAPI gateway and is read-only - it does not accept user-generated content or game state.

## For AI agents

Look up Hearthstone cards, card backs, and game metadata by name, class, set, race, quality, type, or faction across 11 read-only endpoints.

## Scope

Does not handle live game state, player accounts, deck submission, or matchmaking - use for static card and metadata lookups only.

## Capabilities

- Retrieve a Hearthstone card by exact name from /cards/{name}
- Search the card pool by partial name match using /cards/search/{name}
- List every card belonging to a given class, set, race, quality, type, or faction
- Pull the full Hearthstone game metadata block (classes, sets, types, factions, qualities, races) from /info
- Enumerate all Hearthstone card backs available in the game via /cardbacks
- Filter card results by collectibility and locale through query parameters on the cards endpoints

## Use cases

### Deck Builder Card Lookup

A community deck-building tool needs to render card images, mana costs, and abilities as users add cards to a deck. The Hearthstone API supplies the canonical card record by name including text, attack, health, cost, and image URLs, so the builder never has to maintain a local card database. Lookups are single GET calls with sub-second latency.

Example prompt: Call GET /cards/Ragnaros%20the%20Firelord and return the card's mana cost, attack, health, and card text

### Class and Set Browsing

A meta-tracking site groups cards by class and set to power filterable browse pages. The /cards/classes/{class} and /cards/sets/{set} endpoints return every card in a given class or expansion in a single response, removing the need for client-side filtering across the full card list.

Example prompt: List every card in the Hearthstone Classic set by calling GET /cards/sets/Classic

### Card Search Autocomplete

An in-browser search box suggests cards as a user types. The /cards/search/{name} endpoint returns all cards whose names contain the supplied substring, making it suitable as an autocomplete backend without needing local indexing.

Example prompt: Search for all Hearthstone cards whose name contains 'dragon' by calling GET /cards/search/dragon

### AI Agent Hearthstone Assistant

A Claude or GPT-based assistant answers player questions about cards, classes, and game mechanics. Through Jentic, the agent searches for the right Hearthstone API operation by intent, loads its schema, and returns structured card data without scraping fan wikis. Integration takes minutes rather than hours of doc reading.

Example prompt: Search Jentic for 'look up a hearthstone card', load the operation schema, and return card data for 'Tirion Fordring'

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /cards | Get all cards |
| GET | /cards/{name} | Get a card by exact name |
| GET | /cards/search/{name} | Search cards by partial name |
| GET | /cards/classes/{class} | List cards by class |
| GET | /cards/sets/{set} | List cards by set |
| GET | /info | Get game metadata for valid filter values |
| GET | /cardbacks | List all card backs |

## Key resources

- **Cards** — Lookup, search, and filter the full Hearthstone card pool by name, class, set, race, quality, type, or faction
- **Card Backs** — List every card back available in Hearthstone
- **Info** — Retrieve the master metadata block listing valid classes, sets, races, types, qualities, and factions

## Why Jentic

- **Setup:** Wiring the Hearthstone API by hand means routing through RapidAPI and sending the X-RapidAPI-Key header on every card lookup. Through Jentic you install once, import the Hearthstone API from the API Directory, store the RapidAPI key once, and your agent calls it.
- **Permission scoping:** The Hearthstone API is read-only, with card and metadata lookups spread across endpoints like /cards, /cards/{name}, and /cards/sets/{set}, so limit the agent to the lookups it needs, such as looking up a card by name. You choose the operations it may call, so anything outside that read-only set is not included unless you add it.
- **Credential handling:** Your RapidAPI key is stored once, encrypted, by your own Jentic One instance and injected as the X-RapidAPI-Key header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'look up a hearthstone card' or 'search cards by name', and Jentic returns the matching operation with its input schema so the agent calls /cards/{name} or /cards/search/{name} directly without browsing the RapidAPI docs.

## Related APIs

- **RAWG Video Games Database API** — RAWG covers video game metadata broadly while Hearthstone API is specific to the card pool
- **Battle.net API** — Battle.net provides player profile and account data across Blizzard titles, complementary to card-pool lookups
- **IGDB API** — IGDB is a general game database - broader than Hearthstone's card-only catalog

## FAQ

### Why is there no official OpenAPI spec for Hearthstone API?

Hearthstone API does not publish an OpenAPI specification of its own. Jentic generates and maintains this spec so that AI agents and developers can call Hearthstone API via structured tooling. It is validated against the live RapidAPI endpoint and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Hearthstone API use?

The API is hosted on RapidAPI and authenticates via the X-RapidAPI-Key header. Through Jentic, the RapidAPI key is held in the encrypted vault and the agent receives scoped access at call time.

### Can I search Hearthstone cards by partial name with this API?

Yes. GET /cards/search/{name} returns every card whose name contains the supplied substring, suitable for autocomplete and fuzzy lookup flows.

### What are the rate limits for the Hearthstone API?

Rate limits are set on the RapidAPI plan attached to your key - the free Basic plan typically allows around 500 requests per month with a hard ceiling on requests per second. Check your RapidAPI dashboard for the exact quota.

### How do I look up a card by name through Jentic?

Run pip install jentic, have the agent search for 'look up a hearthstone card by name', load the GET /cards/{name} operation, and execute it with the card name as the path parameter.

### Does the Hearthstone API include card images?

Yes. Card responses include image URLs for both the standard and gold card art, returned alongside name, mana cost, attack, health, and card text on the /cards endpoints.

### Can I limit what my agent is allowed to do with the Hearthstone API?

Yes. Because you run Jentic One yourself, you decide which of the Hearthstone API's read-only operations your agent may call, so you can grant just a card-by-name lookup with GET /cards/{name} and leave the rest out. The API is entirely read-only, so an agent can never submit decks, change game state, or touch player accounts, but you can still narrow it further to only the endpoints you need, such as GET /cards/search/{name} or GET /cards/sets/{set}. Anything you have not added, including the full /cards listing or the /info metadata block, stays out of the agent's reach.