Skip to main content
GET
List cards
Cards come back in catalog order, by expansion then collector number, paged by cursor. This is how you walk the whole catalog: keep calling with the next_cursor you were handed until it comes back null. Pass expansion_id to walk one expansion instead. It is a filter, not a lookup, so an id that matches nothing is an empty page rather than a 404. Pass q to search by name or collector number. Rows then come back best-match first, each carrying a score, and the cursor keeps working exactly as it does without it. The two compose: ?q=charizard&expansion_id=base1 searches inside one expansion. A name resolves to candidates, not to one id. Dozens of cards are named exactly “Charizard”, so they all score identically and ?q=charizard hands back a list to choose from rather than an answer. Where rows tie at the top score the tie-break is id order, not relevance, so the first row is the lowest id among equals and not the best match. Show the candidates and let someone pick, or narrow with expansion_id. Ranking is by similarity, so a misspelling still finds its card. Rows here are summaries, not full card objects. They carry enough to render a list. Fetch the card when someone opens one.

​
Attaching more to each row

include takes a comma-separated list of variants, metadata, change, or any combination. variants is the same array the card object carries, so one decoder covers both endpoints. With both includes, a row carries every field GET /v1/cards/{id} serves and number_normalized besides. Each include is absent entirely unless you ask for it. The key is not null and not an empty array. A card the catalog holds no printings for gets [] once you do ask. A value the endpoint does not recognise is dropped rather than refused. change stays absent even when asked for if the card has no computed mover row, and it reports the card’s headline printing, not necessarily the one that moved most. See Change on the card object, and List biggest gainers and losers for the leaderboard this is drawn from. This is how you build a local catalog. At limit=200 the roughly 21,000-card catalog is about 105 requests instead of one per card.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
limit
integer
default:50

How many rows to return. Defaults to 50 and stops at 200; a larger value is clamped, not rejected.

Required range: 1 <= x <= 200
​
cursor
string

The next_cursor from the previous page. Omit it for the first page. A cursor this endpoint did not issue is ignored, and you get the first page back.

​
expansion_id
string

Narrow the list to one expansion. An id that matches nothing is an empty page, not a 404.

​
q
string

Search cards by name or collector number. Ranked best-match first, every row carrying its score, and the cursor keeps working.

Minimum string length: 1
​
include
string

Comma-separated extras to attach to every row: variants, metadata, change, or any combination. A value that is not one of those is dropped rather than rejected.

Response

Card list

​
data
object
required
​
error
object | null
required