Scryfall

Implementation notes

When to use Scryfall

Scryfall is the reference API for Magic: The Gathering — every card ever printed, every printing of every card, oracle text, rulings, format legality, marketplace prices, and high-resolution card images. No key, no signup, and a search syntax that is genuinely excellent: it is the same query language the website uses, so you can prototype a query in the search box and paste it straight into your code. Use it for deck builders, collection trackers, Discord bots, draft simulators, and price-check tools. It is one of the best-run free APIs in any category — thoughtful documentation, a published rate-limit courtesy policy, versioned bulk data downloads, and maintainers who communicate changes ahead of time. The design assumption is that heavy consumers download the bulk files and query locally while the HTTP API handles lookups and interactive search; integrations that respect that split essentially never have problems.

Common pitfalls

• Scryfall asks for 50-100ms between requests, roughly 10 per second, and enforces it with 429s escalating to IP blocks for sustained abuse. Anything beyond interactive lookups should use the bulk data endpoint, which serves the whole card database as one compressed JSON file refreshed daily. Downloading a few hundred megabytes once a day is faster for you and is the behaviour they explicitly ask for.
• Card images are immutable per printing and can be cached forever, but the docs ask you not to hotlink them at scale — download what you display and serve it from your own storage. Also note that the image_uris object is absent entirely on double-faced cards, where the images live under card_faces[].image_uris instead, so naive accessors throw on roughly every transforming card.
• Prices are informational aggregates refreshed about daily from marketplace data, and Scryfall states plainly they should not be used for commerce. They are fine for a rough collection valuation; they are not a pricing feed, they lag real market moves, and a store or trading feature built on them will quote numbers that do not match what anything actually sells for.
• Set code plus collector number identify a printing; a card name identifies an oracle card that may have dozens of printings. /cards/named?exact=Lightning+Bolt returns one arbitrary printing, not the one your user owns. When the specific physical card matters, use /cards/{set}/{collector_number} — and store collector numbers as strings, since promos and variants carry letter and symbol suffixes like 123a.

Quick start (bash)

# same search syntax as the website: t:dragon f:commander cmc<=4
curl -s 'https://api.scryfall.com/cards/search?q=t%3Adragon+f%3Acommander+cmc%3C%3D4' | jq '.total_cards'
# for anything bulk, download the daily dump instead of paging the API
curl -s 'https://api.scryfall.com/bulk-data' | jq -r '.data[].download_uri'

Embed this badge

Add a live status badge to your README, docs, or website.

Markdown

[![Scryfall Status](https://api.freeapi.watch/badge/scryfall.svg)](https://freeapi.watch/scryfall)

HTML

<a href="https://freeapi.watch/scryfall"><img src="https://api.freeapi.watch/badge/scryfall.svg" alt="Scryfall Status"/></a>