Cards

Each field available on a Magic: The Gathering card is described below with its field name and corresponding data type.

id <string>

The unique identifier for the card.

name <string>

The name of the card.

flavor_name <string>

The promotional card name printed above the true card name on special cards that has no game function.
Example, "Mechagodzilla, Battle Fortress" while the card is functionally "Hangarback Walker."

flavor_text <string>

The italicized text found below the rules text that has no game function.

supertypes <array of strings>

The supertypes found before the em dash (e.g., "Legendary", "Basic", "Snow")

subtypes <array of strings>

The subtypes found after the em dash (e.g., "Elf", "Demon", "Cat").

types <array of strings>

The types of the card (e.g., "Artifact", "Creature", "Sorcery").

type <string>

The full type, including any supertypes and types as printed on the card.

number <string>

The number of the card.

color_identity <array of strings>

A list of all the colors found in mana_cost, color_indicator, and rules properties.

color_indicator <array of strings>

A list of all the colors in the color indicator. This is the symbol prefixed to a card's types.

colors <array of strings>

A list of all the colors in mana_cost and color_indicator properties.
Some cards may not have values, such as cards with "Devoid" in its text.

mana_cost <string>

The mana cost of the card wrapped in curly brackets for each mana symbol value.
For example, {2}{B} means 2 colorless and 1 black mana. {R}{W} would mean Red and White.

mana_value <number>

The mana value of a card. If it costs 3 mana to play, the mana_value is 3.

power <string>

The power of the card

toughness <string>

The toughness of the card

loyalty <string>

The starting loyalty of the card (for Planeswalkers only)

rules <array of strings>

The various rules of the card describing the effects and abilities.

rarity <string>

The rarity of the card (e.g., "Common", "Uncommon", "Rare", "Mythic")

artist <string>

The artist of the card.

keywords <array of strings>

A list of keywords found on the card (e.g., "Enchant", "Vigilance", "Flying")

layout <string>

The layout of the card (e.g., "adventure", "aftermath", "art_series", "augment", "case", "class", "double_faced_token", "emblem", "flip", "host", "leveler", "meld", "modal_dfc", "mutate", "normal", "planar", "prototype", "reversible_card", "saga", "scheme", "split", "token", "transform", "vanguard")

is_online_only <boolean>

If the card is only available in online play, such as MTGO or Arena.

faces <array of maps>

If the card has multiple faces (such as transform cards or split cards),
each face may have its own name, power, toughness, etc.

Refer to the field specific docs for descriptions

• name <string>
• flavor_name <string>
• flavor_text <string>
• supertypes <array of strings>
• subtypes <array of strings>
• types <array of strings>
• color_identity <array of strings>
• color_indicator <array of strings>
• colors <array of strings>
• mana_cost <string>
• mana_value <number>
• power <string>
• toughness <string>
• loyalty <string>
• rules <array of strings>

images <array of maps>

Contains URLs for the card's images in various sizes.

• type <string>: The type of image (e.g., "front", "back").
• small <string>: The URL of the small image.
• medium <string>: The URL of the medium image.
• large <string>: The URL of the large image.

variants <array of maps>

A list of collectible variants of the card.

• name <string>: The name of the variant (e.g., "normal", "foil").
• images <array of maps>: Any images available for the specific variant
• prices <array>: The price data for the variant.

rulings <array of maps>

A list of official rulings for the card

• date <string>: The data of the ruling in format YYY/MM/DD
• text <string>: The ruling text

expansion <object>

Details about the card's expansion or set.

• id <string>: The ID of the expansion.
• name <string>: The name of the expansion.
• code <string>: The code of the expansion (e.g., "KTK", "BLB")
• type <string>: The type of expansion (e.g., "expansion", "masterpiece", "core")
• block <string>: The block the expansion is part of (when blocks still existed, such as Theros)
• total <number>: The number of cards in the expansion.
• release_date <string>: The release date in format YYYY/MM/DD
• is_foreign_only <boolean>: Whether the expansion is foreign only (no english print)
• is_foil_only <boolean>: Whether the expansion only has foil cards.
• is_non_foil_only <boolean>: Whether the expansion only has non-foil cards.
• is_online_only <boolean>: Whether the expansion is online only
• is_paper_only <boolean>: Whether the expansion is paper only, and doesn't appear online.
• is_partial_preview <boolean>: Whether the expansion is still being revealed, and not completely released.
• logo <string>: The url of the expansion logo.
• symbol <string>: The url of the expansion symbol.

language <string>

The language of the card.

language_code <string>

The language code of the card (e.g., "EN", "JA").

expansion_sort_order <integer>

The position of the card in the expansion, used for sorting.

Here is an example JSON representation of the Pokémon card object:

{
  "id": "KTK-214",
  "name": "Zurgo Helmsmasher",
  "supertypes": [
    "Legendary"
  ],
  "subtypes": [
    "Orc",
    "Warrior"
  ],
  "types": [
    "Creature"
  ],
  "type": "Legendary Creature — Orc Warrior",
  "number": "214",
  "color_identity": [
    "B",
    "R",
    "W"
  ],
  "colors": [
    "B",
    "R",
    "W"
  ],
  "mana_cost": "{2}{R}{W}{B}",
  "mana_value": 5,
  "power": "7",
  "toughness": "2",
  "rules": [
    "Haste",
    "Zurgo attacks each combat if able.",
    "During your turn, Zurgo has indestructible.",
    "Whenever a creature dealt damage by Zurgo this turn dies, put a +1/+1 counter on Zurgo."
  ],
  "rarity": "Mythic",
  "artist": "Aleksi Briclot",
  "keywords": [
    "Haste"
  ],
  "layout": "normal",
  "faces": [],
  "images": [
    {
      "type": "front",
      "small": "https://images.scrydex.com/magicthegathering/KTK-214/small",
      "medium": "https://images.scrydex.com/magicthegathering/KTK-214/medium",
      "large": "https://images.scrydex.com/magicthegathering/KTK-214/large"
    }
  ],
  "variants": [
    {
      "name": "normal",
      "images": [],
      "border_color": "black"
    },
    {
      "name": "foil",
      "images": [],
      "border_color": "black"
    }
  ],
  "rulings": [
    {
      "date": "2014/09/20",
      "text": "Each time a creature dies, check whether Zurgo had dealt any damage to it at any time during that turn. If so, Zurgo's ability will trigger. It doesn't matter who controlled the creature or whose graveyard it went to."
    },
    {
      "date": "2014/09/20",
      "text": "If Zurgo enters the battlefield before the combat phase, it will attack that turn if able. If it enters the battlefield after combat, it won't attack that turn and will usually be available to block on the following turn."
    },
    {
      "date": "2014/09/20",
      "text": "If, during your declare attackers step, Zurgo is tapped or is affected by a spell or ability that says it can't attack, then it doesn't attack. If there's a cost associated with having Zurgo attack, you aren't forced to pay that cost, so it doesn't have to attack in that case either."
    },
    {
      "date": "2014/09/20",
      "text": "You still choose which player or planeswalker Zurgo Helmsmasher attacks."
    }
  ],
  "expansion": {
    "id": "KTK",
    "name": "Khans of Tarkir",
    "code": "KTK",
    "type": "expansion",
    "block": "Khans of Tarkir",
    "total": 306,
    "release_date": "2014/09/26",
    "is_foil_only": false,
    "is_online_only": false,
    "logo": "https://images.scrydex.com/magicthegathering/KTK-logo/logo",
    "symbol": "https://images.scrydex.com/magicthegathering/KTK-symbol/symbol"
  },
  "language": "English",
  "language_code": "EN",
  "expansion_sort_order": 235
}

curl --request GET \
  --url https://api.scrydex.com/pokemon/v1/cards/xy1-1 \
  --header 'X-Api-Key: <api_key_here>'
  --header 'X-Team-Id: <team_id_here>'

This endpoint retrieves a specific Pokémon card by its unique identifier.

URL

GET https://api.scrydex.com/v1/cards/<id>

URL Parameters

• id <string>
  The unique identifier of the card to retrieve. This is a required parameter.

Query Parameters

• select <comma-separated string>
  
  Specifies which fields to return in the response (e.g., "name,types,attacks").

• casing <string>
  
  Allows changing the output format of the response. Supported values are:

  • camel
  • snake

• include <comma-separated string>
  
  Fetch additional resources alongside the card. Supported values include:

  • prices (fetch price details for the card)

Here is how you can retrieve a card using various programming languages:

curl --request GET \
  --url https://api.scrydex.com/pokemon/v1/cards/xy1-1 \
  --header 'X-Api-Key: <api_key_here>'

card = Pokemon::Card.find('sv1-1')
puts card.name # => "Pineco"

from pokemon import Card

card = Card.find('sv1-1')
print(card.name)  # Output: "Pineco"

pokemon.card.find('sv1-1')
    .then(card => {
        console.log(card.name) // "Pineco"
    });

Fetching and searching for multiple cards in the Scrydex API is simple yet powerful. Use the various query parameters to customize your requests and retrieve the specific cards or data you need.

Query Parameters

All query parameters are optional, but combining them allows for advanced and targeted searches.

Key Features of q (Search Queries)

Search queries use a Lucene-like syntax for filtering, making it easy to build powerful card searches. Below are examples of supported query operations:

Keyword Matching

• Find cards that contain "charizard" in the name field: name:charizard
• Search for the phrase "venusaur v" in the name field: name:"venusaur v"
• Combine multiple conditions:
  • Cards with "charizard" in the name AND "mega" in the subtypes field: name:charizard subtypes:mega
  • Cards with "charizard" in the name AND either "mega" or "vmax" in subtypes: name:charizard (subtypes:mega OR subtypes:vmax)

Exclude Results

• Retrieve only cards with subtypes:mega while excluding water types: subtypes:mega -types:water

Wildcard Matching

• Cards where the name starts with "char": name:char*
• Cards where the name starts with "char" and ends with "der": name:char*der

Exact Matching

• Match cards where the name is exactly "charizard" (no other characters appear in the name field): !name:charizard

Range Searches

Fields containing numerical data (e.g., hp, nationalPokedexNumbers) support range searches:

• Cards featuring the original 151 Pokémon: nationalPokedexNumbers:[1 TO 151]
• Cards with HP values up to 100: hp:[* TO 100]
• Cards with HP values greater than or equal to 150: hp:[150 TO *]

Pro Tip: Use square brackets [ ] for inclusive ranges, and curly braces { } for exclusive ranges.

Searching Nested Fields

Leverage the . separator to search nested fields:

• Filter by set ID: set.id:sm1
• Find cards with an attack named "Spelunk": attacks.name:Spelunk
• Search for cards banned in Standard play: legalities.standard:banned

Example: Fetch & Search Cards

Use the query parameters to retrieve and search cards. Below are examples using Scrydex API:

Ordering Data

The orderBy parameter allows for flexible sorting of results:

• Order cards by number within their set: ?orderBy=number
• Combine ascending (ASC) and descending (DESC) order: ?orderBy=name,-number

Field Selection

Optimize and reduce response payload sizes using the select parameter to return only the fields you care about:

• Example: Request only id and name fields for all cards: ?select=id,name

Response Example

Here’s a sample response for a search query:

{
  "status": "success",
  "data": [
    {
      "id": "xy7-54",
      "name": "Gardevoir-EX",
      "hp": 170,
      "types": ["Fairy"],
      "subtypes": ["EX"]
    },
    {
      "id": "sm3-20",
      "name": "Charizard-GX",
      "hp": 250,
      "types": ["Fire"],
      "subtypes": ["GX"]
    }
  ],
  "page": 1,
  "pageSize": 2,
  "totalCount": 5000
}

Best Practices for Fetching & Searching

• Paginate Results: Use the page and pageSize parameters to prevent overloading responses.
• Limit Fields Returned: Use the select parameter to only get the data you need.
• Avoid Overhead: Minimize wildcard or range queries for better performance.