Deckbrew: A Magic: The Gathering API
Running Yourself
Deckbrew requires an existing Postgres database, accessible using DATABASE_URL.
A URL from Heroku or Amazon RDS will work. If you're running your own database,
setup it up using these commands.
CREATE DATABASE deckbrew WITH template=template0 encoding='UTF8'
Adding a new set
- Update the standard and modern format definitions
- Add the pricing name information to tcg player
API Documentation
The DeckBrew Magic: The Gathering API is open
source. Please report any issues
or bugs you encounter. This API wouldn't have been possible without the amazing
mtgjson and mtgimage resources.
All API access is over HTTPS, and accessed from the api.deckbrew.com
domain.
All data is sent and received as JSON.
Current Version
The DeckBrew API is currently in beta. Backwards incompatible changes
may be made at any time.
Content-Type: application/json
Requests that return multiple items will be paginated to 100 items by default.
You can specify further pages with the ?page
parameter.
$ curl https://api.deckbrew.com/mtg/cards?page=2
Note that page numbering is 1-based and that omitting the ?page
parameter
will return the first page.
The pagination info is included in the Link header. It is important to follow
these Link header values instead of constructing your own URLs.
Link: <https://api.deckbrew.com/mtg/cards?page=3>; rel="next",
<https://api.deckbrew.com/mtg/cards?page=1>; rel="prev"
The possible rel
values are:
Name |
Description |
next |
Shows the URL of the immediate next page of results. |
prev |
Shows the URL of the immediate previous page of results. |
Errors
Any response with a status code greater than or equal to 400 is considered an
error. An error object will be returned with an errors
key pointing to a list
of errors for a given request.
GET /mtg/page/not/found
{
"errors": [
"Card with ID '123' not found"
]
}
Magic Cards
List all cards
Return a list of all Magic cards. Can be filtered using query string parameters
to narrow the search.
GET /mtg/cards
[
{
name: "About Face",
id: "05194b17e11a7a45c7820c13f3ba8cbc",
url: "https://api.deckbrew.com/mtg/cards/05194b17e11a7a45c7820c13f3ba8cbc",
types: [
"instant"
],
colors: [
"red"
],
cmc: 1,
cost: "{R}",
text: "Switch target creature's power and toughness until end of turn.",
formats: {
commander: "legal",
legacy: "legal",
vintage: "legal"
},
editions: [
{
set: "Urza's Legacy",
rarity: "common",
artist: "Melissa A. Benson",
multiverse_id: 12414,
flavor: "The overconfident are the most vulnerable.",
number: "73",
layout: "normal",
url: "https://api.deckbrew.com/mtg/cards?multiverseid=12414",
image_url: "http://mtgimage.com/multiverseid/12414.jpg",
set_url: "https://api.deckbrew.com/mtg/sets/ULG"
}
]
}
]
Card filtering
Cards can be filtering using query string parameters. Parameters with the
same name are evaluated as OR statements. For example, the query below will
find all red or blue rare cards in Unhinged.
GET /mtg/cards?set=UNH&color=red&color=blue&rarity=rare
Name |
Type |
Description |
type |
[]string |
Any valid card type. Possible values include enchantment and |
subtype |
[]string |
Any valid card subtype. Possible values include zombie and tribal . |
supertype |
[]string |
Any valid card supertype, such as legendary |
name |
[]string |
A fuzzy match on a card's name |
oracle |
[]string |
A fuzzy match on a card's Oracle rules text |
set |
[]string |
A three letter identifier for a Magic set |
rarity |
[]string |
Select cards printed at this rarity. Options are common , uncommon , rare and mythic |
color |
[]string |
Select cards of the chosen color |
multiverseid |
[]string |
Select cards of that have at least one edition with the given Multiverse ID |
format |
[]string |
Only show cards from a format's card pool. Legal values are vintage , legacy , modern , standard , and commander |
status |
[]string |
Only show cards with the given status. Legal values are legal , banned or restricted |
Get cards for a Multiverse ID
A specific print of a card or cards identified by it's Multiverse
ID. By filtering on endpoint always returns
an array of cards, as certain prints contain for than one card, such as the
split card Turn // Burn.
Search examples
All red or blue rares with "fire" in their name:
https://api.deckbrew.com/mtg/cards?color=red&color=blue&rarity=rare&name=fire
All black zombies from Onslaught block:
https://api.deckbrew.com/mtg/cards?set=ons&set=scg&set=lgn&subtype=zombie&color=black
All cards that reference winning or lose the game
https://api.deckbrew.com/mtg/cards?oracle=win+the+game&oracle=lose+the+game
Get a single card
/mtg/cards/:id
{
name: "About Face",
id: "05194b17e11a7a45c7820c13f3ba8cbc",
url: "https://api.deckbrew.com/mtg/cards/05194b17e11a7a45c7820c13f3ba8cbc",
types: [
"instant"
],
colors: [
"red"
],
cmc: 1,
cost: "{R}",
text: "Switch target creature's power and toughness until end of turn.",
formats: {
commander: "legal",
legacy: "legal",
vintage: "legal"
},
editions: [
{
set: "Urza's Legacy",
rarity: "common",
artist: "Melissa A. Benson",
multiverse_id: 12414,
flavor: "The overconfident are the most vulnerable.",
number: "73",
layout: "normal",
url: "https://api.deckbrew.com/mtg/cards?multiverseid=12414",
image_url: "http://mtgimage.com/multiverseid/12414.jpg",
set_url: "https://api.deckbrew.com/mtg/sets/ULG"
}
]
}
Magic Sets
List all sets
GET /mtg/sets
[
{
"id": "ARB",
"name": "Alara Reborn",
"border": "black",
"type": "expansion",
"url": "https://api.deckbrew.com/mtg/sets/ARB",
"cards_url": "https://api.deckbrew.com/mtg/cards?set=ARB"
}
]
Get a single set
GET /mtg/sets/:id
{
"id": "ARB",
"name": "Alara Reborn",
"border": "black",
"type": "expansion",
"url": "https://api.deckbrew.com/mtg/sets/ARB",
"cards_url": "https://api.deckbrew.com/mtg/cards?set=ARB"
}
Magic Types and Colors
These endpoints provide a list of possible values for specific search terms.
List all types
GET /mtg/types
[
"artifact",
"creature",
"enchantment",
"instant",
"land",
"phenomenon",
"plane",
"planeswalker",
"scheme",
"sorcery",
"tribal",
"vanguard"
]
List all supertypes
GET /mtg/supertypes
[
"basic",
"legendary",
"ongoing",
"snow",
"world"
]
List all subtypes
GET /mtg/subtypes
[
"advisor",
"ajani",
"alara",
"ally",
"angel",
"anteater",
]
List all colors
GET /mtg/colors
[
"black",
"blue",
"green",
"red",
"white"
]