Public API

A free, developer-friendly REST API exposing the full Hearthstone Battlegrounds card database. Built for bots, stat trackers, wiki templates, Discord integrations, and anyone who wants structured card data without scraping HTML.

Quick start

Zero setup. Paste into your terminal and run:

curl https://hsbgcards.studentapp.space/api/v1/cards/deathwing

Accepts numeric id (60347), slug (60347-deathwing), or normalized name (deathwing, Dr. Boom).

Card images

Every card has an image endpoint that 302-redirects to a static file. Zero server-side image processing - the redirect target is cached for 24 hours, and any HTTP client that follows redirects (browsers, curl -L, fetch) will end up downloading the file directly.

# Default: medium webp (~300px, ~30-50KB)
curl -L https://hsbgcards.studentapp.space/api/v1/cards/morchie/image -o morchie.webp

# Small webp (~150px, ~10-15KB) - perfect for grids + list views
curl -L "https://hsbgcards.studentapp.space/api/v1/cards/morchie/image?size=small" -o morchie-small.webp

# Full PNG (512x673) - best for high-res rendering
curl -L "https://hsbgcards.studentapp.space/api/v1/cards/morchie/image?size=full&format=png" -o morchie.png

# Golden variant (falls back to non-golden if a card has no golden art,
# and sets an X-Image-Fallback: no-golden response header)
curl -L "https://hsbgcards.studentapp.space/api/v1/cards/deathwing/image?golden=true" -o deathwing-gold.webp

Query parameters:

• size: small (150px), medium (300px, default), full (512px)
• format: webp (default), png (only supported with size=full)
• golden: true to request the golden variant (auto-falls back to non-golden with an X-Image-Fallback: no-golden header if a card has no golden art)

Use it directly in HTML: <img src=".../api/v1/cards/morchie/image?size=small">. The browser will transparently follow the 302 and cache the result.

What it does

• Lookup any card by id, slug, or normalized name
• Filter + paginate the full catalog (type, tier, tribe, keywords, duos/solos)
• Batch up to 100 cards per request - counts as 1 against your rate limit
• Single-field extraction with friendly aliases (atk, hp, text_gold) in plain-text or JSON
• Resolved related cards (parent, children, companion, hero skins, text mentions)
• Image redirects to multiple sizes and formats
• Time travel: fetch a card's state as it existed at a historical patch
• Full patch notes data for every tracked patch

Rate limits

• Without a key: 120 requests per minute, per IP. No signup, no catch.
• With a key: configurable higher limits (default 600/min). Request one via any contact method below.

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so your client can self-regulate.

Request an API key

Need a higher tier? Drop me a line on any of these - tell me what you're building and I'll get you set up:

Once a key is issued, pass it via the X-API-Key header or ?api_key= query param. The API reloads keys from disk within 60s - no restart required on my end.

Versioning & stability

/api/v1/* is a frozen contract. Additive changes (new endpoints, new fields, new query params) ship without a bump; breaking changes will ship as /api/v2/* with v1 kept alive for a generous deprecation window. The internal /api/cards endpoint that the website uses is not part of the public contract - don't build against it.

Full reference below

The full interactive reference is rendered below. Every endpoint documented with request params, response schemas, and a "Try it" panel that fires real requests against the live API. Scroll down or jump straight in: