Cards API

Query the DeckSense card database. Returns card_id, name, image_url, and full card details.

Endpoints

GET /api/cards/detail/{card_id}

Full detailed info for a single card.

• GET /api/cards/detail/base1-1 — Card by ID

GET /api/cards/search

Search returns card_id, name, image_url, is_legal_now, legality_status, supertype. Use detail endpoint when user selects for full info (attacks, abilities, copy_stats).

Param	Type	Description
name	string	Substring search (required)
set_id	string	Filter by set
supertype	string	Pokémon, Trainer, or Energy
legal	1/true/yes	Only legal cards
limit	int	Max results (default 20, max 100)
offset	int	Pagination offset

• GET /api/cards/search?name=Pikachu
• GET /api/cards/search?name=Charizard&legal=1

GET /api/cards/hot

Full card info for top 150 most used cards. Optimized for frequent calls; rebuilds cache if stale.

• GET /api/cards/hot — Returns cards + cache_updated_at, rebuild_triggered
• GET /api/cards/hot?refresh=1 — Force async rebuild

GET /api/cards/query

Batch fetch and filter cards.

Param	Type	Description
ids	string	Comma-separated card IDs. Max 500.
limit	int	Max results (default 50, max 500)
offset	int	Pagination offset
set_id	string	Filter by set
supertype	string	Pokémon, Trainer, or Energy
legal	1/true/yes	Only legal cards
name	string	Substring search

• GET /api/cards/query?ids=base1-1,base1-2
• GET /api/cards/query?name=Charizard

Copy stats (1–4 only)

When built (weekly cron), cards include copy_stats: % of decks that use the card running 1, 2, 3, or 4+ copies. pct_1 + pct_2 + pct_3 + pct_4 = 100.

{
  "copy_stats": {
    "pct_1": 5.2,
    "pct_2": 82.3,
    "pct_3": 0,
    "pct_4": 0,
    "total_decks": 491959,
    "decks_with_card": 1247
  }
}

Response format

total is the number of rows matching the query in the live cards table (pagination total), not a fixed constant. After importing a new JSON catalog, it should match the imported row count.

{
  "cards": [...],
  "count": 3,
  "total": <number>
}