Melee Tournament Data API Documentation

Updated July 1st 2022
Revision: 1

Melee provides an Application Programming Interface (API) for accessing your tournament data programmatically. The API exposes information available to your organization in a JSON format. To gain access to our API and discuss the fees associated with its use, please email us at contact@melee.gg

API Details

The API is available at https://mtgmelee.com. API requests are only served over HTTPS. Requests will not be honored over plaintext HTTP. The API uses UTF-8 character encoding for all responses.

Rate Limits and Good Citizenship

We ask that you only fetch data using the API whenever you need it. Constant polling when the tournament is not ongoing or polling too quickly may result in your credentials being revoked.

We encourage you to local cache the data you fetch using the API. A good example would be the tournament details such as phases and rounds, which are unchanging during the course of the tournament.

Submitting excessive requests to the server may result in a HTTP 429 Too Many Requests status code. Continuing to overload the API after this point may result in a temporary or permanent ban of your IP address.

Caching

Endpoints labeled as “cached” use a distributed cache and therefore lag behind up-to-date data. The Time To Live (TTL) on the cache is 5 minutes. Any requests made to this endpoint with an interval less than 5 minutes will return the same data.

Authentication

The Melee API uses Basic access authentication. More information about Basic authentication can be found here: https://en.wikipedia.org/wiki/Basic_access_authentication. The basic authentication header takes a clientId and a clientSecret, which is generated by Melee staff and is located in the user’s settings.

Authentication is per-user and requests using these credentials will have access to tournaments that user has access to on the Melee site.

Use of Melee Data

Melee provides special endpoints to facilitate fetching of tournament information for logistics and broadcast reasons. Sharing of API credentials with third parties without permission of Melee is expressly prohibited. Melee reserves the right to revoke API credentials at any time for failure to comply with its policies. Endpoints labeled as "privileged" require special organizer privileges granted by Melee staff.


Tournament Endpoints

Tournament endpoints are locations for retrieving information about your tournaments, their structure, players, matches, etc.

Each endpoint in this list takes a variable, like {tournamentId}, and return a json object representing that domain.

You may need to use an endpoint to retrieve variables before using other endpoints. For example, if you want to collect all of the matches for a round, you need to use the /Tournament/Tournament endpoint to get the structure of the tournament and then use /Tournament/RoundMatches/ with that round's guid.

Endpoints
  • GET /Tournament/ArchetypeStandings/{tournamentId} cached
  • GET /Tournament/CurrentFeatureMatches/{tournamentId}
  • GET /Tournament/CurrentMatches/{tournamentId}
  • GET /Tournament/CurrentStandings/{tournamentId} cached
  • GET /Tournament/PhaseStandings/{phaseId} cached
  • GET /Tournament/RoundFeatureMatches/{roundId}
  • GET /Tournament/RoundMatches/{roundId}
  • GET /Tournament/Tournament/{tournamentId} cached
  • GET /Tournament/TournamentDecklists/{tournamentId}?format={format} cachedprivileged
  • GET /Tournament/TournamentMatch/{matchGuid}
  • GET /Tournament/TournamentPlayer/{playerId} cached
  • GET /Tournament/TournamentPlayers/{tournamentId} cached
  • GET /Tournament/TournamentWOTCDecklists/{tournamentId}?format={format} cachedprivileged

Tournament

The tournament object contains information about the structure of the tournament. Its main purpose is to communicate round and phase ids for other endpoints.
The Tournament Object

                    

Players

The player object represents a player or team in a tournament.

Certain sensitive fields like Age, Region, and WizardsAccountEmail are not populated unless the player has acknoledged that the data is ok to be shared for this tournament during registration. This information is not available to organizers by default.

The player object contains metadata information about the player which can be assigned at registration or via the tournament controller.
The Player Object

                    

Matches

Matches are groups of teams that compete in a tournament.

The match object contains metadata information about the players in the match which can be assigned at registration or via the tournament controller.
The Match Object

                    

Standings

Standings is a ranked list of players in a tournament.

The standings object contains metadata information about the player which can be assigned at registration or via the tournament controller.
The Standing Object

                    

Archetype Standings

Archetype Standings is a ranked list of decklist archetypes for a tournament.
The Archetype Standing Object