⚠️ We have a new, GraphQL public API alpha which you can read about on our new developer portal ⚠️  

The old API, detailed below, will continue to be available as we develop the new one. We encourage you to try to build your applications in the new one first, as the old one will be decommissioned in the future. The new API is completely separate, and the following information is accurate for the old API only. 

REST API Overview

The smashgg REST API is not final or considered “published” at this point. The REST API is subject to change without notice. Please use at your own risk.

In general, objects in our REST API (e.g. tournaments, brackets, etc.) are accessed like api.smash.gg/objectType/objectId. To make it easier to get data connected to an object, we have a special parameter called expand which is an array field where each value is a string. Different object types have different expand options.

For instance, to get a tournament, with all of its events you would do https://api.smash.gg/tournament/pulsar-premier-league?expand[]=event. If you wanted to also include the phases of the tournament, you would do https://api.smash.gg/tournament/pulsar-premier-league?expand[]=event&expand[]=phase

Tournaments are kind of self explanatory but they have an important difference in how they're accessed from the REST API by comparison to other objects. Tournaments are accessed via their slug (which you can get from the tournament's URL). For instance: https://api.smash.gg/tournament/pulsar-premier-league

Events are always contained in a tournament and represent a game (e.g. Rocket League) and type (e.g. Teams) that a person can enter. If you know an event's ID, you can access it via https://api.smash.gg/event/eventId. If you only know an event’s slug (e.g. melee-singles) and it’s tournament slug (e.g. the-big-house-6), you can access it like https://api.smash.gg/tournament/the-big-house-6/event/melee-singles.

Phases are containers of brackets. An event can have 0 or more phases. For instance, many tournaments will have a pools phase which has many brackets inside it that progress into a single final bracket phase.

Phase groups are just brackets. They can be of type single elim, double elim, or round robin. Phase groups contain sets. You can access a phase group via: https://api.smash.gg/phase_group/phaseGroupId.

Phase Group ID’s are typically the last number in a bracket URL.

Sets are individual matches in a bracket or phase group. Sets have a field for entrant1Id and entrant2Id which are the entrants playing in the set. If either of these is null, this is a bye set.

Tasks are only applicable for online events. They are the set of things that each entrant must do when playing the set. Some tasks may require actions on behalf of 1 or more participants in the entrant.

Players are a site-wide representation of a person. Players can enter tournaments and when they do a Participant is created for the player and tournament.

A participant is a representation of a player in a tournament.

An entrant is like a container of participants (1 or more) in an event. Entrants are what you'll see displayed in bracket. Entrants have an array of participant IDs that they contain.

Seeds are a phase-level concept used for determining where entrants are placed in a bracket within the phase. Seeds have an optional entrantId, an overall
​

Tournament organizers can add stations (e.g. groups of or individual setups at a live event) and streams (e.g. a Twitch stream) to organize matches. To see the stations and streams for a tournament, use the

Sets (and entire phase groups) can be assigned to streams and then ordered according to their play order. Modifying the play order is currently only supported for streams. To get the list of sets to be played on each stream in the tournament, use the following route: https://api.smash.gg/station_queue/tournamentId where tournamentId can be retrieved from a tournament REST API hit. This will give you an object with a queues field that has stream ID mapped to an array of set IDs. The data field in the response will have entities for every set and stream in the queue along with event, phase, phase group, entrant, and player data pertaining to the sets in the queue.

Let's say we want to get the top placement in an online teams bracket and know the players of each team who checked in to each match.

First we'll get the events, phases, and phase groups (brackets) for the tournament so we can find out the IDs of each bracket we're interested in: https://api.smash.gg/tournament/pulsar-premier-league?expand[]=phase&expand[]=groups&expand[]=event

Once we have a phase group (bracket) ID that we want placements and check in data for (e.g. 178064), we can do this to get placements and the sets in the bracket: https://api.smash.gg/phase_group/178064?expand[]=sets&expand[]=standings&expand[]=seeds . Access the standings entity to get placements for each entrant.

To get check in information for individual sets within the bracket, get a set ID from the sets entity in the previous REST API request (e.g. 4761484) and then do https://api.smash.gg/set/4761484?expand[]=setTask . Tasks for a set is contained in the setTask entity. Check in tasks have atype value of 1. Check in data for a task is contained in the metadata field of the task.

Goal: Get the current standings of an event and for brackets within the event

Event standings encompass all brackets and phases in the entire event. Bracket standings are just for a single bracket. Bracket standings and event standings are accessed slightly differently.

To get the standings for a single bracket, use https://api.smash.gg/phase_group/323872?expand[]=standings&expand[]=seeds and look at the standings field in the response. There are a few useful fields on each standing item:

To get standings for an event, use https://api.smash.gg/tournament/cheeseadelphia-4-1/event/starcraft-ii-legacy-of-the-void-singles/standings?entityType=event&expand[]=entrants&mutations[]=playerData&mutations[]=standingLosses&page=1&per_page=25. Standings are sorted in ascending order to show better-placing entrants first. A few notes about this URL structure:

 With the above expands and mutations in the URL, you'll get a few extra fields on the standing and entrant objects like losses and player data.

Goal: Get match results for a bracket

Using the same expands as before (sets and seeds), we'll use this REST API endpoint: https://api.smash.gg/phase_group/323872?expand[]=sets&expand[]=seeds

The response will have all the sets for the bracket. Each set has a few useful fields:

To get names for each entrant, use the seeds entity in the response. Each seed maps 1-1 with an entrant. Each seed has a mutations field which has some additional info about the objects associated with that seed. For instance, in the response for the above, you can see that the seed has mutations for the participant, player, and entrants. For singles events, entrants and participants are very similar. For teams events, the entrant (the team) is comprised of multiple participants. If you need more detailed info about the participants such as their profile pictures or ranking info, use the players field.

Goal: Get all subleagues for a league

To get the ids of all the subleagues in a league, use https://api.smash.gg/tournament/[league-slug]?expand[]=tagsByContainer and look at the “entityContainerTag” field in the response.

These objects are extremely simple and just represent an entity containing another entity (Note that leagues are represented internally as tournaments, so their type will always be “tournament” in any responses):

If you want to get more information about the subleagues than just their ids, you can use https://api.smash.gg/tournament/[league-slug]?expand[]=visibleEntityContainerTag, which returns all the “entityContainerTag”s for the league and its subleagues, as well as the tournaments and events associated with those “entityContainerTag”s.

Example: I want all the subleagues for “brawlhalla-circuit”, so I use https://api.smash.gg/tournament/brawlhalla-circuit?expand[]=tagsByContainer which returns the following:

Now I know that “brawlhalla-circuit” has four subleagues with ids 6755, 6756, 6763, 6762. I can now use https://api.smash.gg/tournament/brawlhalla-circuit?expand[]=visibleEntityContainerTag, and look through the “tournament” array for the objects with those ids to get more information about those subleages.

Goal: Get standings for a league

To get the standings for a league, use https://api.smash.gg/standing/[league-slug]/getAllEvents?expand[]=participants&mutations[]=playerData and look at the “standing” array in the response. There are a few useful fields on each standing item:

It is important to realize that if you are accessing a league that contains subleagues the default behaviour will be to only get the top 3 standings of each subleague. This behaviour can be changed by adding the optional “top” parameter.

Example: Use https://api.smash.gg/standing/brawlhalla-circuit/getAllEvents?expand[]=participants&mutations[]=playerData&top=10 to get the top 10 standings for every subleague.

To get information about the entity (e.g. “player”) associated with a standing, look at the entityType and entityId of the standing and access the matching data objects in the response.

Example: We use https://api.smash.gg/standing/brawlhalla-circuit/getAllEvents?expand[]=participants&mutations[]=playerData&top=10 and pick the first “standing” in the “standing” array, as shown below.

Looking at the “entityType”, we know that this standing is associated with a “player” and we will need to look at the “player” array for more information. We’ll need the “id” of the “player”, which is 11838, since that is the “entityId” of this standing.

We now look at the “player” array in the response and find the object with id 11838 to get all the information about the player (see below).

To get more specific information about the standings of a league, you’ll need the league’s id. To get the ids of subleagues you are interested in see Example 4 above. Once you have the id of the league you are interested in, you can use https://api.smash.gg/standing/tournament/[league-id]/page?expand[]=participants&expand[]=standingPoints&mutations[]=playerData. By default you will get the top 25 standings. This behaviour can be changed by adding the optional “per_page” parameter (e.g. https://api.smash.gg/standing/tournament/[league-id]/page?expand[]=participants&expand[]=standingPoints&mutations=playerData&per_page=50)

The “standing” array will be the same as shown above, but now there will be a “standingPoints” array with the following characteristics:

If we ignore special cases, such as when points are awarded directly, and just focus on “standingPoints” where the sourceType=”event”, then we can describe “standingPoints” much more simply: “standingPoints” for an event represent the point structure for that event.

Example: Let’s say I have an event “example-event” with an id of 12345 and I decide that 1st place will get 100 points, 2nd place gets 50 points, 3rd gets 25 points, 4th gets 10 points, and 5th gets 5 points. This would result standing points similar to the following (note that I am leaving out fields irrelevant to this example).

"standingPoints": [

{"id": 123, "sourceType": "event", "sourceId": 12345, "quantity": 100, "standing": 1},

{"id": 124, "sourceType": "event", "sourceId": 12345, "quantity": 50, "standing": 2},

{"id": 125, "sourceType": "event", "sourceId": 12345, "quantity": 25, "standing": 3},

{"id": 126, "sourceType": "event", "sourceId": 12345, "quantity": 10, "standing": 4},

{"id": 127, "sourceType": "event", "sourceId": 12345, "quantity": 5, "standing": 5}

]

It is important to notice that if my event finished with a simple double elimination bracket, two people may get 5th place, but there is only one “standingPoint” entry for 5th. That is because the “standingPoints” just act as a sort of lookup table for what points are associated with what place. If you found the “standing” object for both 5th place entrants in this event, you would see that they both have id 127 in their “pointIds” array.

Example: Let’s say we have determined that the id of the “United States 1v1” subleague of the “Brawlhalla Circuit” is 6755 using the methods described previously. Now we’ll use https://api.smash.gg/standing/tournament/6755/page?expand[]=participants&expand[]=standingPoints&mutations[]=playerData to the following response:

Now we want to find out which events the player with standing 1 has gotten points from, what place he got in that event, and how many points it was worth. So first we’ll take a look at the standing where “standing” equals 1.

We see that this standing is made up of 350 points and because there is only one entry in the “pointIds” array, all 350 points must have come from that one “standingPoints” object. So now we can find the “standingPoints” object with the id 4627.

We can see that the source of these points was the “event” with the id 23910. Now this can be a bit confusing because of the naming, but the field “standing” here means that these points are awarded to the person who placed 1 in that event. Remember that these “standingPoints” just represent the point structure for an event (as discussed in the example above). Finally, if we want to know more about the event, we can use the https://api.smash.gg/event/eventId route. So we use https://api.smash.gg/event/23910 and get the response: