Docs
API referenceCards

Search cards

Cursor-paginated search. Zero results is a 200, not a 404. Filters combine with AND across parameters. Within one parameter, `set`, `rarity` and `category` match any of the values given, while `color` and `type` require all of them. `rarity`, `color` and `type` have a vocabulary that belongs to a single game: send `game` with them, or the answer is narrower than it looks and costs a scan of every other game.

Cursor-paginated search. Zero results is a 200, not a 404.

Filters combine with AND across parameters. Within one parameter, set, rarity and category match any of the values given, while color and type require all of them.

rarity, color and type have a vocabulary that belongs to a single game: send game with them, or the answer is narrower than it looks and costs a scan of every other game.

Authorization

ApiKey
headerAuthorizationBearer <rar_live_*>

Send Authorization: Bearer rar_live_..., or use rar_test_... for a test key. Both lanes currently read the same catalogue. Without a key you stay in the anonymous lane: 30 requests/minute and 1,000/day, against 60/minute per key and 2,000/day per organization with one on the Free plan. Sending a key that is malformed, revoked or unknown is a 401; sending none is not.

Query Parameters

q?string

Query language, Scryfall syntax. Terms separated by spaces must all match; or asks for alternatives and parentheses group them.

TermMeaning
luffyfull-text over the card's name and rules text
"straw hat"the same, as an adjacent phrase
name:luffyfull-text over the name alone. A bare luffy also returns cards that mention Luffy in their rules text. Quote phrases, as in name:"bond en avant"
luffy*the last word is a prefix rather than a whole word. This is the form used for autocomplete. Works on a bare term and on name:, and on a phrase too: name:"bond en av"*
set:OP01 rarity:sr category:leader color:red type:Navy game:one_piecethe field equals the value
power>=5000numeric comparison on a game attribute: >= <= > < = !=
-color:rednegates any term. It can also negate a group: -(color:red or color:green)
color:red or color:greeneither one. or, OR, and, AND are all accepted
luffy (set:OP01 or set:ST01)parentheses group, and nest

A value with spaces is quoted: type:"Straw Hat Crew". To search for the word or itself, quote it: "or".

* is a prefix wildcard and only that. It may appear only at the end of a search term. lu*fy, *luffy and "luffy*" return 400. A wildcard on a field term such as set:OP* also returns 400 because fields compare whole values and the wildcard would otherwise produce an empty 200 response. Suffix and infix wildcards are unsupported.

and binds tighter than or, as it does in Lucene: set:OP01 luffy or zoro is (set:OP01 luffy) or zoro, not set:OP01 (luffy or zoro). Parentheses when in doubt.

Repeating a field means and. Therefore set:OP01 set:OP02 matches nothing because a card has one set. set:OP01 or set:OP02 asks for either, and the set parameter does the same.

Attribute names come from the games themselves; a name no registered game publishes is a 400 rather than an empty page. Their vocabulary is per game, so pair a numeric term with game:.

An or without another narrowing term is the slowest read in this API. It takes 10 ms, compared with 0.13 ms after adding game:, because the catalogue contains every game. Pair a broad or with game:.

A query accepts at most 20 terms, 4 levels of parentheses and 512 characters. Terms are counted as leaves, including terms inside parentheses, so nesting does not bypass the term limit. Exceeding any limit returns 400. The server never truncates a query because truncation would change its meaning.

Match^[^\u0000-\u001f\u007f-\u009f]*[^\u0000-\u001f\u007f-\u009f\s][^\u0000-\u001f\u007f-\u009f]*$
Lengthlength <= 512
lang?string

Language of the print. Never negotiated through Accept-Language.

Match^[^\u0000-\u001f\u007f-\u009f]*[^\u0000-\u001f\u007f-\u009f\s][^\u0000-\u001f\u007f-\u009f]*$
Default"en"
set?array<>

Set code, case-insensitive. Repeatable: ?set=OP01&set=OP02 matches either, because a card has one set.

Itemsitems <= 10
rarity?array<>

Rarity code, case-insensitive. Repeated values match any value. Each game has its own vocabulary, such as sr on One Piece and legendary on Star Wars Unlimited. Send game with this parameter.

Itemsitems <= 10
category?array<>

Card category: character, leader, event, stage, unit, base, upgrade, token. Case-insensitive, repeatable, matches any of the values. The vocabulary is per game.

Itemsitems <= 10
color?array<>

Colour, case-insensitive. Repeated values must all be present: ?color=red&color=green requires both red and green. Each game has its own vocabulary, such as red on One Piece and heroism on Star Wars Unlimited.

Itemsitems <= 10
type?array<>

Trait as published in the card's types, such as Straw Hat Crew or Trooper. Matching is exact and case-sensitive because publishers define traits as free text. Repeated values must all be present.

Itemsitems <= 10
order?string

Sort key. number, the default, sorts by collector number. name sorts by card name and can be used for browsing, autocomplete and prefix searches such as luffy*.

The card id provides a final tie-breaker for both orderings, so pagination does not repeat or skip rows. A cursor is valid only for its original ordering. Changing order during pagination returns cursor_order_mismatch. Restart without a cursor.

Default"number"
Value in"number""name"
cursor?string

Opaque cursor returned in next_cursor. Do not build it by hand.

Lengthlength <= 512
limit?integer

Items per page. Safe integers are clamped to 1-100, not rejected.

Range-9007199254740991 <= value <= 9007199254740991
Default20
game?string

Game code, as returned in a card's game.

Match^[^\u0000-\u001f\u007f-\u009f]*[^\u0000-\u001f\u007f-\u009f\s][^\u0000-\u001f\u007f-\u009f]*$

Response Body

A page of results. Zero results = 200 with data: [].

application/json
  1. response

List envelope. Zero results is a 200 with data: [], never a 404.

object*string
data*array<>
has_more*boolean

The only end-of-pagination signal.

next_cursor*|

Present and non-null if and only if has_more is true.

total?|

An estimate. Never use it as a termination signal.

warnings?array<string>

Non-fatal channel: query terms that were ignored.

Example Request
cURL
curl -X GET 'https://api.rarity.dev/v1/cards' \  -A 'my-app/1.0 (you@example.com)'
Example Response
{  "object": "list",  "data": [    {      "object": "card",      "id": "string",      "oracle_id": "string",      "illustration_id": "string",      "external_ids": {        "tcgplayer": 610429,        "cardmarket": 801001      },      "lang": "string",      "layout": "string",      "uri": "http://example.com",      "livemode": true,      "updated_at": "2019-08-24T14:15:22Z",      "name": "string",      "text": "string",      "colors": [        "string"      ],      "types": [        "string"      ],      "legalities": [        {          "format": "string",          "status": "string",          "since": "string"        }      ],      "faces": [        {          "face_type": "string",          "name": "string",          "text": "string",          "image": "http://example.com",          "illustration_id": "string",          "attributes": {            "property1": null,            "property2": null          }        }      ],      "printed_name": "リザードンex",      "set": "string",      "collector_number": "string",      "rarity": "sr",      "category": "string",      "illustrator": "string",      "products": [        "string"      ],      "variant": {        "type": "string",        "of": "string",        "treatment": [          "string"        ]      },      "image": "http://example.com",      "image_status": "missing",      "prices": {        "cardmarket": {          "currency": "eur",          "updated_at": "2019-08-24T14:15:22Z",          "finishes": {            "property1": {              "trend": -9007199254740991,              "avg": -9007199254740991,              "low": -9007199254740991,              "avg1": -9007199254740991,              "avg7": -9007199254740991,              "avg30": -9007199254740991            },            "property2": {              "trend": -9007199254740991,              "avg": -9007199254740991,              "low": -9007199254740991,              "avg1": -9007199254740991,              "avg7": -9007199254740991,              "avg30": -9007199254740991            }          }        },        "tcgplayer": {          "currency": "usd",          "updated_at": "2019-08-24T14:15:22Z",          "finishes": {            "property1": {              "market": -9007199254740991,              "low": -9007199254740991,              "mid": -9007199254740991,              "high": -9007199254740991,              "direct_low": -9007199254740991            },            "property2": {              "market": -9007199254740991,              "low": -9007199254740991,              "mid": -9007199254740991,              "high": -9007199254740991,              "direct_low": -9007199254740991            }          }        },        "pricecharting": {          "currency": "usd",          "updated_at": "2019-08-24T14:15:22Z",          "grades": {            "1": -9007199254740991,            "2": -9007199254740991,            "3": -9007199254740991,            "4": -9007199254740991,            "5": -9007199254740991,            "6": -9007199254740991,            "7": -9007199254740991,            "8": -9007199254740991,            "9": -9007199254740991,            "ungraded": -9007199254740991,            "9.5": -9007199254740991,            "psa_10": -9007199254740991,            "bgs_10": -9007199254740991,            "cgc_10": -9007199254740991,            "sgc_10": -9007199254740991,            "cgc_10_pristine": -9007199254740991,            "bgs_10_black": -9007199254740991,            "tag_10": -9007199254740991,            "ace_10": -9007199254740991          }        }      },      "source_url": "http://example.com",      "game": "dragon_ball_fusion_world",      "attributes": {        "property1": null,        "property2": null,        "counter": "string",        "attributes": [          "string"        ],        "block": "string",        "trigger": "string",        "upgrade_power": "string",        "upgrade_hp": "string",        "subtitle": "string",        "unique": true,        "arenas": [          "string"        ],        "keywords": [          "string"        ],        "unit_type": "string",        "deploy_box": "string",        "epic_action": "string",        "dmg": "string",        "life": "string",        "hp": "string",        "type": "string",        "stage": "string",        "attacks": [          {            "cost": "string",            "name": "string",            "damage": "string",            "text": "string"          }        ],        "abilities": [          {            "kind": "string",            "name": "string",            "text": "string"          }        ],        "weakness": "string",        "resistance": "string",        "retreat_cost": "string",        "card_type": "string",        "colors": [          "string"        ],        "cost": "string",        "specified_cost": "string",        "power": "string",        "combo_power": "string",        "traits": [          "string"        ]      }    }  ],  "total": -9007199254740991,  "warnings": [    "string"  ],  "has_more": true,  "next_cursor": "string"}

Retrieve a card by id GET

Lookup by opaque id. With `?format=image` it answers 302 towards the CDN.

Suggest prints for free text GET

Autocomplete over prints: the prints that best match what the user typed, best first. It tolerates a misspelled name, reads `printed_name`, and understands the collector number as the card prints it. Words can be combined, as in `pikachu 58/102` or `charizard base`: a print that more words match ranks higher. Prints with the same score are ordered by `id`, so the same request always returns the same body. With several games, prints that match more words in full come first, from any game. Among prints that match as many words in full, the games take turns: the best print of each game, then the second of each game, and so on. A full match in one game therefore ranks above a misspelling in another. The response is the list envelope of `GET /v1/cards` with whole cards, and never has a next page: `has_more` is always false. Use `GET /v1/cards` to page through a catalogue. An unknown query parameter returns 400 (`unknown_parameter`).