API Reference

EDHREC

Scryfall

Scryfall is a search engine for magic cards. It provides a REST-like API for ingesting our card data programatically. The API exposes information available on the regular site in easy-to-consume formats.

Feature	Support
Cards	✅
Sets	✅
Rulings	✅
Card Symbols	✅
Bulk Data	✅ (fully async)
Card Migrations	✅
Application	❌

Scryfall Client

class mightstone.services.scryfall.Scryfall(transport: Optional[BaseTransport] = None)

Scryfall API client

autocomplete(q: str, include_extras=False) → Catalog: Sync version of autocomplete_async(), same behavior but wrapped by async_to_sync().

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

Returns a Catalog object containing up to 20 full English card names that could be autocompletions of the given string parameter.

This method is designed for creating assistive UI elements that allow users to free-type card names. The names are sorted with the nearest match first, highly favoring results that begin with your given string.

Spaces, punctuation, and capitalization are ignored.

If q is less than 2 characters long, or if no names match, the Catalog will contain 0 items (instead of returning any errors).

Parameters:

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

Returns:

A scryfall Card instance async generator

base_url: str = 'https://api.scryfall.com': Base url of the service (must be a root path such as https://example.com)

card(id: str, type: CardIdentifierPath = CardIdentifierPath.SCRYFALL) → Card: Sync version of card_async(), same behavior but wrapped by async_to_sync().

async card_async(id: str, type: CardIdentifierPath = CardIdentifierPath.SCRYFALL) → Card

Returns a single card with a given ID, or by its code set / collector number

Depending on the type value, one of the following endpoint will be reached:

/cards/:id
/cards/tcgplayer/:id
/cards/multiverse/:id
/cards/mtgo/:id
/cards/arena/:id
/cards/cardmarket/:id
/cards/:code/:number

Parameters:

id – The requested Card identifier string, for code-number, please use / as separator (dmu/123)
type – The card identifier, please refer to CardIdentifierPath enum
type – Type of id researched

Returns:

A scryfall Card instance

catalog(type: CatalogType) → Catalog: Sync version of catalog_async(), same behavior but wrapped by async_to_sync().

async catalog_async(type: CatalogType) → Catalog

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

Parameters:: type – See CatalogType for more informations
Returns:: A Catalog instance

collection(identifiers: List[Union[IdentifierId, IdentifierName, IdentifierNameSet, IdentifierMtgId, IdentifierOracleId, IdentifierMultiverseId, IdentifierCollectorNumberSet, IdentifierIllustrationId]]) → AsyncGenerator[Card, None]: Sync version of collection_async(), same behavior but wrapped by async_to_sync().

async collection_async(identifiers: List[Union[IdentifierId, IdentifierName, IdentifierNameSet, IdentifierMtgId, IdentifierOracleId, IdentifierMultiverseId, IdentifierCollectorNumberSet, IdentifierIllustrationId]]) → AsyncGenerator[Card, None]

Accepts a JSON array of card identifiers, and returns a List object with the collection of requested cards. A maximum of 75 card references may be submitted per request.

Parameters:: identifiers – Each submitted card identifier must be a JSON object with one or more of the keys id, mtgo_id, multiverse_id, oracle_id, illustration_id, name, set, and collector_number
Returns:: A scryfall Card instance async generator

get_bulk_data(bulk_type: str) → AsyncGenerator[Card, None]: Sync version of get_bulk_data_async(), same behavior but wrapped by async_to_sync().

async get_bulk_data_async(bulk_type: str) → AsyncGenerator[Card, None]

Access the bulk cards This script uses ijson and should stream data on the fly

See https://scryfall.com/docs/api/bulk-data for more informations

Parameters:: bulk_type – A string describing the bulk export name
Returns:: An async iterator of Card

get_bulk_tags(tag_type: BulkTagType) → AsyncGenerator[Tag, None]: Sync version of get_bulk_tags_async(), same behavior but wrapped by async_to_sync().

async get_bulk_tags_async(tag_type: BulkTagType) → AsyncGenerator[Tag, None]

Access the private tag repository

This is an alpha feature, and could be removed later.

Parameters:: tag_type – The tag type either oracle or illustration
Returns:: A scryfall Tag instance async generator

migration(id: str) → Migration: Sync version of migration_async(), same behavior but wrapped by async_to_sync().

async migration_async(id: str) → Migration

Returns a single Card Migration with the given :id

Returns:: A Migration instance

migrations(limit: int = None) → AsyncGenerator[Migration, None]: Sync version of migrations_async(), same behavior but wrapped by async_to_sync().

async migrations_async(limit: Optional[int] = None) → AsyncGenerator[Migration, None]

For the vast majority of Scryfall’s database, Magic card entries are additive. We add new and upcoming cards as we learn about them and obtain images.

In rare instances, Scryfall may discover that a card in our database does not really exist, or it has been deleted from a digital game permanently. In these situations, we provide endpoints to help you reconcile downstream data you may have synced or imported from Scryfall.

Each migration has a provided migration_strategy:

merge You should update your records to replace the given old Scryfall ID with the new ID. The old ID is being discarded, and an existing record should be used to replace all instances of it.

delete The given UUID is being discarded, and no replacement data is being provided. This likely means the old records are fully invalid. This migration exists to provide evidence that cards were removed from Scryfall’s database.

Parameters:: limit – The number of item to return, please note that Mightstone wraps Scryfall pagination and streams the results
Returns:: A Migration instance async generator

named(q: str, set: str = None, exact=True) → Card: Sync version of named_async(), same behavior but wrapped by async_to_sync().

async named_async(q: str, set: Optional[str] = None, exact=True) → Card

Returns a Card based on a name search string. This method is designed for building chatbots, forum bots, and other services that need card details quickly.

If exact mode is on, a card with that exact name is returned. Otherwise, an Exception is raised because no card matches. If exact mode is off and a card name matches that string, then that card is returned. If not, a fuzzy search is executed for your card name. The server allows misspellings and partial words to be provided. For example: jac bele will match Jace Beleren. When fuzzy searching, a card is returned if the server is confident that you unambiguously identified a unique name with your string. Otherwise, an exception will be raised describing the problem: either more than 1 one card matched your search, or zero cards matched.

Card names are case-insensitive and punctuation is optional (you can drop apostrophes and periods etc). For example: fIReBALL is the same as Fireball and smugglers copter is the same as Smuggler’s Copter.

Parameters:

q – The searched card name
exact – Run a strict text research instead of a fuzzy search
set – You may also provide a set code in the set parameter, in which case the name search and the returned card print will be limited to the specified set.

Returns:

A scryfall Card instance

parse_mana(cost: str) → ManaCost: Sync version of parse_mana_async(), same behavior but wrapped by async_to_sync().

async parse_mana_async(cost: str) → ManaCost

Parses the given mana cost parameter and returns Scryfall’s interpretation.

The server understands most community shorthand for mana costs (such as 2WW for {2}{W}{W}). Symbols can also be out of order, lowercase, or have multiple colorless costs (such as 2{g}2 for {4}{G}).

If part of the string could not be understood, the server will raise an Error object describing the problem.

Parameters:: cost – A mana cost string
Returns:: A ManaCost instance

random(q: str = None) → Card: Sync version of random_async(), same behavior but wrapped by async_to_sync().

async random_async(q: Optional[str] = None) → Card

Returns a single random Card object.

This method will use: - /cards/random

Parameters:: q – The optional parameter q supports the same fulltext search system that the main site uses. Providing q will filter the pool of cards before returning a random entry.
Returns:: A scryfall Card instance

rulings(id: str, type: RulingIdentifierPath = RulingIdentifierPath.SCRYFALL, limit: int = None) → AsyncGenerator[Ruling, None]: Sync version of rulings_async(), same behavior but wrapped by async_to_sync().

async rulings_async(id: str, type: RulingIdentifierPath = RulingIdentifierPath.SCRYFALL, limit: Optional[int] = None) → AsyncGenerator[Ruling, None]

Returns a single card with the given ID.

Depending on the type value, one of the following endpoint will be reached:

/cards/:id/rulings
/cards/multiverse/:id/rulings
/cards/mtgo/:id/rulings
/cards/arena/:id/rulings

Parameters:

id – The requested Card identifier string. In the case of card-number, use set/number (separated by a slash, for instance dmu/123)
type – The card identifier, please refer to RulingIdentifierPath enum

Returns:

A scryfall Ruling instance async generator

search(q: str, unique: UniqueStrategy = UniqueStrategy.CARDS, order: SortStrategy = SortStrategy.NAME, dir: DirectionStrategy = DirectionStrategy.AUTO, include_extras=False, include_multilingual=False, include_variations=False, limit: int = 100) → AsyncGenerator[Card, None]: Sync version of search_async(), same behavior but wrapped by async_to_sync().

async search_async(q: str, unique: UniqueStrategy = UniqueStrategy.CARDS, order: SortStrategy = SortStrategy.NAME, dir: DirectionStrategy = DirectionStrategy.AUTO, include_extras=False, include_multilingual=False, include_variations=False, limit: int = 100) → AsyncGenerator[Card, None]

Returns a List object containing Cards found using a fulltext search string. This string supports the same fulltext search system that the main site uses.

Parameters:

unique – The strategy for omitting similar cards.
order – The method to sort returned cards.
dir – The direction to sort cards.
include_extras – If true, extra cards (tokens, planes, etc) will be included. Equivalent to adding include:extras to the fulltext search.
include_multilingual – If true, cards in every language supported by Scryfall will be included.
include_variations – If true, rare care variants will be included, like the Hairy Runesword.
q – A fulltext search query.
limit – The number of item to return, please note that Mightstone wraps Scryfall pagination and streams the results

Returns:

A scryfall Card instance async generator

set(limit: int = None) → AsyncGenerator[Set, None]: Sync version of sets_async(), same behavior but wrapped by async_to_sync().

async set_async(id_or_code: Optional[str] = None) → Set

Returns a Set with the given set code.

Parameters:: id_or_code – The code can be either the code or the mtgo_code or the scryfall UUID for the set.
Returns:: A Set instance

sets(limit: int = None) → AsyncGenerator[Set, None]: Sync version of sets_async(), same behavior but wrapped by async_to_sync().

async sets_async(limit: Optional[int] = None) → AsyncGenerator[Set, None]

Returns a List object of all Sets on Scryfall.

Parameters:: limit – The number of item to return, please note that Mightstone wraps Scryfall pagination and streams the results
Returns:: A Set instance async generator

symbols(limit: int = None) → AsyncGenerator[Symbol, None]: Sync version of symbols_async(), same behavior but wrapped by async_to_sync().

async symbols_async(limit: Optional[int] = None) → AsyncGenerator[Symbol, None]

Returns a List of all Card Symbols.

Parameters:: limit – The number of item to return, please note that Mightstone wraps Scryfall pagination and streams the results
Returns:: A scryfall Symbol instance async generator

Models

`BulkTagType`(value)	An enumeration.
`Card`
`CardFace`(_typename[, _fields])
`Catalog`
`ManaCost`
`Migration`
`Preview`
`Ruling`	Rulings represent Oracle rulings, Wizards of the Coast set release notes, or Scryfall notes for a particular card.
`Set`	A Set object represents a group of related Magic cards. All Card objects on Scryfall
`Symbol`	A Card Symbol object represents an illustrated symbol that may appear in card’s mana cost or Oracle text.
`Tag`

MTGJSON

MTGJSON is an open-source project that catalogs all Magic: The Gathering data in portable formats. Using an aggregation process we fetch information between multiple resources and approved partners, and combine all that data in to various downloadable formats.

Feature	Support
JSON data	✅
Compressed JSON data	✅ (except zip)
SQLite data	❌
CSV data	❌
GraphQL API	❌

MtgJson Client

class mightstone.services.mtgjson.MtgJson(compression: Optional[MtgJsonCompression] = None, version: int = 5, *args, **kwargs)

MTGJSON client

Supports compression and will get gzip versions by default.

all_identifiers() → AsyncGenerator[Card, None]: Sync version of all_identifiers_async(), same behavior but wrapped by async_to_sync().

async all_identifiers_async() → AsyncGenerator[Card, None]

all Card (Set) cards organized by card UUID.

Returns:: An async iterator of Card object (either CardToken, or CardSet)

all_prices() → AsyncGenerator[CardPrices, None]: Sync version of all_prices_async(), same behavior but wrapped by async_to_sync().

async all_prices_async() → AsyncGenerator[CardPrices, None]

all prices of cards in various formats.

Returns:: An async iterator of CardPrices

all_printings() → AsyncGenerator[Set, None]: Sync version of all_printings_async(), same behavior but wrapped by async_to_sync().

async all_printings_async() → AsyncGenerator[Set, None]

all Card (Set) cards, including all printings and variations, categorized by set.

Returns:: An async iterator of CardSet

atomic_cards() → AsyncGenerator[CardAtomic, None]: Sync version of atomic_cards_async(), same behavior but wrapped by async_to_sync().

async atomic_cards_async() → AsyncGenerator[CardAtomic, None]

every Card (Atomic) card.

Returns:: An async iterator of CardAtomic

base_url: str = 'https://mtgjson.com': Base url of the service (must be a root path such as https://example.com)

card_types() → CardTypes: Sync version of card_types_async(), same behavior but wrapped by async_to_sync().

async card_types_async() → CardTypes

every card type of any type of card.

Returns:: A CardTypes object

compiled_list() → List[str]: Sync version of compiled_list_async(), same behavior but wrapped by async_to_sync().

async compiled_list_async() → List[str]

all individual outputs from MTGJSON, such as AllPrintings, CardTypes, etc.

Returns:: A list of string

deck(file_name: str) → Deck: Sync version of deck_async(), same behavior but wrapped by async_to_sync().

async deck_async(file_name: str) → Deck

Recovers a deck data

Parameters:: file_name – the deck file_name
Returns:: A Deck object

deck_list() → AsyncGenerator[DeckList, None]: Sync version of deck_list_async(), same behavior but wrapped by async_to_sync().

async deck_list_async() → AsyncGenerator[DeckList, None]

all individual Deck data.

Returns:: An async iterator of DeckList

enum_values() → dict: Sync version of enum_values_async(), same behavior but wrapped by async_to_sync().

async enum_values_async() → dict

All known property values for various Data Models.

Returns:: a dict object

keywords() → Keywords: Sync version of keywords_async(), same behavior but wrapped by async_to_sync().

async keywords_async() → Keywords

a list of possible all keywords used on all cards.

Returns:: A Keywords object

legacy() → AsyncGenerator[Set, None]: Sync version of legacy_async(), same behavior but wrapped by async_to_sync().

async legacy_async() → AsyncGenerator[Set, None]

all Card (Set) cards organized by Set, restricted to sets legal in the Legacy format.

Returns:: An async iterator of Set

legacy_atomic() → AsyncGenerator[CardAtomic, None]: Sync version of legacy_atomic_async(), same behavior but wrapped by async_to_sync().

async legacy_atomic_async() → AsyncGenerator[CardAtomic, None]

all Card (Set) cards organized by Set, restricted to sets legal in the Legacy format.

Returns:: An async iterator of CardAtomic

meta() → Meta: Sync version of meta_async(), same behavior but wrapped by async_to_sync().

async meta_async() → Meta

the metadata object with ISO 8601 dates for latest build and SemVer specifications of the MTGJSON release.

Returns:: A Meta object

modern() → AsyncGenerator[Set, None]: Sync version of modern_async(), same behavior but wrapped by async_to_sync().

async modern_async() → AsyncGenerator[Set, None]

all Card (Set) cards organized by Set, restricted to sets legal in the Modern format.

Returns:: An async iterator of Set

modern_atomic() → AsyncGenerator[CardAtomic, None]: Sync version of modern_atomic_async(), same behavior but wrapped by async_to_sync().

async modern_atomic_async() → AsyncGenerator[CardAtomic, None]

all Card (Atomic) cards, restricted to cards legal in the Modern format.

Returns:: An async iterator of CardAtomic

pauper_atomic() → AsyncGenerator[CardAtomic, None]: Sync version of pauper_atomic_async(), same behavior but wrapped by async_to_sync().

async pauper_atomic_async() → AsyncGenerator[CardAtomic, None]

all Card (Atomic) cards, restricted to cards legal in the Pauper format.

Returns:: An async iterator of CardAtomic

pioneer() → AsyncGenerator[Set, None]: Sync version of pioneer_async(), same behavior but wrapped by async_to_sync().

async pioneer_async() → AsyncGenerator[Set, None]

all Card (Set) cards organized by Set, restricted to cards legal in the Pioneer format.

Returns:: An async iterator of Set

pioneer_atomic() → AsyncGenerator[CardAtomic, None]: Sync version of pioneer_atomic_async(), same behavior but wrapped by async_to_sync().

async pioneer_atomic_async() → AsyncGenerator[CardAtomic, None]

all Card (Atomic) cards, restricted to cards legal in the Pioneer format.

Returns:: An async iterator of CardAtomic

set(code: str) → SetList: Sync version of set_async(), same behavior but wrapped by async_to_sync().

async set_async(code: str) → SetList

Get a Set data

Parameters:: code – The set identifier, such as “IKO” for “Ikoria, lair of the monsters”
Returns:: The set representation

set_list() → AsyncGenerator[SetList, None]: Sync version of set_list_async(), same behavior but wrapped by async_to_sync().

async set_list_async() → AsyncGenerator[SetList, None]

a list of meta data for all Set data.

Returns:: An async iterator of SetList

standard() → AsyncGenerator[Set, None]: Sync version of standard_async(), same behavior but wrapped by async_to_sync().

async standard_async() → AsyncGenerator[Set, None]

all Card (Set) cards organized by Set, restricted to cards legal in the Standard format.

Returns:: An async iterator of Set

standard_atomic() → AsyncGenerator[CardAtomic, None]: Sync version of standard_atomic_async(), same behavior but wrapped by async_to_sync().

async standard_atomic_async() → AsyncGenerator[CardAtomic, None]

all Card (Atomic) cards, restricted to cards legal in the Standard format.

Returns:: An async iterator of CardAtomic

tcg_player_skus() → AsyncGenerator[TcgPlayerSKUs, None]: Sync version of tcg_player_skus_async(), same behavior but wrapped by async_to_sync().

async tcg_player_skus_async() → AsyncGenerator[TcgPlayerSKUs, None]

TCGplayer SKU information based on card UUIDs.

Returns:: an async iterator of TcgPlayerSKUs

vintage() → AsyncGenerator[Set, None]: Sync version of vintage_async(), same behavior but wrapped by async_to_sync().

async vintage_async() → AsyncGenerator[Set, None]

all Card (Set) cards organized by Set, restricted to sets legal in the Vintage format.

Returns:: An async iterator of Set

vintage_atomic() → AsyncGenerator[CardAtomic, None]: Sync version of vintage_atomic_async(), same behavior but wrapped by async_to_sync().

async vintage_atomic_async() → AsyncGenerator[CardAtomic, None]

all Card (Atomic) cards, restricted to sets legal in the Vintage format.

Returns:: An async iterator of CardAtomic

Models

`Card`	A card either a Card from a set, or a token
`Set`
`SetList`	The Set List Data Model describes a metadata-like properties and values for an individual Set.
`Meta`
`Keywords`
`Deck`	The Deck Data Model describes a complete deck reference.
`DeckList`	The Deck List Data Model describes a metadata-like model for a Deck.
`CardTypes`	The Card Types Data Model describes card types that a card may have.

Card Conjurer

Card Conjurer is a card editor service that provides a unique file format to describe a card image. Each card is described in a JSON file that extends a template. Template may vary from MTG copycat to brand new card frame.

Feature	Support
Template	✅ (read-only)
Card	✅ (read-only)
Card Generation	🟠 Working for the most part, but inline symbols are not supported

../_images/cardconjurer.sample.png — Fig 1. Card Conjurer generated image

../_images/cardconjurer.mightstone.png — Fig 2. Mightstone generated image

CardConjurer Client

class mightstone.services.cardconjurer.CardConjurer(default_font=None, **kwargs)

Card Conjurer client

base_url: str: Base url of the service (must be a root path such as https://example.com)

card(url_or_path) → Card: Sync version of card_async(), same behavior but wrapped by async_to_sync().

async card_async(url_or_path) → Card

Open a Card, local or through HTTP

Parameters:: url_or_path – A path or an url
Returns:: Card instance

render(card: Card, output=None) → Image: Sync version of render_async(), same behavior but wrapped by async_to_sync().

async render_async(card: Card, output=None) → Image

Render a card object into a PIL Image

Parameters:

card – Card model from Card Conjurer
output – A path or a file like object for writing

Returns:

A PIL Image object

template(url_or_path) → Template: Sync version of template_async(), same behavior but wrapped by async_to_sync().

async template_async(url_or_path) → Template

Open a Template, local or through HTTP

Parameters:: url_or_path – A path or an url
Returns:: Template instance

Models

`Card`	A Card as described in Card Conjurer JSON
`Template`	A Template as described in Card Conjurer JSON
`Image`	A layer composed of an image (One of the 3 possible layer types)
`Text`	A layer composed of a text (One of the 3 possible layer types)
`Group`	A layer composed of a list of other layers (One of the 3 possible layer types)

Wizards Of The Coast

RuleExplorer Client

class mightstone.services.wotc.RuleExplorer(transport: Optional[BaseTransport] = None)

base_url: str = 'https://media.wizards.com': Base url of the service (must be a root path such as https://example.com)

explore(after: date, before: date = None, concurrency=3) → List[str]: Sync version of explore_async(), same behavior but wrapped by async_to_sync().

async explore_async(after: date, before: Optional[date] = None, concurrency=3) → List[str]

Explore the wizards of the coast website to find any rule between two timestamp.

Wizards don’t support an historic index of previous rules, this method tries to compensate by providing a brute force attempt to pull magic rule history. This method will brute force every possible rule using the current format:

https://media.wizards.com/YYYY/downloads/MagicComp%20Rules%20{YYYY}{MM}{DD}.txt

Parameters:

after – The min date to scan
before – The max date to scan (defaults to today)
concurrency – The max number of concurrent HTTP requests

Returns:

A list of existing rules url

latest() → str: Sync version of latest_async(), same behavior but wrapped by async_to_sync().

async latest_async() → str

Resolves wizard latest published ruleset

Returns:: The url of the latest ruleset to date

open(path: str = None) → ComprehensiveRules: Sync version of open_async(), same behavior but wrapped by async_to_sync().

async open_async(path: Optional[str] = None) → ComprehensiveRules

Open a local or remote comprehensive rule document, if no path is provided then the latest rules from Wizards of the Coast website is pulled.

Parameters:: path – A local path, or an URL to the rule document
Returns:: A ComprehensiveRules instance

Models

`ComprehensiveRules`
`Ruleset`
`Glossary`