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 description on how you intend to use the service!

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": "bmg | dan"
}

A Player can be looked up by steam ID. This returns the player’s name and brawlhalla_id.

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