TopDeck.gg API – Tournaments V2 Documentation

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!

Required Header

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

{
  "Authorization": "Your-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

Note: When "decklist" is included in columns, the response will also include deckObj fields when structured deck data is available.

Parameters

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

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

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

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

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

The number of days back from today to include tournaments.

The maximum number of participants to include.

The minimum number of participants to include.

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

[
  "name", // Name of the player
  "decklist", // String or URL of the player's decklist (also includes deckObj when available)
  "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
  "byes", // Byes received in the tournament
  "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
]

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
]

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

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

[
  "name", // Name of the player
  "id", // Player ID
  "decklist" // String or URL of the player's decklist (also includes deckObj when available)
]

Example Request

{
  "last": 30,
  "columns": ["name", "decklist", "wins", "draws", "losses"],
  "rounds": true,
  "tables": ["table", "players", "winner", "status"],
  "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,
    "game": "Magic: The Gathering",
    "format": "EDH",
    "topCut": 8,
    "eventData": {
      "lat": 40.7128,
      "lng": -74.0060,
      "city": "New York",
      "state": "NY",
      "location": "Local Game Store",
      "headerImage": "https://example.com/images/tournament.png"
    },
    "standings": [
      {
        "name": "Player Name",
        "id": "Player1UID",
        "decklist": "~~Commanders~~\\n1 Rograkh, Son of Rohgahh\\n1 Silas Renn, Seeker Adept\\n\\n~~Mainboard~~\\n1 Mana Crypt\\n1 Underworld Breach\\n...",
        "deckObj": {
          "Commanders": {
            "Rograkh, Son of Rohgahh": {
              "id": "584cee10-f18c-4633-95cc-f2e7a11841ac",
              "count": 1
            },
            "Silas Renn, Seeker Adept": {
              "id": "0dc78b1e-581e-4f28-bf35-e2082553d6a9",
              "count": 1
            }
          },
          "Mainboard": {
            "Mana Crypt": {
              "id": "0cb33b46-4d60-4ce7-8c78-0c2c7c0bb7a3",
              "count": 1
            },
            "Underworld Breach": {
              "id": "27e0948b-9916-473b-8d8c-a51bdfbc7457",
              "count": 1
            }
          }
        },
        "wins": 4,
        "draws": 1,
        "losses": 0
      }
    ],
    "rounds": [
      {
        "round": 1,
        "tables": [
          {
            "table": 1,
            "players": [
              {
                "name": "Player 1",
                "id": "Player1UID",
                "decklist": "~~Commanders~~\\n1 Rograkh, Son of Rohgahh\\n1 Silas Renn, Seeker Adept\\n\\n~~Mainboard~~\\n1 Mana Crypt\\n1 Underworld Breach\\n...",
                "deckObj": {
                  "Commanders": {
                    "Rograkh, Son of Rohgahh": {
                      "id": "584cee10-f18c-4633-95cc-f2e7a11841ac",
                      "count": 1
                    },
                    "Silas Renn, Seeker Adept": {
                      "id": "0dc78b1e-581e-4f28-bf35-e2082553d6a9",
                      "count": 1
                    }
                  },
                  "Mainboard": {
                    "Mana Crypt": {
                      "id": "0cb33b46-4d60-4ce7-8c78-0c2c7c0bb7a3",
                      "count": 1
                    },
                    "Underworld Breach": {
                      "id": "27e0948b-9916-473b-8d8c-a51bdfbc7457",
                      "count": 1
                    }
                  }
                }
              },
              {
                "name": "Player 2",
                "id": "Player2UID",
                "decklist": "~~Commanders~~\\n1 Thrasios, Triton Hero\\n1 Tymna the Weaver\\n\\n~~Mainboard~~\\n1 Mana Crypt\\n...",
                "deckObj": null
              }
            ],
            "winner": "Player 1",
            "status": "Completed"
          }
        ]
      }
    ]
  }
]

Field Descriptions

Tournament Level Fields

eventData Fields

Standings Fields (Conditional)

The standings array contains objects with fields based on the "columns" parameter:

GET /v2/tournaments/{TID}

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

Note: This endpoint returns all tournament data in a single response for efficiency.

Conditional Fields

• Decklists: Only appear when the tournament has ended OR the organizer has enabled "Show Decks"
• deckObj: Only included when structured deck data is available
• Discord fields: Only appear when the tournament is configured to include Discord information
• Win rate fields: Field names vary by tournament type (League tournaments use "successRate" instead of "winRate")

Response

Success

{
  "data": {
    "name": "Tournament Name",
    "game": "Magic: The Gathering", 
    "format": "EDH",
    "startDate": 1627844461
  },
  "standings": [
    {
      "standing": 1,
      "name": "Player Name",
      "discord": "Discord Username",
      "discordId": "123456789",
      "id": "Player ID",
      "decklist": "~~Commanders~~\\n1 Rograkh, Son of Rohgahh\\n1 Silas Renn, Seeker Adept\\n\\n~~Mainboard~~\\n1 Mana Crypt\\n1 Underworld Breach\\n...",
      "deckObj": {
        "Commanders": {
          "Rograkh, Son of Rohgahh": {
            "id": "584cee10-f18c-4633-95cc-f2e7a11841ac",
            "count": 1
          },
          "Silas Renn, Seeker Adept": {
            "id": "0dc78b1e-581e-4f28-bf35-e2082553d6a9",
            "count": 1
          }
        },
        "Mainboard": {
          "Mana Crypt": {
            "id": "0cb33b46-4d60-4ce7-8c78-0c2c7c0bb7a3",
            "count": 1
          },
          "Underworld Breach": {
            "id": "27e0948b-9916-473b-8d8c-a51bdfbc7457",
            "count": 1
          }
        }
      },
      "points": 15,
      "winRate": 0.8,
      "opponentWinRate": 0.6,
      "gameWinRate": 0.75,
      "opponentGameWinRate": 0.65
    }
  ],
  "rounds": [
    {
      "round": 1,
      "tables": [
        {
          "table": 1,
          "players": [
            {
              "name": "Player 1",
              "discord": "discord_username",
              "discordId": "123456789",
              "id": "Player1ID",
              "decklist": "~~Commanders~~\\n1 Rograkh, Son of Rohgahh\\n1 Silas Renn, Seeker Adept\\n\\n~~Mainboard~~\\n1 Mana Crypt\\n1 Underworld Breach\\n...",
              "deckObj": null
            },
            {
              "name": "Player 2", 
              "discord": null,
              "discordId": null,
              "id": "Player2ID",
              "decklist": "~~Commanders~~\\n1 Thrasios, Triton Hero\\n1 Tymna the Weaver\\n\\n~~Mainboard~~\\n1 Mana Crypt\\n...",
              "deckObj": null
            }
          ],
          "winner": "Player 1",
          "winner_id": "Player1ID",
          "status": "Completed"
        },
        {
          "table": "Byes",
          "players": [
            {
              "name": "Player 3",
              "discord": null,
              "discordId": null,
              "id": "Player3ID",
              "decklist": null,
              "deckObj": null
            }
          ],
          "status": "Bye"
        }
      ]
    }
  ]
}

Field Descriptions

Top Level Fields

data Object Fields

GET /v2/tournaments/{TID}/info

This endpoint retrieves basic information about a specific tournament.

Response

Success

{
  "name": "Tournament Name",
  "game": "Magic: The Gathering",
  "format": "EDH",
  "startDate": 1627844461
}

Field Descriptions

GET /v2/tournaments/{TID}/standings

This endpoint retrieves the standings of a specific tournament.

Conditional Fields

• Decklists: Only appear when the tournament has ended OR organizer has enabled "Show Decks"
• deckObj: Only included when structured deck data is available
• Discord fields: Only appear when the tournament is configured to include Discord information
• Win rate fields: League tournaments use "successRate"/"opponentSuccessRate", others use "winRate"/"opponentWinRate"
• Game win rates: Only appear in Pairs mode tournaments

Response

Success (Standard Tournament)

[
  {
    "standing": 1,
    "name": "Player Name",
    "discord": "discord_username",
    "discordId": "123456789",
    "id": "Player ID",
    "decklist": "~~Commanders~~\\n1 Rograkh, Son of Rohgahh\\n1 Silas Renn, Seeker Adept\\n\\n~~Mainboard~~\\n1 Mana Crypt\\n1 Underworld Breach\\n...",
    "deckObj": {
      "Commanders": {
        "Rograkh, Son of Rohgahh": {
          "id": "584cee10-f18c-4633-95cc-f2e7a11841ac",
          "count": 1
        },
        "Silas Renn, Seeker Adept": {
          "id": "0dc78b1e-581e-4f28-bf35-e2082553d6a9",
          "count": 1
        }
      },
      "Mainboard": {
        "Mana Crypt": {
          "id": "0cb33b46-4d60-4ce7-8c78-0c2c7c0bb7a3",
          "count": 1
        },
        "Underworld Breach": {
          "id": "27e0948b-9916-473b-8d8c-a51bdfbc7457",
          "count": 1
        }
      }
    },
    "points": 15,
    "winRate": 0.83,
    "opponentWinRate": 0.7
  }
]

Success (League Tournament)

[
  {
    "standing": 1,
    "name": "Player Name", 
    "id": "Player ID",
    "points": 15,
    "successRate": 0.83,
    "opponentSuccessRate": 0.7
  }
]

Success (Pairs Mode Tournament)

[
  {
    "standing": 1,
    "name": "Player Name",
    "id": "Player ID", 
    "points": 15,
    "winRate": 0.83,
    "opponentWinRate": 0.7,
    "gameWinRate": 0.75,
    "opponentGameWinRate": 0.65
  }
]

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

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

Conditional Fields

• Decklists: Only appear when the tournament has ended OR organizer has enabled "Show Decks"
• deckObj: Only included when structured deck data is available
• Decklist format: The decklist field can be either a URL or a text string depending on when the tournament was created

Response

Success

{
  "name": "Player Name",
  "standing": 1,
  "decklist": "~~Commanders~~\\n1 Rograkh, Son of Rohgahh\\n1 Silas Renn, Seeker Adept\\n\\n~~Mainboard~~\\n1 Mana Crypt\\n1 Underworld Breach\\n...",
  "deckObj": {
    "Commanders": {
      "Rograkh, Son of Rohgahh": {
        "id": "584cee10-f18c-4633-95cc-f2e7a11841ac",
        "count": 1
      },
      "Silas Renn, Seeker Adept": {
        "id": "0dc78b1e-581e-4f28-bf35-e2082553d6a9",
        "count": 1
      }
    },
    "Mainboard": {
      "Mana Crypt": {
        "id": "0cb33b46-4d60-4ce7-8c78-0c2c7c0bb7a3",
        "count": 1
      },
      "Underworld Breach": {
        "id": "27e0948b-9916-473b-8d8c-a51bdfbc7457",
        "count": 1
      }
    }
  },
  "winRate": 0.83,
  "gamesPlayed": 10,
  "gamesWon": 8,
  "byes": 0,
  "gamesDrawn": 1,
  "gamesLost": 1
}

Field Descriptions

deckObj Structure

The deckObj field contains structured decklist information when available:

GET /v2/tournaments/{TID}/rounds

This endpoint retrieves all rounds of a specific tournament.

Conditional Fields

• Decklists: Only appear when the tournament has ended OR organizer has enabled "Show Decks"
• deckObj: Only included when structured deck data is available
• Discord fields: Only appear when the tournament is configured to include Discord information

Response

Success

[
  {
    "round": 1,
    "tables": [
      {
        "table": 1,
        "players": [
          {
            "name": "Player 1",
            "discord": "discord_username",
            "discordId": "123456789",
            "id": "Player1ID",
            "decklist": "~~Commanders~~\\n1 Rograkh, Son of Rohgahh\\n1 Silas Renn, Seeker Adept\\n\\n~~Mainboard~~\\n1 Mana Crypt\\n1 Underworld Breach\\n...",
            "deckObj": null
          },
          {
            "name": "Player 2",
            "discord": null,
            "discordId": null,
            "id": "Player2ID",
            "decklist": "~~Commanders~~\\n1 Thrasios, Triton Hero\\n1 Tymna the Weaver\\n\\n~~Mainboard~~\\n1 Mana Crypt\\n...",
            "deckObj": null
          }
        ],
        "winner": "Player 1",
        "winner_id": "Player1ID",
        "status": "Completed"
      },
      {
        "table": "Byes",
        "players": [
          {
            "name": "Player 3",
            "discord": null,
            "discordId": null,
            "id": "Player3ID",
            "decklist": null,
            "deckObj": null
          }
        ],
        "status": "Bye"
      }
    ]
  },
  {
    "round": "Top 8",
    "tables": [
      {
        "table": 1,
        "players": [
          {
            "name": "Player 1",
            "discord": "discord_username",
            "discordId": "123456789", 
            "id": "Player1ID",
            "decklist": "~~Commanders~~\\n1 Rograkh, Son of Rohgahh\\n1 Silas Renn, Seeker Adept\\n\\n~~Mainboard~~\\n1 Mana Crypt\\n1 Underworld Breach\\n...",
            "deckObj": null
          },
          {
            "name": "Player 4",
            "discord": null,
            "discordId": null,
            "id": "Player4ID",
            "decklist": null,
            "deckObj": null
          }
        ],
        "winner": null,
        "winner_id": "Draw",
        "status": "Completed"
      }
    ]
  }
]

Field Descriptions

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

This endpoint retrieves the current/latest round of a specific tournament.

Conditional Fields

• Decklists: Only appear when the tournament has ended OR organizer has enabled "Show Decks"
• deckObj: Only included when structured deck data is available
• Discord fields: Only appear when the tournament is configured to include Discord information

Response

Success

[
  {
    "table": 1,
    "players": [
      {
        "name": "Player 1",
        "discord": "discord_username",
        "discordId": "123456789",
        "id": "Player1ID",
        "decklist": "https://example.com/deck1",
        "deckObj": null
      },
      {
        "name": "Player 2",
        "discord": null,
        "discordId": null,
        "id": "Player2ID",
        "decklist": "https://example.com/deck2",
        "deckObj": null
      }
    ],
    "winner": "Player 1",
    "winner_id": "Player1ID",
    "status": "Completed"
  },
  {
    "table": 2,
    "players": [
      {
        "name": "Player 3",
        "discord": null,
        "discordId": null,
        "id": "Player3ID",
        "decklist": null,
        "deckObj": null
      },
      {
        "name": "Player 4",
        "discord": "discord_user4",
        "discordId": "987654321",
        "id": "Player4ID",
        "decklist": null,
        "deckObj": null
      }
    ],
    "winner": null,
    "winner_id": null,
    "status": "Pending"
  },
  {
    "table": "Byes",
    "players": [
      {
        "name": "Player 5",
        "discord": null,
        "discordId": null,
        "id": "Player5ID",
        "decklist": null,
        "deckObj": null
      }
    ],
    "status": "Bye"
  }
]

GET /v2/tournaments/{TID}/attendees

This endpoint retrieves all attendees for a specific tournament, including registered players, dropped players, and waitlisted users.

⚠️ Staff Only: This endpoint requires tournament staff permissions.

Authorization

Only tournament staff with permissions on the specific tournament can access this endpoint.

Unauthorized users will receive a 403 Forbidden error.

Response

Success

[
  {
    "uid": "player123",
    "name": "John Doe",
    "email": "[email protected]",
    "discord": "johndoe",
    "discordId": "123456789",
    "status": "player",
    "standing": 1,
    "decklist": "~~Commanders~~\\n1 Rograkh, Son of Rohgahh\\n1 Silas Renn, Seeker Adept\\n\\n~~Mainboard~~\\n1 Mana Crypt\\n1 Underworld Breach\\n...",
    "deckObj": {
      "Commanders": {
        "Rograkh, Son of Rohgahh": {
          "id": "584cee10-f18c-4633-95cc-f2e7a11841ac",
          "count": 1
        }
      },
      "Mainboard": {
        "Mana Crypt": {
          "id": "0cb33b46-4d60-4ce7-8c78-0c2c7c0bb7a3",
          "count": 1
        }
      }
    }
  },
  {
    "uid": "player456",
    "name": "Jane Smith",
    "email": "[email protected]",
    "discord": "janesmith",
    "discordId": "987654321",
    "status": "dropped",
    "standing": null,
    "decklist": "https://example.com/deck2",
    "deckObj": null
  },
  {
    "uid": "waitlist789",
    "name": "Bob Wilson",
    "email": "[email protected]",
    "discord": "bobwilson",
    "discordId": "456789123",
    "status": "waitlist",
    "standing": null,
    "decklist": null,
    "deckObj": null,
    "joinedAt": 1627844461,
    "waitlistStatus": "waiting",
    "waitlistPosition": 1,
    "offeredAt": null,
    "expirationTimestamp": null
  }
]

Field Descriptions

Waitlist-Specific Fields

These additional fields are included for users with status "waitlist":

Error Responses

Forbidden (403)

{
  "error": "Forbidden: Insufficient permissions"
}

Not Found (404)

{
  "error": "Tournament not found"
}