Cards

All card endpoints require your API key in the X-API-Key header.

Search Cards

GET /cards/search?game={slug}&name={query}&page={n}&limit={n}

Search cards by name within a game. The search is case-insensitive and supports partial matching.

Parameter	Type	Required	Default	Description
game	string	yes	—	Game slug (e.g. `riftbound`, `mtg`)
name	string	yes	—	Card name to search for
page	number	no	1	Page number
limit	number	no	20	Results per page (min 1, max 100)

Example:

curl "https://tcg-api-production-5148.up.railway.app/cards/search?game=riftbound&name=dragon" \
  -H "X-API-Key: tcg_your_key_here"

Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "gameId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "externalId": "847458",
      "name": "Fire Dragon",
      "categoryId": "10",
      "expansionId": "100",
      "price": {
        "sell": 5.99,
        "low": 3.50,
        "trend": 4.75,
        "avg1": 5.50,
        "avg7": 5.20,
        "avg30": 4.90,
        "foilSell": 2.87,
        "foilLow": 0.95,
        "foilTrend": 2.89,
        "updatedAt": "2026-04-07T04:00:00.000Z"
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 4,
    "totalPages": 1
  }
}

Get Card by ID

GET /cards/{game}/{externalId}

Look up a single card by its Cardmarket product ID (externalId).

Parameter	Type	Required	Description
game	path	yes	Game slug (e.g. `riftbound`)
externalId	path	yes	Cardmarket product ID

Example:

curl "https://tcg-api-production-5148.up.railway.app/cards/riftbound/847458" \
  -H "X-API-Key: tcg_your_key_here"

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "gameId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalId": "847458",
  "name": "Fire Dragon",
  "categoryId": "10",
  "expansionId": "100",
  "price": {
    "sell": 5.99,
    "low": 3.50,
    "trend": 4.75,
    "avg1": 5.50,
    "avg7": 5.20,
    "avg30": 4.90,
    "foilSell": 2.87,
    "foilLow": 0.95,
    "foilTrend": 2.89,
    "updatedAt": "2026-04-07T04:00:00.000Z"
  }
}

Returns 404 Not Found if the card does not exist.

Batch Lookup

POST /cards/batch

Look up multiple cards at once using their Cardmarket product IDs.

Body:

{
  "game": "riftbound",
  "cardIds": ["847458", "847412"]
}

Field	Type	Required	Description
game	string	yes	Game slug
cardIds	string[]	yes	Array of Cardmarket product IDs (min 1)

Batch Size Limits

Plan	Max cards per request
Free	10
Premium	25
Pro	50

Exceeding your plan's limit returns a 400 Bad Request.

Example:

curl -X POST "https://tcg-api-production-5148.up.railway.app/cards/batch" \
  -H "X-API-Key: tcg_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"game": "riftbound", "cardIds": ["847458", "847412"]}'

Response:

Returns an array of card objects (same structure as search, without pagination). Cards not found are silently omitted.

Card Object Reference

Field	Type	Description
id	string	Card UUID
gameId	string	UUID of the game
externalId	string	Cardmarket product ID
name	string	Card name
categoryId	string?	Cardmarket category ID
expansionId	string?	Cardmarket expansion/set ID
price	object?	Price data (null if not yet synced)

Price Object Reference

Field	Type	Description
sell	number?	Average sell price
low	number?	Lowest available price
trend	number?	Price trend
avg1	number?	1-day average
avg7	number?	7-day average
avg30	number?	30-day average
foilSell	number?	Foil average sell price
foilLow	number?	Foil lowest price
foilTrend	number?	Foil price trend
updatedAt	string	Last price update (ISO 8601)