TopDeck.gg API

Complete reference for TopDeck.gg's tournaments API. Access data on tournaments, players, and standings. Seamlessly integrate tournament data into your projects.

Tournaments · Players · Standings · Decklists · Free REST API

OpenAPI Spec

Usage Requirements

The TopDeck.gg API is free to use, providing tournament data for your projects and applications.

Rate Limits

Most endpoints allow 100 requests per minute. Heavier endpoints like bulk tournament queries have lower limits. You'll receive a 429 response if you exceed your limit. Need more? E-mail us at contact@topdeck.gg.

Attribution Required

Any project using the API must include a visible credit and link back to TopDeck.gg. See the attribution example on the right.

Info

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

Quick Start

curl https://topdeck.gg/api/v2/tournaments \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"game": "Magic: The Gathering", "format": "Standard", "start": 1700000000}'

Attribution Example

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

Authentication

All endpoints use the following base URL:

https://topdeck.gg/api

Every request must include your API key in the Authorization header. Keys are free — create one from your account page.

Get API Key

Example Request

curl https://topdeck.gg/api/v2/tournaments \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"game": "Magic: The Gathering", "format": "Standard"}'

Header Format

{
  "Authorization": "YOUR_API_KEY",
  "Content-Type": "application/json"
}

POST/v2/tournaments

Search and retrieve information about completed tournaments — players, standings, decklists, matchups, and more. Powerful filter options available.

Body Parameters

Note

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

TID: string | array of strings

Tournament ID. Can be a single string or an array for multiple tournaments.

game: string

Game name for filtering. Case sensitive.

format: string

Game format for filtering. Case sensitive.

These must be passed exactly as written below (case sensitive).

Game	Format
Magic: The Gathering	EDH Pauper EDH Standard Pioneer Modern Legacy Pauper Vintage Premodern Sealed Limited Duel Commander Old School 93/94 Canadian Highlander Tiny Leaders EDH Draft Timeless Historic Explorer 7pt Highlander Oathbreaker
Pokemon	Standard Expanded Legacy GLC
Yu-Gi-Oh	Edison Goat Advanced HAT REDU Genesys Domain
One Piece	Leave format blank ("")
Gundam TCG	Leave format blank ("")
Union Arena	Leave format blank ("")
Star Wars Unlimited	Premier Draft Twin Suns
Disney Lorcana	Core Constructed Infinity Constructed Sealed Pack Rush
Riftbound	Constructed 2v2 Free-for-All
Marvel Snap	Leave format blank ("")
Overpower	Modern Draft Sealed Legacy Mixed Modern Skirmish Legacy Skirmish
Naruto Mythos TCG	Release Event Pre-Release Event Local Tournament Store Championship Regional Standard
Cyberpunk TCG	Leave format blank ("")
Chrono Core TCG	Weekly Arena Crossfire Realm Showdown Realm Championship
Beyblade	X
Cardfight Vanguard	Standard Premium VPremium
Digimon	Leave format blank ("")
Flesh and Blood	Leave format blank ("")
Shadowverse: Evolve	Leave format blank ("")
Sorcery: Contested Realm	Leave format blank ("")
Altered	Standard Draft
CookieRun: Braverse TCG	Casual Constructed Draft Sealed Learn to Play Pre-Release
Rush of Ikorr	Standard
Lairen: La Historia	Leave format blank ("")
Five Mics	Leave format blank ("")
Settlers of Catan	Leave format blank ("")
Gudnak	Leave format blank ("")
Hadrai'da Ascendant	Conquest Duel Conquest Tag Team Conquest Squads Conquest Battle Royale Gladiator Duel Gladiator Tag Team Gladiator Squads

start: integer

Unix timestamp (seconds) — earliest tournament start date.

end: integer

Unix timestamp (seconds) — latest tournament end date.

last: integer

Number of days back from today to include.

participantMax: integer

Maximum number of participants.

participantMin: integer

Minimum number of participants.

columns: array of strings

Player columns to include. Default: ["decklist", "wins", "draws", "losses"]

Options: name, decklist, wins, winsSwiss, winsBracket, winRate, winRateSwiss, winRateBracket, byes, draws, losses, lossesSwiss, lossesBracket, id

rounds: boolean | array of strings

Round details to include. Default: false. If true, returns ["round", "tables"].

tables: array of strings

Table details to include. Default: ["table", "players", "winner", "status"]

players: array of strings

Player details within rounds. Default: ["name", "id"]

Response Fields

Tournament Level

Field	Type	Description
TID	string	Tournament identifier
tournamentName	string	Name of the tournament
swissNum	number	Number of Swiss rounds played
startDate	number	Unix timestamp of tournament start
game	string	Game being played
format	string	Game format
topCut	number	Size of the top cut bracket (0 if none)
eventData	object	Location details (lat, lng, city, state, location, headerImage)
standings	array	Player standings (based on columns param)
rounds	array	Round data (when rounds param is included)

Request

{
  "game": "Magic: The Gathering",
  "format": "EDH",
  "last": 30,
  "columns": ["name", "decklist", "wins", "draws", "losses"],
  "rounds": true
}

Response

[
  {
    "TID": "abc123",
    "tournamentName": "Weekly EDH",
    "swissNum": 5,
    "startDate": 1627844461,
    "game": "Magic: The Gathering",
    "format": "EDH",
    "topCut": 8,
    "eventData": {
      "city": "New York",
      "state": "NY",
      "location": "Local Game Store"
    },
    "standings": [
      {
        "name": "Player Name",
        "decklist": "~~Commanders~~\n...",
        "wins": 4,
        "draws": 1,
        "losses": 0
      }
    ],
    "rounds": [
      {
        "round": 1,
        "tables": [{ ... }]
      }
    ]
  }
]

GET/v2/my-tournaments

Returns all tournaments owned by the authenticated API key holder. By default, only upcoming tournaments are returned.

Note

Requires a TopDeck subscription and at least one tournament created on your account.

Query Parameters

Parameter	Type	Default	Description
filter	string	upcoming	Set to `all` to include past tournaments.

Response Fields

Field	Type	Description
tid	string	Tournament ID
name	string	Tournament name
game	string	Game being played
format	string	Game format
startDate	number	Unix timestamp of start
endDate	number \| null	Unix timestamp of end
status	string	`Complete`, `Ongoing`, or `Not Started`
location	object \| null	Location details (name, city, state, country, lat, lng)
headerImage	string \| null	URL of event header image

Response

[
  {
    "tid": "abc123",
    "name": "Weekly Modern",
    "game": "Magic: The Gathering",
    "format": "Modern",
    "startDate": 1627844461,
    "endDate": 1627855261,
    "status": "Not Started",
    "location": {
      "name": "Card Kingdom Seattle",
      "city": "Seattle",
      "state": "WA",
      "country": "US"
    },
    "headerImage": "https://..."
  }
]

GET/v2/tournaments/{TID}

Retrieve detailed information about a specific tournament — info, standings, and all rounds in a single response.

Conditional Fields

Decklists: Only when tournament has ended OR organizer enabled "Show Decks"
deckObj: Only when structured deck data is available
Discord fields: Only when tournament includes Discord info
Win rate fields: League tournaments use "successRate" instead of "winRate"

Response Fields

Top Level

Field	Type	Description
data	object	Tournament info (name, game, format, startDate)
standings	array	Player standings with detailed stats
rounds	array	All rounds with table details

Response

{
  "data": {
    "name": "Tournament Name",
    "game": "Magic: The Gathering",
    "format": "EDH",
    "startDate": 1627844461
  },
  "standings": [
    {
      "standing": 1,
      "name": "Player Name",
      "id": "abc123",
      "points": 15,
      "winRate": 0.8,
      "opponentWinRate": 0.6
    }
  ],
  "rounds": [
    {
      "round": 1,
      "tables": [{ ... }]
    }
  ]
}

GET/v2/tournaments/{TID}/info

Retrieve basic tournament information including location and scheduling details.

Response Fields

Field	Type	Description
tid	string	Tournament ID
name	string	Tournament name
game	string	Game being played
format	string	Game format
startDate	number	Unix timestamp of start
endDate	number \| null	Unix timestamp of end
status	string	`Complete`, `Ongoing`, or `Not Started`
location	object \| null	Location details (name, city, state, country, lat, lng)
headerImage	string \| null	URL of event header image

Response

{
  "tid": "abc123",
  "name": "Tournament Name",
  "game": "Magic: The Gathering",
  "format": "EDH",
  "startDate": 1627844461,
  "endDate": 1627855261,
  "status": "Complete",
  "location": {
    "name": "Card Kingdom Seattle",
    "city": "Seattle",
    "state": "WA",
    "country": "US"
  },
  "headerImage": "https://..."
}

GET/v2/tournaments/{TID}/standings

Retrieve standings for a specific tournament.

Conditional Fields

Decklists: Only when tournament has ended OR organizer enabled "Show Decks"
deckObj: Only when structured deck data is available
Discord fields: Only when tournament includes Discord info
Win rate fields: League tournaments use successRate / opponentSuccessRate
Game win rates: Only in Pairs mode tournaments (gameWinRate, opponentGameWinRate)

Standard Tournament

[
  {
    "standing": 1,
    "name": "Player Name",
    "id": "abc123",
    "decklist": "~~Commanders~~\n...",
    "deckObj": { ... },
    "points": 15,
    "winRate": 0.83,
    "opponentWinRate": 0.7
  }
]

League Tournament

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

Pairs Mode

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

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

Retrieve detailed information about a specific player in a tournament.

Conditional Fields

Decklists: Only when tournament has ended OR organizer enabled "Show Decks"
deckObj: Only when structured deck data is available
Decklist format: Can be either a URL or text string

Response Fields

Field	Type	Description
name	string	Player's display name
standing	number	Current tournament standing
decklist	string \| undefined	Decklist as text or URL
deckObj	object \| undefined	Structured deck data
winRate	number	Overall win rate (0.0–1.0)
gamesPlayed	number	Total games played
gamesWon	number	Total games won
byes	number	Byes received
gamesDrawn	number	Total draws
gamesLost	number	Total losses

Response

{
  "name": "Player Name",
  "standing": 1,
  "decklist": "~~Commanders~~\n...",
  "deckObj": {
    "Commanders": { ... },
    "Mainboard": { ... }
  },
  "winRate": 0.83,
  "gamesPlayed": 10,
  "gamesWon": 8,
  "byes": 0,
  "gamesDrawn": 1,
  "gamesLost": 1
}

GET/v2/tournaments/{TID}/rounds

Retrieve all rounds of a specific tournament.

Conditional Fields

Decklists: Only when tournament has ended OR organizer enabled "Show Decks"
deckObj: Only when structured deck data is available
Discord fields: Only when tournament includes Discord info

Response Fields

Field	Type	Description
round	number \| string	Round number or bracket label (e.g. "Top 8")
table	number \| "Byes"	Table number or "Byes" for bye assignments
winner	string \| null	Winner's name (null for draws)
winner_id	string \| "Draw" \| null	Winner's ID, "Draw" for ties, null for unfinished
status	string	"Completed", "Active", "Pending", or "Bye"

Response

[
  {
    "round": 1,
    "tables": [
      {
        "table": 1,
        "players": [
          { "name": "Player 1", "id": "abc" },
          { "name": "Player 2", "id": "def" }
        ],
        "winner": "Player 1",
        "winner_id": "abc",
        "status": "Completed"
      }
    ]
  },
  {
    "round": "Top 8",
    "tables": [{ ... }]
  }
]

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

Retrieve the current/latest round of a specific tournament. Returns the same table structure as the rounds endpoint, but only for the most recent round.

Conditional Fields

Decklists: Only when tournament has ended OR organizer enabled "Show Decks"
deckObj: Only when structured deck data is available
Discord fields: Only when tournament includes Discord info

Response

[
  {
    "table": 1,
    "players": [
      { "name": "Player 1", "id": "abc" },
      { "name": "Player 2", "id": "def" }
    ],
    "winner": "Player 1",
    "winner_id": "abc",
    "status": "Completed"
  },
  {
    "table": "Byes",
    "players": [
      { "name": "Player 5", "id": "ghi" }
    ],
    "status": "Bye"
  }
]

GET/v2/tournaments/{TID}/attendees

Retrieve all attendees for a tournament — registered players, dropped players, and waitlisted users.

Staff Only

This endpoint requires tournament staff permissions. Unauthorized users receive a 403.

Response Fields

Field	Type	Description
uid	string \| null	User's unique identifier
name	string	Display name
email	string \| null	Email address
discord	string \| null	Discord username
status	string	`player`, `dropped`, or `waitlist`
standing	number \| null	Tournament standing (null for dropped/waitlist)
decklist	string \| null	Decklist URL (if available)
deckObj	object \| null	Structured deck data

Waitlist-Specific Fields

Additional fields for users with status waitlist:

Field	Type	Description
joinedAt	number \| null	Unix timestamp when user joined waitlist
waitlistStatus	string	"waiting", "offered", "accepted", "declined", "expired", "moved"
waitlistPosition	number \| null	Position in queue (only for "waiting")
offeredAt	number \| null	When spot was offered
expirationTimestamp	number \| null	When offer expires

Response

[
  {
    "uid": "player123",
    "name": "John Doe",
    "email": "john@example.com",
    "status": "player",
    "standing": 1,
    "decklist": "...",
    "deckObj": { ... }
  },
  {
    "uid": "waitlist789",
    "name": "Bob Wilson",
    "status": "waitlist",
    "waitlistStatus": "waiting",
    "waitlistPosition": 1
  }
]

Error Responses

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

{ "error": "Tournament not found" }

Error Codes

The API uses standard HTTP status codes. Errors return a JSON body with status and error fields.

Code	Meaning	When
400	Bad Request	Missing or invalid parameters
401	Unauthorized	Invalid or missing API key
429	Rate Limited	Too many requests per minute
500	Server Error	Internal error — contact us

400 Bad Request

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

401 Unauthorized

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

429 Rate Limited

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

500 Server Error

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

TopDeck.gg API

Usage Requirements

Rate Limits

Attribution Required

Authentication

Body Parameters

Games and Supported Formats

Response Fields

Tournament Level

Query Parameters

Response Fields

Conditional Fields

Response Fields

Top Level

Response Fields

Conditional Fields

Conditional Fields

Response Fields

Conditional Fields

Response Fields

Conditional Fields

Response Fields

Waitlist-Specific Fields

Error Codes