Scryfall API Overview

Scryfall provides a REST API for combing through our database of cards. The API exposes all of the information available on the regular site in easy-to-consume formats.

If you build something neat with our API, we want to hear about it! Send us a note on Twitter. 😘

Endpoint Details

The API is available at https://api.scryfall.com

API requests are only served over HTTPS, using TLS 1.0, 1.1 and 1.2. Requests will not be honored over plaintext HTTP.

The API uses UTF-8 character encoding for all responses. Many fields will include characters that are not in the ASCII range.

Authentication and Rate Limits

The Scryfall API does not require any authentication: all methods are currently public.

We kindly request that you insert 50 – 100 milliseconds of delay between the requests you send to the server. (i.e., 10 requests per second on average).

Submitting excessive requests to the server may result in a HTTP 429 Too Many Requests status code. Continuing to overload the API after this point may result in a temporary or permanent ban of your IP address.

👉 Tip: The best way to request bulk information for a whole set, or any other large group of cards is to use the /cards/search API method and paginate over the results.

Colors

Whenever the API presents set of Magic colors, the field will be an array that uses the uppercase, single character abbreviation for that color. For example, ["R","G"] represents something that is both red and green. Colorless sources are denoted with an empty array [ ].

Mana Costs and Card Symbology

Whenever the API presents mana costs and other card symbols, it does so using the official plaintext notation for that symbol set forth in the Comprehensive Rules. For example, “{2/W}, {T}” is written as {2/W}, {T}.

Type: List

A List object represents a requested sequence of other objects (Cards, Sets, etc). List objects may be paginated, and also include information about issues raised when generating the list.

List objects have the following fields:

  • data: An array of the requested objects, in a specific order

  • has_more: True if there is a page beyond the current page. False if there are no more pages or there is only one page.

  • next_page: If there is a page beyond this page of results, this field will contain a full API URI to that page. You may submit a HTTP GET request to that URI to continue paginating forward on this List. Can be null.

  • total_cards: If this is a list of Card objects, this field will contain the total number of cards found across all pages. Can be null.

  • warnings: An array of human-readable warnings issued when generating this list. Warnings are non-fatal issues that the API discovered with your input. In general, they indicate that the List will not contain the all of the information you requested. You should fix the warnings and re-submit your request.

Type: Card

A Card object represents a single distinct Magic: The Gathering card. Cards contain both gameplay information and print information.

Gameplay information is everything that players playing a Magic game need to know about a card. This information does not change between different reprints of a card.

Print information is everything unique to a specific card re/print.

Cards contain the following gameplay fields:

  • name: The English name of the card

  • mana_cost: The mana cost of this card. Can be null, which indicates no cost at all. Note that {0} and null are not the same cost, per the game rules.

  • converted_mana_cost: The converted mana cost of this card. Note that this is not always an integer thanks to cards from Un-sets.

  • type_line: The line on the card face that contains its supertypes, card types, and subtypes. Can be null for multi-faced cards.

  • oracle_text: The official Oracle text for this card. As Magic rules have changed over the years, Wizards has issued errata to re-word and clarify the text on older cards. This field will always contain the most up-to-date wording for this card’s text box. Can be null for multi-faced cards.

  • power/toughness: This card’s power and toughness, if any. Note that these fields will be strings because some cards have noninteger values like 1+*. Can be null.

  • loyalty: This card’s starting loyalty value, if any, as a string. Can be null.

  • hand_modifier/life_modifier: This card’s hand and life modifiers, if it is a Vanguard card. This value will be a string containing a delta, like +0, -1, or +1.

  • colors: The colors that this card is. A card’s colors are determined by it’s mana cost, color indicator, or abilities in its text box.

  • color_identity: The color identity of this card. A card’s color identity is determined by its color indicator, abilities, or any colored mana symbols on the face of the card.

  • layout: The face layout for this card. The possible values are:

    • normal: The standard one-faced card
    • split: cards that are part of a split-faced card
    • flip: cards that invert vertically with the flip keyword
    • transform: cards with a front/back face that transform
    • meld: cards with a front/back face that meld together
    • leveler: cards with Level Up
    • plane: Plane-type cards
    • phenomenon: Phenomenon-type cards
    • scheme: Scheme-type cards
    • vanguard: Vanguard-type cards
  • card_faces: If this is a split or flip card, this property will be an array of objects representing the distinct faces of the card. The objects will have the following fields:

    • name: The name of this particular face
    • mana_cost: The mana cost for this face. Can be null.
    • type: The type line for this face.
    • oracle_text: The Oracle text for this face. Can be null.
    • power: The power of this face, as a string. Can be null.
    • toughness: The toughness of this face, as a string. Can be null.
  • legalities: An object field where the keys are play formats and the values are the legal status of this card in that format.

    • The current supported formats are: standard, modern, legacy, vintage, commander, pauper, frontier, penny, duel, 1v1, and future.
    • The legality status may be legal, not_legal, restricted, or banned.
  • reserved: True if this card name is on the Reserved List

Cards also contain the following print-specific fields:

  • id: The unique UUID for this print in Scryfall’s database.

  • multiverse_id: The Gatherer multiverse ID for this print. Can be null, not all cards have a multiverse ID.

  • mtgo_id: The Magic Online ID for this print. Can be null, not all cards have a Magic Online ID.

  • set: The three or four-letter set code for this print.

  • set_name: A copy of the set name for this print.

  • collector_number: The collector number for this card in its set. Note that many older sets did not have collector numbers at all, so Scryfall has invented an arbitrary number for those cards. This field is a string because card numbers can contain letters and characters. Can be also null, not all cards have a collector numbers yet.

  • all_parts: If this card transforms or melds, this property will be an array of objects representing the card on the flipside and/or the other meld parts of the card. The array will include an object for the current card as well. The objects will have the following fields:

    • id: the Scryfall ID of the card
    • name: The English name of the card
    • uri: A Scryfall API URI where you can retrieve a full Card object for this face
  • rarity: The rarity of this card when it was printed.

    • Possible values are common, uncommon, rare, and mythic.
  • digital: True if this is a digital-only card reprint for Magic Online.

  • flavor_text: The italicized flavor text for this card, if any.

  • artist: The name of the person who illustrated this card.

  • frame: The Magic card frame used on face of this card, possible values are:

    • 1993: The original Magic card frame, starting from Limited Edition Alpha.
    • 2001: The “modern” Magic card frame, introduced in Eighth Edition and Mirrodin block.
    • 2015: The holofoil-stamp Magic card frame, introduced in Magic 2015.
    • future: The frame used on cards from the future
  • border: The color of this card’s border.

    • Possible values are black, white, silver, and gold.
  • timeshifted: True if this print is timeshifted from history

  • colorshifted: True if this print is from an alternate reality

  • futureshifted: True if this print is from the future

  • usd: The average price of this physical/paper card in decimal United States dollars. Can be null, not all cards have price information.

  • eur: The average price of this physical/paper card in decimal Euros. Can be null, not all cards have price information.

  • tix: The average price of this card at Magic Online resellers, expressed as decimal Event Tickets. Can be null, not all cards have price information.

  • scryfall_uri: A URI to this card’s permapage on scryfall.com

  • image_uri: A URI to a JPEG image of this card. Can be null for unavailable imagery.

  • related_uris: An object field that contains useful links for getting more information about this card. Not all cards have every link.

  • purchase_uris: An object field that contains links for buying this card. Not all cards have every link.

Type: Set

A Set object represents a group of related Magic: The Gathering cards. All Card objects on Scryfall belong to exactly one set.

Due to Magic’s long and complicated history, Scryfall includes many un-official sets as a way to group promotional or outlier cards together. Such sets will have a four-letter set code that begins with p, such as pcel. Official sets have a three-letter set code, such as zen.

Set objects have the following fields:

  • code: The three or four-letter set code for this set.

  • name: The English name of this set

  • search_uri: A Scryfall API URI that you can request to begin paginating over the cards in this set.

  • set_type: The kind of set that this is. Possible values are:

    • core: A yearly Magic core set (Tenth Edition, etc)
    • expansion: A rotational expansion set in a block (Zendikar, etc)
    • masters: A reprint set that contains no new cards (Modern Masters, etc)
    • masterpiece: Masterpiece Series premium foil cards
    • from_the_vault: From the Vault gift sets
    • premium_deck: Premium Deck Series decks
    • duel_deck: Duel Decks
    • commander: Commander preconstructed decks
    • planechase: Planechase sets
    • conspiracy: Conspiracy sets
    • archenemy: Archenemy sets
    • vanguard: Vanguard card sets
    • funny: A funny un-set or set with funny promos (Unglued, Happy Holidays, etc)
    • starter: A starter/introductory set (Portal, etc)
    • box: A gift box set
    • promo: A set that contains purely promotional cards

Type: Catalog

A Catalog object contains an array of Magic datapoints. Catalog objects are provided by the API as aids for building other Magic software and understanding possible values for a field on Card objects.

Catalog objects have the following fields:

  • data: The datapoints. Always an array of strings.

Type: CardSymbol

A CardSymbol object represents an illustrated symbol that may appear in card’s mana cost or Oracle text. Symbols are based on the notation used in the Comprehensive Rules.

CardSymbol objects have the following fields:

  • symbol: The plaintext symbol. Often surrounded with curly braces { }. Note that not all symbols are ASCII text (for example, {∞}).

  • loose_variant: An alternate version of this symbol, if it is possible to write it without curly braces.

  • english: An English snippet that describes this symbol. Appropriate for use in alt text or other accessible communication formats.

  • transposable: True if it is possible to write this symbol “backwards”. For example, the official symbol {U/P} is sometimes written as {P/U} or {P\U} when players are chatting. Note that Scryfall never writes symbols backwards in other responses. This field is provided for informational purposes.

  • represents_mana: True if this is a mana symbol.

  • converted_mana_cost: A decimal number representing this symbol’s converted mana cost. Note that mana symbols from Un-sets can have fractional converted mana costs.

  • colors: An array of colors that this symbol represents.

  • appears_in_mana_costs: True if this symbol appears in a mana cost on any Magic card. For example {20} has this field set to false because {20} only appears in Oracle text, not mana costs.

  • funny: True if this symbol is only used on funny cards or Un-cards.

Type: Error

An Error object represents a failure to find information or understand the input you provided to the API. Error objects are always transmitted with the appropriate 4XX or 5XX HTTP status code.

Error objects have the following fields:

  • status: An integer HTTP status code for this error.

  • code: A computer-friendly string representing the appropriate HTTP status code.

  • type: A computer-friendly string that provides additional context for the main error. For example, an endpoint many generate HTTP 404 errors for different kinds of input. This field will provide a label for the specific kind of 404 failure, such as ambiguous. Can be null.

  • details: A human-readable reason for this error.

  • warnings: If your input also generated non-failure warnings, they will be provided as human-readable strings in this array. Can be null.

Disclaimer

The Scryfall API is provided AS IS, on an AS AVAILABLE basis. We make no guarantees about server uptime or the accuracy of any information provided.

The API may include information about the price of a card. Absolutely no guarantees are provided for this information. See stores for final prices.

The API may include information about the tournament legality of a card. Absolutely no guarantees are provided for this information. Please contact a local DCI Judge or Wizards of the Coast customer service for help with evaluating your deck for sanctioned events.

The literal and graphical information presented on this site about Magic: The Gathering, including card images, the mana symbols, and Oracle text, is copyright Wizards of the Coast, a subsidiary of Hasbro, Inc. This website and service is not produced by, endorsed by, supported by, or affiliated with Wizards of the Coast.