MTGGraphQL

MTGGraphQL is a service of MTGJSON and a GraphQL API built on top of the MTGJSON data sets. The goal being to reduce the amount of unnecessary data retrieved and empowering users to ask for exactly what they need from the GraphQL service. This will also allow us to connect future projects and changes under a single API that can evolve over time. While more data is in the works, the current service focuses on these JSON payloads:

• Cards
• Decks
• Imagery
• Sets
• Metadata
• Prices

Beta Information

The beta rollout of the service will be available to all Patreon subscribers with the goal of bringing a version to the rest of the community in the near future. Feel free to submit suggestions on our Discord.

Usage

Endpoint

Every query is a POST request to a single endpoint:

• https://graphql.mtgjson.com/

The request body is JSON containing a query property, and the response is JSON containing a data property. Visiting the endpoint in a browser loads the GraphQL Playground instead.

Authorization

Send your access token in an authorization header on every request:

{
  "authorization": "Bearer <Access Token>"
}

Access tokens are issued to Patreon subscribers while the service is in beta. To get one:

1. Subscribe to MTGJSON on Patreon.
2. Join our Discord.
3. Ask us for an access token, and we will issue one for your account.

Data Source

MTGGraphQL is based on the latest MTGJSON release. For the timings of data updates, see this FAQ question.

Rate Limits

The current rate limits are capped at 1,000 requests per IP Address per hour and 500 requests per access token per hour.

Querying Outside of the Playground

Any HTTP client can talk to the endpoint. Here is the same query using curl:

curl https://graphql.mtgjson.com/ \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <Access Token>' \
  -d '{"query": "query { cards(filter: { name_eq: \"Phelddagrif\" }, page: { take: 100, skip: 0 }) { name setCode type } }"}'

And the same query from JavaScript or TypeScript:

const response = await fetch('https://graphql.mtgjson.com/', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    authorization: 'Bearer <Access Token>',
  },
  body: JSON.stringify({
    query: `query {
      cards(filter: { name_eq: "Phelddagrif" }, page: { take: 100, skip: 0 }) {
        name
        setCode
        type
      }
    }`,
  }),
});

const { data } = await response.json();

NPM TypeScript Package

To go along with MTGGraphQL, we have released a NPM TypeScript Package for your convenience.

Client-based Querying

You can utilize a tool like Apollo to make Client-based calls.

GraphQL Playground

We provide a GraphQL Playground where you can query the server and get a response.

The playground consists of 3 main sections:

• The top left, for your query
• The bottom left tabs, containing HTTP HEADERS for your authorization
• The right, which has the server response

Example Query

query {
  cards(
    filter: { name_eq: "Phelddagrif" }
    page: { take: 100, skip: 0 }
    order: { order: ASC }
  ) {
    name
    setCode
    type
    text
    prices {
      provider
      date
      cardType
      listType
      price
    }
  }
}

Example HTTP Headers Authorization

Paste your access token into the HTTP HEADERS tab so the playground can authorize your query. See Authorization if you do not have a token yet.

{
  "authorization": "Bearer <Access Token>"
}

Example Response

Here is a reduced payload the example response:

{
  "data": {
    "cards": [
      {
        "name": "Phelddagrif",
        "setCode": "ALL",
        "type": "Legendary Creature — Phelddagrif",
        "text": "{G}: Phelddagrif gains trample until end of turn. Target opponent creates a 1/1 green Hippo creature token.\n{W}: Phelddagrif gains flying until end of turn. Target opponent gains 2 life.\n{U}: Return Phelddagrif to its owner's hand. Target opponent may draw a card.",
        "prices": [
          {
            "provider": "cardkingdom",
            "date": "2023-08-15",
            "cardType": "normal",
            "listType": "buylist",
            "price": 5.5
          },
          {
            "provider": "cardkingdom",
            "date": "2023-08-15",
            "cardType": "normal",
            "listType": "retail",
            "price": 9.99
          },
          {
            "provider": "cardmarket",
            "date": "2023-08-15",
            "cardType": "normal",
            "listType": "retail",
            "price": 8.95
          },
          {
            "provider": "tcgplayer",
            "date": "2023-08-15",
            "cardType": "normal",
            "listType": "retail",
            "price": 10.05
          },
          {
            "provider": "tcgplayer",
            "date": "2023-08-15",
            "cardType": "normal",
            "listType": "buylist",
            "price": 7.54
          },
          {
            "provider": "cardsphere",
            "date": "2023-08-15",
            "cardType": "normal",
            "listType": "retail",
            "price": 10.25
          }
        ]
      },
      {
        "name": "Phelddagrif",
        "setCode": "ME1",
        "type": "Legendary Creature — Phelddagrif",
        "text": "{G}: Phelddagrif gains trample until end of turn. Target opponent creates a 1/1 green Hippo creature token.\n{W}: Phelddagrif gains flying until end of turn. Target opponent gains 2 life.\n{U}: Return Phelddagrif to its owner's hand. Target opponent may draw a card.",
        "prices": [
          {
            "provider": "cardhoarder",
            "date": "2023-08-15",
            "cardType": "normal",
            "listType": "retail",
            "price": 0.03
          },
          {
            "provider": "cardhoarder",
            "date": "2023-08-15",
            "cardType": "foil",
            "listType": "retail",
            "price": 1.82
          }
        ]
      }
    ]
  }
}

You can use the this embedded playground to run this specific example query without the need of an access token: