Introduction
Welcome to the Brawlhalla API Beta! You can use our API to access Brawlhalla API endpoints, which can get information on various players, stats, and ranked data in our database. To gain access to the Brawlhalla API, send an email to [email protected] with a detailed description of how you intend to use the service.
PLEASE NOTE: A limited number of keys are granted each week based on request quality and usage needs.
Usage
All requests are made at the following secure URL: https://api.brawlhalla.com
Results are printed in standard JSON format.
Rate Limit
The Brawlhalla API limits how often a end-user can access the API. This is done in order to ensure that quality service is provided to the API system as well as the Brawlhalla game itself. We enforce a rate limit to prevent overloading and to ensure that the back-end servers and system are stable.
The limits are as follows:
180 calls per 15 minutes
10 calls per second
Beta Access
In beta, All calls to the service are subjected to change, and are not guaranteed to be backwards compatible. Please check this page periodically for updates.
Authentication
To authorize, use this code:
curl "https://api.brawlhalla.com/search?steamid={steamid}&api_key=EXAMPLEKEY"
Make sure to replace
EXAMPLEKEY
with your API key.
Brawlhalla expects for the API key to be included in all API requests to the server as a query parameter api_key={EXAMPLEKEY}
If you do not have an API key, you can request a Brawlhalla API key by sending an email to [email protected]
Search By Steam ID
curl "https://api.brawlhalla.com/search?steamid=76561198025185087&api_key=EXAMPLEKEY"
The above command returns JSON structured like this:
{
"brawlhalla_id": 2,
"name": ""
}
A Player can be looked up by steam ID. This returns the brawlhalla_id and a blank name.
HTTP Request
GET https://api.brawlhalla.com/search
Query Parameters
Parameter | Description |
---|---|
steamid | A player’s steamid in format steamID64 (ex 76561198025185087). |
Rankings
curl "https://api.brawlhalla.com/rankings/1v1/us-e/1?api_key=EXAMPLEKEY"
The above command returns JSON structured like this:
[
{
"rank": "1",
"name": "Dobrein\u00f0\u009f\u0091\u00bb",
"brawlhalla_id": 20877,
"best_legend": 25,
"best_legend_games": 719,
"best_legend_wins": 642,
"rating": 2872,
"tier": "Diamond",
"games": 719,
"wins": 642,
"region": "EU",
"peak_rating": 2872
},
{
"rank": "2",
"name": "Maltimum",
"brawlhalla_id": 299070,
"best_legend": 20,
"best_legend_games": 774,
"best_legend_wins": 572,
"rating": 2697,
"tier": "Diamond",
"games": 774,
"wins": 572,
"region": "EU",
"peak_rating": 2804
}
]
This endpoint retreives an array of rankings ordered and paginated 50 at a time. URL Parameters are required, else a bad request response is returned. The name parameter is optional.
HTTP Request
GET https://api.brawlhalla.com/rankings/{bracket}/{region}/{page}?name={name}
URL Parameters
Parameter | Description |
---|---|
bracket | Either 1v1 or 2v2 or kungfoot . Note that kungfoot will rotate out with the rotating ranked for that season. |
region | The region from this subset us-e, eu, sea, brz, aus, us-w For Global region, use all . |
page | The page number requested. A page of 1 is required to get the first page. |
Query Parameters
Parameter | Description |
---|---|
name | The Steam name to query against. Note that steam names can change frequently. Searching names is currently only implemented for bracket 1v1 . Searching for a name in 2v2 results in a bad request error response. Name searching must start with exact match. |
Players
Stats
curl "https://api.brawlhalla.com/player/2/stats?api_key=EXAMPLEKEY"
The above command returns JSON structured like this:
{
"brawlhalla_id": 2,
"name": "bmg | dan",
"xp": 191718,
"level": 47,
"xp_percentage": 0.6252398209337,
"games": 8,
"wins": 2,
"damagebomb": "29",
"damagemine": "0",
"damagespikeball": "0",
"damagesidekick": "14",
"hitsnowball": 0,
"kobomb": 0,
"komine": 0,
"kospikeball": 0,
"kosidekick": 0,
"kosnowball": 0,
"legends": [
{
"legend_id": 30,
"legend_name_key": "val",
"damagedealt": "317",
"damagetaken": "458",
"kos": 0,
"falls": 3,
"suicides": 0,
"teamkos": 0,
"matchtime": 155,
"games": 3,
"wins": 0,
"damageunarmed": "15",
"damagethrownitem": "1",
"damageweaponone": "77",
"damageweapontwo": "224",
"damagegadgets": "0",
"kounarmed": 0,
"kothrownitem": 0,
"koweaponone": 0,
"koweapontwo": 0,
"kogadgets": 0,
"timeheldweaponone": 38,
"timeheldweapontwo": 97,
"xp": 97,
"level": 1,
"xp_percentage": 0.46190476190476
},
{
"legend_id": 29,
"legend_name_key": "wu shang",
"damagedealt": "0",
"damagetaken": "0",
"kos": 0,
"falls": 0,
"suicides": 0,
"teamkos": 0,
"matchtime": 0,
"games": 0,
"wins": 0,
"damageunarmed": "0",
"damagethrownitem": "0",
"damageweaponone": "0",
"damageweapontwo": "0",
"damagegadgets": "0",
"kounarmed": 0,
"kothrownitem": 0,
"koweaponone": 0,
"koweapontwo": 0,
"kogadgets": 0,
"timeheldweaponone": 0,
"timeheldweapontwo": 0,
"xp": 260,
"level": 2,
"xp_percentage": 0.13586956521739
}
],
"clan": {
"clan_name": "Blue Mammoth Games",
"clan_id": 1,
"clan_xp": "86962",
"personal_xp": 4492
}
}
This endpoint retrieves all stats about a player
HTTP Request
GET https://api.brawlhalla.com/player/{brawlhalla_id}/stats
URL Parameters
Parameter | Description |
---|---|
brawlhalla_id | The brawlhalla ID of a player |
Ranked
curl "https://api.brawlhalla.com/player/2/ranked?api_key=EXAMPLEKEY"
The above command returns JSON structured like this:
{
"name": "bmg | dan",
"brawlhalla_id": 2,
"rating": 1745,
"peak_rating": 1792,
"tier": "Platinum 2",
"wins": 207,
"games": 391,
"region": "US-E",
"global_rank": 5698,
"region_rank": 1644,
"legends": [
{
"legend_id": 4,
"legend_name_key": "cassidy",
"rating": 1736,
"peak_rating": 1792,
"tier": "Platinum 1",
"wins": 161,
"games": 300
},
{
"legend_id": 21,
"legend_name_key": "barraza",
"rating": 1640,
"peak_rating": 1640,
"tier": "Gold 5",
"wins": 41,
"games": 77
}
],
"2v2": [
{
"brawlhalla_id_one": 2,
"brawlhalla_id_two": 9,
"rating": 793,
"peak_rating": 793,
"tier": "Tin 2",
"wins": 1,
"games": 1,
"teamname": "[BMG] Dan+[BMG] Dolchay",
"region": 2,
"global_rank": 423974
},
{
"brawlhalla_id_one": 1,
"brawlhalla_id_two": 2,
"rating": 789,
"peak_rating": 789,
"tier": "Tin 2",
"wins": 1,
"games": 1,
"teamname": "[BMG] Tyveris+[BMG] Dan",
"region": 2,
"global_rank": 430291
}
]
}
This endpoint retrieves ranked data about a player.
HTTP Request
GET https://api.brawlhalla.com/player/{brawlhalla_id}/ranked
URL Parameters
Parameter | Description |
---|---|
brawlhalla_id | The brawlhalla ID of a player |
Clans
curl "https://api.brawlhalla.com/clan/1/?api_key=EXAMPLEKEY"
The above command returns JSON structured like this:
{
"clan_id": 1,
"clan_name": "Blue Mammoth Games",
"clan_create_date": 1464206400,
"clan_xp": "86962",
"clan": [
{
"brawlhalla_id": 3,
"name": "[BMG] Chill Penguin X",
"rank": "Leader",
"join_date": 1464206400,
"xp": 6664
},
{
"brawlhalla_id": 2,
"name": "bmg | dan",
"rank": "Officer",
"join_date": 1464221047,
"xp": 4492
}
]
}
This endpoint retrieves information about a specific clan and its clan members.
HTTP Request
GET https://api.brawlhalla.com/clan/{clan_id}
URL Parameters
Parameter | Description |
---|---|
clan_id | The clan ID of a clan |
Static Data
All Legends
curl "https://api.brawlhalla.com/legend/all/?api_key=EXAMPLEKEY"
The above command returns JSON structured like this:
[
{
"legend_id": 3,
"legend_name_key": "bodvar",
"bio_name": "B\u00f6dvar",
"bio_aka": "The Unconquered Viking, The Great Bear",
"weapon_one": "Hammer",
"weapon_two": "Sword",
"strength": "6",
"dexterity": "6",
"defense": "5",
"speed": "5"
},
{
"legend_id": 4,
"legend_name_key": "cassidy",
"bio_name": "Cassidy",
"bio_aka": "The Marshal of the Old West",
"weapon_one": "Pistol",
"weapon_two": "Hammer",
"strength": "6",
"dexterity": "8",
"defense": "4",
"speed": "4"
}, ...
]
This endpoint retrieves summarized data for all legends. Use the Specific Legend endpoint for more details about a legend.
HTTP Request
GET https://api.brawlhalla.com/legend/all
URL Parameters
Parameter | Description |
---|---|
all | The keyword ‘all’ signifies that every legend should be returned |
Specific Legend
curl "https://api.brawlhalla.com/legend/3/?api_key=EXAMPLEKEY"
The above command returns JSON structured like this:
{
"legend_id": 3,
"legend_name_key": "bodvar",
"bio_name": "B\u00f6dvar",
"bio_aka": "The Unconquered Viking, The Great Bear",
"bio_quote": "\"I speak, you noble vikings, of a warrior who surpassed you all. I tell of a great bear-man who overcame giants and armies, and of how he came to leave our world and challenge the Gods.\"",
"bio_quote_about_attrib": "\" -The Saga of B\u00f6dvar Bearson, first stanza\"",
"bio_quote_from": "\"Listen you nine-mothered bridge troll, I'm coming in, and the first beer I'm drinking is the one in your fist.\"",
"bio_quote_from_attrib": "\" -B\u00f6dvar to Heimdall, guardian of the gates of Asgard\"",
"bio_text": "Born of a viking mother and bear father, B\u00f6dvar grew up feared and mistrusted by his own people.\nB\u00f6dvar's first nemesis was the terrible giant bear Grothnar, his own brother. By defeating Grothnar in a battle that lasted seven days, B\u00f6dvar chose to side with humanity and became the protector of the people of the north. He led his Skandian people against the Witch Queen of Helheim, slew the White Dragon Sorcerer, and lived the life of an all-conquering hero.\nAfter he single-handedly ended the Giant Wars by trapping the fire giant king in his own volcano, B\u00f6dvar sensed his work was done. But he felt doomed to never be taken by the Valkyries to Valhalla because he could never manage to be defeated in battle. So he travelled to Asgard himself, broke down the doors, and let himself in.\nValhalla is everything B\u00f6dvar hoped - an endless reward of feasting and fighting, with himself among its greatest champions.",
"bot_name": "B\u00f6tvar",
"weapon_one": "Hammer",
"weapon_two": "Sword",
"strength": "6",
"dexterity": "6",
"defense": "5",
"speed": "5"
}
This endpoint retrieves information about a specific legend.
HTTP Request
GET https://api.brawlhalla.com/legend/{legend_id}
URL Parameters
Parameter | Description |
---|---|
legend_id | The legend ID of a legend |
Change Log
Version .07
2021/04/26
- Search endpoint no longer supports name. Use players instead.
- Added kungfoot as a valid bracket for the rankings endpoint.
Version .06
2018/06/13
- Added All Legend endpoint
Version .05
2016/10/05
- Added region to 2v2 in player/ranked
- Added region to rankings for 2v2
- Added ability to filter by region for 2v2
Version .04
2016/10/03
- Disabled “global_rank”, “region_rank” for 1v1 and 2v2 ranked. Returns 0
- Added HTTP response codes that match the error codes
Version .03
2016/09/13
- Updated Rankings output
- Added peak_rating to 2v2
- Changed output key labels (total_games => games, total_wins => wins)
Version .02
2016/09/13
- Rankings
Version .01
2016/09/12
- Search
- Player
- Stats
- Clans
- Specific Legend
- Documentation
Errors
Example Error
{
"error": {
"code": 404,
"message": "Not Found"
}
}
Currently, The Brawlhalla API returns errors in JSON format, as well in the headers.
Error Code | Meaning |
---|---|
401 | Unauthorized – You Must use HTTPS |
403 | Forbidden – Bad API key or missing API key |
404 | Not Found – The service or endpoint is not found |
404 | Bad Request – Required Parameters missing, or possibly invalid |
429 | Too Many Requests – Your API key has hit the rate limit. |
503 | Service Unavailable – We’re temporarially offline for maintanance. Please try again later. |