Cards, sets and stored prices
Wiki home · Practical examples · All endpoints · Exact schemas
Current access: first-party * for this family, except the one-card cheapest-purchase endpoint, which also accepts a separately granted card:purchase:read scope. A customer ASK key does not automatically have the rest of this family. Source/field policy can further restrict output.
Find a card
| Operation | Use |
|---|---|
| GET /v1/cards | Search, filter, sort and page canonical card identities |
| GET /v1/cards/named | Resolve one exact or fuzzy card name |
| GET /v1/cards/by-identifier | Resolve an external card identifier |
| GET /v1/cards/autocomplete | Name suggestions for a typeahead |
| POST /v1/cards/resolve | Resolve a batch of names |
| GET /v1/cards/{oracle_id} | Read one Oracle identity |
| GET /v1/cards/{oracle_id}/printings | Printings of an Oracle identity |
| GET /v1/cards/{oracle_id}/parts | Related card parts |
| GET /v1/printings/{printing_id} | One exact printing |
| GET /v1/printings/by-identifier | Printing by external identifier |
The Oracle ID identifies a card identity; the printing ID identifies a specific physical/digital edition. Use the latter when the edition, art or price matters. Search supports fields such as name/q, format and legality, colors/color identity, mana value, type, keyword, set, rarity, game, sort/order, as_of, fields/include, and limit/cursor. The OpenAPI parameters specify accepted values and combinations. Do not assume a fuzzy match is an exact card identity.
curl -sS 'https://api.chaosdraft.com/v1/cards?name=Llanowar%20Elves&limit=10' \
-H "Authorization: Bearer $CHAOSDRAFT_FIRST_PARTY_KEY"Sets
| Operation | Use |
|---|---|
| GET /v1/sets | Search and page sets |
| GET /v1/sets/{code} | Read one set |
| GET /v1/sets/{code}/cards | Cards/printings in a set |
GET /v1/sets supports q, type, released_after/released_before, as_of and pagination. Set codes are path identifiers, not display names. Check each result's provenance and coverage when a date matters.
Prices and purchase links
| Operation | Use |
|---|---|
| GET /v1/prices/printings/{printing_id} | Stored observations for one exact printing |
| GET /v1/prices/cards/{oracle_id} | Stored prices across a card's printings |
| GET /v1/cards/{oracle_id}/cheapest-purchase | One cheapest recent, in-stock Card Kingdom NM/nonfoil retail observation and policy-gated product link/image |
Prices are stored observations, not a fresh checkout quote. The cheapest-purchase route needs card:purchase:read on a scoped server key; ask_ai alone is insufficient. A customer account's configured Card Kingdom affiliate code may be included in its buy_url. Show observation time, currency, condition, finish, and coverage beside any price; handle no quote. Product URL and card image have separate source-policy gates.
Sources and service status
GET /v1/sources lists the API's sources and their attribution. GET /v1/status reports source/ingestion status. GET /health checks the process and GET /ready checks readiness; only those last two are public. Include the attribution returned for any source-derived information you display.