deckbrew

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

Pagination

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.

Link Header

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:

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

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"
]