TopDeck.gg API – Tournaments V2 Documentation

Documentation for getting data from TopDeck.gg's Tournaments V2 API

REST API URL: `https://topdeck.gg/api`

Usage Requirements

Free to Use

The TopDeck.gg API is free to use, providing access to a wealth of data for your projects and applications.

Rate Limits

You are limited to 200 requests per minute. Need a higher limit? E-mail us at [email protected].

Attribution

Any project using the API or data from the API must include proper attribution to TopDeck.gg. This includes a visible credit and a link back to TopDeck.gg.

Example Attribution:

<p>Data provided by <a href="https://topdeck.gg" target="_blank">TopDeck.gg</a></p>

By using the API, you agree to these usage requirements. Thank you for supporting TopDeck.gg!

Please acquire an API Key using the link below. All requests must include your API key in the Authorization header.

{
  "Authorization": "Your-API-Key"
}

Get API Key

POST /v2/tournaments

This endpoint retrieves information about completed tournaments. You can retrieve a variety of information, such as players, standings, decklists, matchups, and more. There are powerful filter options available.

Request

Body Parameters

TID: string | array of strings

The ID of the tournament. Can be a single string or an array of strings for multiple tournaments.

game: string

The name of the game for filtering tournaments. Case sensitive. See below.

format: string

The format of the game for filtering tournaments. Case sensitive. See below.

The following games and formats can be filtered. These must be passed to the game and format fields. They are case sensitive and must be passed exactly as written below.

Game	Format
Magic: The Gathering	EDH Pauper EDH Standard Pioneer Modern Legacy Pauper Vintage Premodern Limited Timeless Historic Explorer Oathbreaker
Pokemon	Standard Expanded Legacy
Yu-Gi-Oh	Advanced Edison Goat Domain
Star Wars Unlimited	Premier Draft
Lorcana	Leave format blank ("")
One Piece	Leave format blank ("")
Digimon	Leave format blank ("")
Marvel Snap	Leave format blank ("")
Shadowverse: Evolve	Leave format blank ("")
Flesh and Blood	Leave format blank ("")
Sorcery: Contested Realm	Leave format blank ("")
Altered	Leave format blank ("")

start: integer

The Unix timestamp (in seconds) indicating the earliest start date for the tournaments to be included in the response.

end: integer

The Unix timestamp (in seconds) indicating the latest end date for the tournaments to be included in the response.

last: integer

The number of days back from today to include tournaments.

participantMax: integer

The maximum number of participants to include.

participantMin: integer

The minimum number of participants to include.

columns: array of strings

An array specifying which player columns to include in the response. Default: ["decklist", "wins", "draws", "losses"]

[
  "name", // Name of the player
  "decklist", // URL of the player's decklist
  "deckSnapshot", // Object of player's decklist (Magic: The Gathering only)
  "commanders", // Array of player's commanders (Magic: The Gathering, EDH only)
  "wins", // Total wins by the player
  "winsSwiss", // Wins in the Swiss rounds
  "winsBracket", // Wins in the Bracket rounds
  "winRate", // Overall win rate
  "winRateSwiss", // Win rate in the Swiss rounds
  "winRateBracket", // Win rate in the Bracket rounds
  "draws", // Number of draws
  "losses", // Total losses by the player
  "lossesSwiss", // Losses in the Swiss rounds
  "lossesBracket", // Losses in the Bracket rounds
  "id" // Unique player identifier on TopDeck.gg
]

rounds: boolean | array of strings

An array specifying which round details to include in the response. This is default set to false. If set to true, the default is: ["round", "tables"]

[
  "round", // The round number or description (e.g., "Top 8")
  "tables" // Details about the tables in each round
]

tables: array of strings

An array specifying which table details to include in the response. Default: ["table", "players", "winner", "status"]

[
  "table", // The table number
  "players", // List of players at the table
  "winner", // The winner of the table
  "status" // Status of the table (e.g., "Completed")
]

players: array of strings

An array specifying which player details to include in the response. Default: ["name", "id", "decklist"]

[
  "name", // Name of the player
  "id", // Player ID
  "decklist" // URL of the player's decklist
]

Example Request

{
  "last": 30,
  "columns": ["decklist", "wins", "draws", "losses"],
  "rounds": true,
  "tables": ["table", "players", "winner"],
  "players": ["name", "id", "decklist"],
  "game": "Magic: The Gathering",
  "format": "EDH",
  "participantMax": 100,
  "participantMin": 10
}

Response

Success

[
  {
    "TID": "TournamentID",
    "tournamentName": "Tournament Name",
    "swissNum": 5,
    "startDate": 1627844461,
    "topCut": 10,
    "standings": [
      {
        "name": "Player Name",
        "id": "Player unique TopDeck.gg Id",
        "decklist": "Decklist URL",
        "wins": 5,
        "winsSwiss": 3,
        "winsBracket": 2,
        "winRate": 0.83,
        "winRateSwiss": 0.75,
        "winRateBracket": 1.00,
        "draws": 1,
        "losses": 2,
        "lossesSwiss": 1,
        "lossesBracket": 1
      },
      ...
    ],
    "rounds": [
      {
        "round": 1,
        "tables": [
          {
            "table": 1,
            "players": [
              {
                "name": "Player 1",
                "id": "Player1ID",
                "decklist": "Decklist URL"
              },
              {
                "name": "Player 2",
                "id": "Player2ID",
                "decklist": "Decklist URL"
              }
            ],
            "winner": "Player 1",
          },
          ...
        ]
      },
      ...
    ]
  }
]

GET /v2/tournaments/{TID}

This endpoint retrieves detailed information about a specific tournament, including tournament info, standings, and rounds.

Decklists will not appear in the response until the tournament is completed.

Discord Ids will not appear unless the tournament is using them.

Response

Success

{
  "data": {
    "name": "Tournament Name",
    "game": "Game Name",
    "format": "Game Format",
    "startDate": 1627844461
  },
  "standings": [
    {
      "standing": 1,
      "name": "Player Name",
      "discord": "Discord ID",
      "id": "Player ID",
      "decklist": "Decklist URL",
      "points": 15,
      "winRate": 0.8,
      "opponentWinRate": 0.6,
      "opponentGameWinRate": 0.7,
    },
    ...
  ],
  "rounds": [
    {
      "round": 1,
      "tables": [
        {
          "table": 1,
          "players": [
            {
              "name": "Player 1",
              "discord": "Discord ID",
              "id": "Player ID",
              "decklist": "Decklist URL"
            },
            {
              "name": "Player 2",
              "discord": "Discord ID",
              "id": "Player ID",
              "decklist": "Decklist URL"
            }
          ],
          "winner": "Player 1",
          "status": "Completed"
        },
        ...
      ]
    },
    ...
  ]
}

GET /v2/tournaments/{TID}/info

This endpoint retrieves detailed information about a specific tournament.

Response

Success

{
  "name": "Tournament Name",
  "game": "Game Name",
  "format": "Game Format",
  "startDate": 1627844461
}

GET /v2/tournaments/{TID}/standings

This endpoint retrieves the standings of a specific tournament.

Response

Success

[
  {
    "standing": 1,
    "name": "Player Name",
    "discord": "Discord ID",
    "id": "Player ID",
    "decklist": "Decklist URL",
    "points": 15,
    "opponentWinRate": 0.7,
    "gameWinRate": 0.75,
    "opponentGameWinRate": 0.65
  }
]

GET /v2/tournaments/{TID}/players/{ID}

This endpoint retrieves information about a specific player in a specific tournament.

Decklists will not appear in the response until the tournament is completed.

Discord Ids will not appear unless the tournament is using them.

Response

Success

{
  "name": "Player Name",
  "standing": 1,
  "decklist": "Decklist URL",
  "winRate": 0.83,
  "gamesPlayed": 10,
  "gamesWon": 8,
  "gamesDrawn": 1,
  "gamesLost": 1
}

GET /v2/tournaments/{TID}/rounds

This endpoint retrieves all rounds of a specific tournament.

Decklists will not appear in the response until the tournament is completed.

Discord Ids will not appear unless the tournament is using them.

Response

Success

[
  {
    "round": 1,
    "tables": [
      {
        "table": 1,
        "players": [
          {
            "name": "Player 1",
            "discord": "Discord ID",
            "id": "Player ID",
            "decklist": "Decklist URL"
          },
          {
            "name": "Player 2",
            "discord": "Discord ID",
            "id": "Player ID",
            "decklist": "Decklist URL"
          }
        ],
        "winner": "Player 1",
        "status": "Completed"
      }
    ]
  }
]

GET /v2/tournaments/{TID}/rounds/latest

This endpoint retrieves the latest round of a specific tournament.

Decklists will not appear in the response until the tournament is completed.

Discord Ids will not appear unless the tournament is using them.

Response

Success

[
  {
    "table": 1,
    "players": [
      {
        "name": "Player 1",
        "discord": "Discord ID",
        "id": "Player ID",
        "decklist": "Decklist URL"
      },
      {
        "name": "Player 2",
        "discord": "Discord ID",
        "id": "Player ID",
        "decklist": "Decklist URL"
      }
    ],
    "winner": "Player 1",
    "status": "Completed"
  }
]

Errors

You may receive the following errors when using the tournaments API.

Bad Request

{
  "status": 400,
  "error": "Both "game" and "format" fields are required."
}

Invalid API Key

{
  "status": 401,
  "error": "INVALID API KEY!"
}

Rate limit exceeded

{
  "status": 429,
  "error": "Rate limit Exceeded"
}

Internal Server Error

If you receive a 500 error, please contact us at [email protected].

{
  "status": 500,
  "error": "Internal Server Error"
}

TopDeck.gg API – Tournaments V2 Documentation

REST API URL: https://topdeck.gg/api

Usage Requirements

Free to Use

Rate Limits

Attribution

Required Header

POST /v2/tournaments

Request

Body Parameters

Games and Supported Formats

Example Request

Response

Success

GET /v2/tournaments/{TID}

Response

Success

GET /v2/tournaments/{TID}/info

Response

Success

GET /v2/tournaments/{TID}/standings

Response

Success

GET /v2/tournaments/{TID}/players/{ID}

Response

Success

GET /v2/tournaments/{TID}/rounds

Response

Success

GET /v2/tournaments/{TID}/rounds/latest

Response

Success

Errors

Bad Request

Invalid API Key

Rate limit exceeded

Internal Server Error

REST API URL: `https://topdeck.gg/api`