API Reference

Client

class scryfall.client.Scryfall(logger: Logger | None = None)

async request(route: Route, params: dict | None = None, **kwargs: dict) → dict[str, Any]

Make a request to the Scryfall API.

Parameters:

route – Route to take
params – Query string parameters. Defaults to None.

Returns:

Raw result

Return type:

dict[str, Any]

async close() → None: Close the session.

HTTP

Card

class scryfall.client.http.card.CardRequests(*args, **kwargs)

async get_card_by_id(id: str | UUID) → Card

Get a card by ID.

Parameters:: id – UUID of card

async get_card_by_tcgplayer_id(id: int) → Card

Get card by TCGPlayer ID

Parameters:: id – TCGPlayer ID

async get_card_by_multiverse_id(id: int) → Card

Get card by Multiverse ID

Parameters:: id – Multiverse ID

async get_card_by_mtgo_id(id: int) → Card

Get card by MTGO ID

Parameters:: id – MTGO ID

async get_card_by_arena_id(id: int) → Card

Get card by MTG Arena ID

Parameters:: id – MTG Arena ID

async get_card_by_cardmarket_id(id: int) → Card

Get card by Cardmarket ID

Parameters:: id – Cardmarket ID

async get_rulings_by_card_id(id: str | UUID) → list[Ruling]

Get card rulings by card ID.

Parameters:: id – UUID of card

async search_cards(q: str, unique: Literal['cards', 'art', 'prints'] = 'cards', order: Literal['name', 'set', 'released', 'rarity', 'color', 'usd', 'tix', 'eur', 'cmc', 'power', 'toughness', 'edhrec', 'penny', 'artist', 'review'] = 'name', dir: Literal['auto', 'asc', 'desc'] = 'auto', include_extras: bool = False, include_multilingual: bool = False, include_variations: bool = False, page: int = 1) → APIList

Search for a card using a fulltext string search.

Parameters:

q – A fulltext search query. Max length: 1000 Unicode characters
unique – The strategy for omitting cards. Default cards
order – The method to sort returned cards. Default name
dir – Direction to sort cards. Default auto
include_extras – If true, extra cards (tokens, planes, etc) will be included. Equivalent to adding include:extras to the fulltext search. Default false
include_multilingual – If true, cards in every language supported by Scryfall will be included. Default false
include_variations – If true, rare card variants will by included. Default false
page – Page number to return. Default 1

async search_cards_named(exact: str | None = None, fuzzy: str | None = None, set: str | None = None) → Card

Search for a card using name search.

Parameters:

exact – Exact string to search for
fuzzy – Fuzzy string to search for
set – Set to search in

async cards_autocomplete(q: str, include_extras: bool = False) → Catalog

Returns a Catalog containing up to 20 full English card names for autocomplete purposes.

Parameters:

q – The string to autocomplete
include_extras – If true, extra cards (tokens, planes, vanguards, etc) will be included. Default False

Set

class scryfall.client.http.set.SetRequests(*args, **kwargs)

async get_all_sets() → APIList: Get all MTG sets.

async get_set_by_id(id: str | UUID) → Set

Get MTG set by ID.

Parameters:: id – UUID of set

async get_set_by_code(code: str) → Set

Get MTG set by set code.

Parameters:: code – Set code

async get_set_by_tcgplayer_id(id: int) → Set

Get MTG set by TCGPlayer ID.

Parameters:: id – TCGPlayer ID of set

Models

class scryfall.models.APIError(*, status: int, code: str, details: str, type: str | None = None, warnings: list[str] | None = None)

Scryfall API error model.

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

status: int: HTTP status code

code: str: HTTP status code text (i.e. not_found)

details: str: More details

type: str | None: The error type

warnings: list[str] | None: Any associated warnings that are not quite errors

Scryfall API list model for paginated requests

async get_next_page() → APIList | None: Get the next page of the query

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None: We need to both initialize private attributes and call the user-defined model_post_init method.

object: Literal['list']: The object type, list in this case

data: list[Card | CardSymbol | Ruling | Set]: The page of data, max 175 items unless it is an entire set of cards

has_more: bool: If there are more pages

next_page: HttpUrl | None: The URL to the next page

total_cards: int | None: The total number of cards found by the original query

warnings: list[str] | None: Warnings generated by the query that are not quite errors

class scryfall.models.BulkData(*, id: UUID, uri: HttpUrl, type: str, name: str, description: str, download_uri: HttpUrl, updated_at: datetime, size: int, content_type: str, content_encoding: str)

Bulk data model

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

id: UUID: UUID of the bulk data

uri: HttpUrl: URI of the bulk data endpoint

type: str: The type of data in the download

name: str: The name of the download

description: str: A description of the download

download_uri: HttpUrl: The download URL for the bulk data

updated_at: datetime: When this bulk data was last updated

size: int: The size of the data in bytes

content_type: str: The content type

content_encoding: str: The MIME encoding

class scryfall.models.Card(*, arena_id: int | None = None, id: UUID, lang: str, mtgo_id: int | None = None, mtgo_foil_id: int | None = None, multiverse_ids: list[int] | None = None, tcgplayer_id: int | None = None, tcgplayer_etched_id: int | None = None, cardmarket_id: int | None = None, object: Literal['card'], layout: str, oracle_id: UUID | None = None, prints_search_uri: HttpUrl, rulings_uri: HttpUrl, scryfall_uri: HttpUrl, uri: HttpUrl, all_parts: list[RelatedCard] | None = None, card_faces: list[CardFace] | None = None, cmc: float, color_identity: list[Color], color_indicator: list[Color] | None = None, colors: list[Color] | None = None, defense: str | None = None, edhrec_rank: int | None = None, game_changer: bool | None = None, hand_modifier: str | None = None, keywords: list[str], legalities: dict[str, Literal['legal', 'not_legal', 'restricted', 'banned']], life_modifier: str | None = None, loyalty: str | None = None, mana_cost: str | None = None, name: str, oracle_text: str | None = None, penny_rank: int | None = None, power: str | None = None, produced_mana: list[Color] | None = None, reserved: bool, toughness: str | None = None, type_line: str, artist: str | None = None, artist_ids: list[UUID] | None = None, attraction_lights: list[int] | None = None, booster: bool, border_color: Literal['black', 'white', 'borderless', 'yellow', 'silver', 'gold'], card_back_id: UUID | None = None, collector_number: str, content_warning: bool | None = None, digital: bool, finishes: list[Literal['foil', 'nonfoil', 'etched']], flavor_name: str | None = None, flavor_text: str | None = None, frame_effects: list[str] | None = None, frame: str, full_art: bool, games: list[Literal['paper', 'arena', 'mtgo']], highres_image: bool, illustration_id: UUID | None = None, image_status: Literal['missing', 'placeholder', 'lowres', 'highres_scan'], image_uris: dict[Literal['small', 'normal', 'large', 'png', 'art_crop', 'border_crop'], HttpUrl] | None = None, oversized: bool, prices: dict[str, str | None], printed_name: str | None = None, printed_text: str | None = None, printed_type_line: str | None = None, promo: bool, promo_types: list[str] | None = None, purchase_uris: dict[str, HttpUrl] | None = None, rarity: Literal['common', 'uncommon', 'rare', 'special', 'mythic', 'bonus'], related_uris: dict[str, HttpUrl], released_at: date, reprint: bool, scryfall_set_uri: HttpUrl, set_name: str, set_search_uri: HttpUrl, set_type: str, set_uri: HttpUrl, set: str, set_id: UUID, story_spotlight: bool, textless: bool, variation: bool, variation_of: UUID | None = None, security_stamp: Literal['oval', 'triangle', 'acorn', 'circle', 'arena', 'heart'] | None = None, watermark: str | None = None, preview: Preview | None = None)

Main Card model.

async get_rulings() → list[Ruling]: Get rulings for card.

async get_set() → Set: Get set card is a part of.

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None: We need to both initialize private attributes and call the user-defined model_post_init method.

arena_id: int | None: MTG Arena ID

id: UUID: Scryfall card UUID

lang: str: Card language

mtgo_id: int | None: MTG Online ID

mtgo_foil_id: int | None: MTG Online Foil ID

multiverse_ids: list[int] | None: MTG Multiverse IDs

tcgplayer_id: int | None: TCGPlayer ID

tcgplayer_etched_id: int | None: TCGPlayer Etched ID

cardmarket_id: int | None: Cardmarket ID

object: Literal['card']: Object type, literally card

layout: str: Card layout

oracle_id: UUID | None: Oracle UUID

prints_search_uri: HttpUrl: Print search URL for other printings

rulings_uri: HttpUrl: Rulings URL

scryfall_uri: HttpUrl: Scryfall URL

uri: HttpUrl: Card URL

all_parts: list[RelatedCard] | None: If this card is closely related to other cards, this property will be an array with Related Card objects.

card_faces: list[CardFace] | None: All faces of the card

cmc: float: Card mana value

color_identity: list[Color]: Card color identity

color_indicator: list[Color] | None: Card color indicator, if any

colors: list[Color] | None: Card colors, if any. Colors may be on the card’s faces instead

defense: str | None: Toughness

edhrec_rank: int | None: EDHRec card rank/popularity

game_changer: bool | None: If this car is on the Commander Game Changer list

hand_modifier: str | None: Vanguard card hand modifier

keywords: list[str]: List of keywords, such as Flying or Cumulative upkeep

legalities: dict[str, Literal['legal', 'not_legal', 'restricted', 'banned']]: List of legalitites across different formats

life_modifier: str | None: The card’s life modifier, if it is a Vanguard card. This value will contain a delta, such as +2.

loyalty: str | None: This loyalty if any. Note that some cards have loyalties that are not numeric, such as X.

mana_cost: str | None: The mana cost for this card. This value will be any empty string “” if the cost is absent. Remember that per the game rules, a missing mana cost and a mana cost of {0} are different values. Multi-faced cards will report this value in card faces.

name: str: The name of this card. If this card has multiple faces, this field will contain both names separated by ␣//␣.

oracle_text: str | None: The Oracle text for this card, if any.

penny_rank: int | None: This card’s rank/popularity on Penny Dreadful. Not all cards are ranked.

power: str | None: This card’s power, if any. Note that some cards have powers that are not numeric, such as *.

produced_mana: list[Color] | None: Colors of mana that this card could produce.

reserved: bool: True if this card is on the Reserved List.

toughness: str | None: This card’s toughness, if any. Note that some cards have toughnesses that are not numeric, such as *.

type_line: str: The type line of this card.

class scryfall.models.Catalog(*, object: Literal['catalog'], uri: HttpUrl | None = None, total_values: int, data: list[str])

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class scryfall.models.Ruling(*, object: Literal['ruling'], oracle_id: UUID, source: Literal['wotc', 'scryfall'], published_at: date, comment: str)

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class scryfall.models.Set(*, object: Literal['set'], id: UUID, code: str, mtgo_code: str | None = None, arena_code: str | None = None, tcgplayer_id: int | None = None, name: str, set_type: str, released_at: date | None = None, block_code: str | None = None, block: str | None = None, parent_set_code: str | None = None, card_count: int, printed_size: int | None = None, digital: bool, foil_only: bool, nonfoil_only: bool, scryfall_uri: HttpUrl, uri: HttpUrl, icon_svg_uri: HttpUrl, search_uri: HttpUrl)

async get_cards() → APIList: Get a list of cards from the set.

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None: We need to both initialize private attributes and call the user-defined model_post_init method.

class scryfall.models.CardSymbol(*, object: Literal['card_symbol'], symbol: str, loose_variant: str | None = None, english: str, transposable: bool, represents_mana: bool, mana_value: float | None = None, appears_in_mana_costs: bool, funny: bool, colors: list[Color], hybrid: bool, phyrexian: bool, gatherer_alternatives: str | None = None, svg_uri: HttpUrl | None = None)

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].