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
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.
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.
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.
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.
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 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.
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.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.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.