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 [email protected].

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 completed tournaments. Returns standings, decklists, and optional round data. Filter by TID, or by game + format + date range.

Request Body

Use either TID mode (specific IDs) or query mode (filters). game and format are required in query mode.

Field	Type	Description
TID	string \| string[]	Tournament ID or array of IDs. Disables query-mode filters.
game	string	Game name. Case sensitive.
format	string	Game format. Case sensitive.
start	integer	Earliest tournament start date (unix seconds).
end	integer	Latest tournament start date (unix seconds).
last	integer	Days back from today. Alternative to `start` / `end`.
participantMin	integer	Minimum participant count.
participantMax	integer	Maximum participant count.
columns	string[]	Player fields to include on standings. See allowed values below.
rounds	boolean \| string[]	Include round data. `true` is shorthand for `["round", "tables"`]. Default `false`.
tables	string[]	Table fields to include when `rounds` is set. See allowed values below.
players	string[]	Player fields within table rows when `rounds` is set. See allowed values below.

Allowed values

Field	Default	Valid values
columns	`decklist, wins, draws, losses`	name, id, decklist, wins, winsSwiss, winsBracket, winRate, winRateSwiss, winRateBracket, byes, draws, losses, lossesSwiss, lossesBracket
tables	`table, players, winner, status`	table, players, winner, status
players	`name, id`	name, id, decklist

Including decklist in columns or players also returns deckObj when structured deck data is available.

Pass exactly as written (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
Cyberpunk TCG	Leave format blank ("")
Chrono Core TCG	Launch Event 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 Brave League 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

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, address, 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",
      "address": "Local Game Store"
    },
    "standings": [
      {
        "name": "Player Name",
        "decklist": "~~Commanders~~\n...",
        "wins": 4,
        "draws": 1,
        "losses": 0
      }
    ],
    "rounds": [
      {
        "round": 1,
        "tables": [
          {
            "table": 1,
            "players": [
              { "name": "Alice", "id": "abc" },
              { "name": "Bob", "id": "def" }
            ],
            "winner": "Alice",
            "winner_id": "abc",
            "status": "Completed"
          }
        ]
      }
    ]
  }
]

GET/v2/tournaments/{TID}

Full tournament data: metadata, standings, and all rounds in one 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 metadata. See fields below.
standings	array	Player standings. See standings for field shape.
rounds	array	All rounds. See rounds for field shape.

data

Field	Type	Description
tid	string	Tournament ID.
name	string	Tournament name.
game	string	Game.
format	string	Game format.
startDate	number	Unix timestamp of start.

Response

{
  "data": {
    "tid": "abc123",
    "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": [
        {
          "table": 1,
          "players": [
            { "name": "Alice", "id": "abc123" },
            { "name": "Bob", "id": "def456" }
          ],
          "winner": "Alice",
          "winner_id": "abc123",
          "status": "Completed"
        }
      ]
    }
  ]
}

GET/v2/tournaments/{TID}/info

Tournament metadata, schedule, and location.

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

Standings for a tournament. League tournaments report successRate instead of winRate. Pairs-mode tournaments additionally include gameWinRate.

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)

Response

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

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

Player details and match record.

Conditional Fields

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

Response Fields

Field	Type	Description
name	string	Display name.
standing	number	Tournament standing.
decklist	string \| null	Decklist text or URL.
deckObj	object \| null	Structured deck data.
winRate	number	Overall win rate (0.0–1.0).
gamesPlayed	number	Total games played.
gamesWon	number	Games won.
byes	number	Byes received.
gamesDrawn	number	Games drawn.
gamesLost	number	Games lost.

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

List every round of a tournament, each with its tables and results. Returns an array of round objects.

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

Round

Field	Type	Description
round	number \| string	Round number, or bracket label like `"Top 8"`.
tables	array	Tables played this round. See fields below.

Table

Field	Type	Description
table	number \| "Byes"	Table number, or `"Byes"` for the bye row.
players	array	Players seated. See player details for field shape.
winner	string \| null	Winner's name, or `null` for draws or unfinished.
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

Tables from the current/latest round. Returns a flat array of tables — no round wrapper, unlike /rounds.

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

Each element is a table. Same shape as the tables entries on /rounds:

Field	Type	Description
table	number \| "Byes"	Table number, or `"Byes"` for the bye row.
players	array	Players seated.
winner	string \| null	Winner's name, or `null` for draws or unfinished.
winner_id	string \| "Draw" \| null	Winner's ID, `"Draw"` for ties, `null` for unfinished.
status	string	`Completed`, `Active`, `Pending`, or `Bye`.

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

All tournament attendees: registered players, dropped players, and waitlisted users.

Staff Only

Requires judge role or higher.

Response Fields

Field	Type	Description
uid	string \| null	User ID. `null` for unregistered waitlist entries.
name	string	Display name.
email	string \| null	Email address.
discord	string \| null	Discord username.
discordId	string \| null	Discord user ID.
status	string	`player`, `dropped`, or `waitlist`.
standing	number \| null	Tournament standing. `null` for dropped or waitlist.
decklist	string \| null	Decklist URL or text.
deckObj	object \| null	Structured deck data.

Waitlist-Specific Fields

Additional fields for entries with status: "waitlist":

Field	Type	Description
joinedAt	number \| null	Unix timestamp when the user joined the waitlist.
waitlistStatus	string	`waiting`, `offered`, `accepted`, `declined`, or `expired`.
waitlistPosition	number \| null	Queue position. Only set when `waitlistStatus: "waiting"`.
offeredAt	number \| null	Unix timestamp when the spot was offered.
expirationTimestamp	number \| null	Unix timestamp when the offer expires.

Response

[
  {
    "uid": "player123",
    "name": "John Doe",
    "email": "[email protected]",
    "status": "player",
    "standing": 1,
    "decklist": "~~Commanders~~\n...",
    "deckObj": { "Commanders": {}, "Mainboard": {} }
  },
  {
    "uid": "dropped456",
    "name": "Jane Smith",
    "email": "[email protected]",
    "status": "dropped",
    "standing": null
  },
  {
    "uid": "waitlist789",
    "name": "Bob Wilson",
    "email": "[email protected]",
    "status": "waitlist",
    "waitlistStatus": "waiting",
    "waitlistPosition": 1,
    "joinedAt": 1627840000
  }
]

POST/v2/tournaments/{TID}/register

Register one or more players by email. Emails matching an account are registered immediately; emails without an account receive an invitation and convert on signup. Returns 409 if the request would exceed the event's player cap — pass overrideCap: true to bypass.

Staff Only

Requires admin role or higher.

Request Body

Field	Type	Description
emails	string \| string[]	Email or array of emails. Required.
overrideCap	boolean	Skip the capacity check. Defaults to `false`.

Response Fields

Each input email appears in exactly one bucket, lowercased.

Field	Type	Description
added	string[]	Newly registered.
pending	string[]	No account found; invitation sent.
alreadyRegistered	string[]	Already registered or invited. No-op.
failed	string[]	Could not be processed.
banned	string[]	Banned by this organizer. Skipped.
capacity	number \| null	Event player cap, or `null` if unset.
registeredCount	number	Total registered: confirmed, pending invites, and offered waitlist seats.

Request

{
  "emails": ["[email protected]", "[email protected]"],
  "overrideCap": false
}

Response

{
  "added": ["[email protected]"],
  "pending": ["[email protected]"],
  "alreadyRegistered": [],
  "failed": [],
  "banned": [],
  "capacity": 32,
  "registeredCount": 24
}

GET/v2/me/tournaments

List tournaments owned by your API key. Defaults to tournaments with a future start date; pass filter=all to include in-progress and past events.

Note

Requires an active TopDeck subscription.

Query Parameters

Parameter	Type	Default	Description
filter	string	upcoming	Set to `all` to include in-progress and 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
registeredCount	number \| null	Current registered player count (null if event has no registration data)
capacity	number \| null	Participant cap for the event (null if uncapped)

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://...",
    "registeredCount": 24,
    "capacity": 32
  }
]

Error Codes

The API uses standard HTTP status codes. Errors return a JSON body with a single error field describing what went wrong.

Code	Meaning	When
400	Bad Request	Missing or invalid parameters
401	Unauthorized	Invalid or missing API key
403	Forbidden	Valid API key but insufficient permissions on the tournament
404	Not Found	Tournament (or other referenced resource) doesn't exist
409	Conflict	Action would violate a constraint (e.g. register past player cap)
429	Rate Limited	Too many requests per minute
500	Server Error	Internal error — contact us

400 Bad Request

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

401 Unauthorized

{ "error": "Invalid API key" }

403 Forbidden

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

404 Not Found

{ "error": "Tournament not found" }

409 Conflict

{ "error": "Event would exceed capacity (32/32 registered, 2 requested, 0 available). Set overrideCap: true to bypass." }

429 Rate Limited

{ "error": "Rate limit exceeded", "retryAfterSeconds": 42 }

Also includes a Retry-After header with the seconds to wait.

500 Server Error

{ "error": "Internal server error" }

TopDeck.gg API

Usage Requirements

Rate Limits

Attribution Required

Authentication

Request Body

Allowed values

Supported games and formats

Response Fields

Tournament Level

Conditional Fields

Response Fields

Top Level

data

Response Fields

Conditional Fields

Conditional Fields

Response Fields

Conditional Fields

Response Fields

Round

Table

Conditional Fields

Response Fields

Response Fields

Waitlist-Specific Fields

Request Body

Response Fields

Query Parameters

Response Fields

Error Codes