BrawlAPI

https://github.com/zihadmahiuddin/brawlapi-docs
Admin
BrawlAPI is an unofficial, public REST API that allows developers to access and retrieve real-time...
Tokens:5,990
Snippets:58
Trust Score:7.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Authenticate with Python

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/authentication.md

Examples using http.client and the aiohttp library.

```python
import http.client

conn = http.client.HTTPConnection("brawlapi.cf")

headers = {
    'Authorization': "a1234567890",
}

conn.request("GET", "/player?tag=Y2QPGG", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
```

```python
import aiohttp
headers = {"Authorization": "a1234567890"}
url = "https://api.brawlapi.cf/v1/player?tag=Y2QPGG"
async with aiohttp.ClientSession() as session:
    async with session.get(url, headers=headers) as resp:
        data = await resp.json()
```

--------------------------------

### Authenticate with Java

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/authentication.md

Examples using OK HTTP and Unirest libraries.

```java
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.brawlapi.cf/v1/player?tag=Y2QPGG")
  .get()
  .addHeader("Authorization", "a1234567890")
  .build();

Response response = client.newCall(request).execute();
```

```java
HttpResponse<String> response = Unirest.get("https://api.brawlapi.cf/v1/player?tag=Y2QPGG")
  .header("Authorization", "a1234567890")
  .asString();
```

--------------------------------

### Authenticate with PHP

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/authentication.md

Examples using native stream context, HttpRequest, and pecl_http.

```php
$token = "a1234567890";
$opts = [
    "http" => [
        "header" => "Authorization:" . $token
    ]
];

$context = stream_context_create($opts);

$test = file_get_contents("https://api.brawlapi.cf/v1/player?tag=Y2QPGG",true, $context);
```

```php
<?php

$request = new HttpRequest();
$request->setUrl('https://api.brawlapi.cf/v1/player?tag=Y2QPGG');
$request->setMethod(HTTP_METH_GET);

$request->setHeaders(array(
  'Authorization' => 'a1234567890'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
```

```php
<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.brawlapi.cf/v1/player?tag=Y2QPGG');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'Authorization' => 'a1234567890'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();
```

--------------------------------

### GET /v1/player

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/authentication.md

Retrieves player information by tag, requiring an Authorization header.

```APIDOC
## GET /v1/player

### Description
Retrieves player data for a specific player tag.

### Method
GET

### Endpoint
https://api.brawlapi.cf/v1/player

### Parameters
#### Query Parameters
- **tag** (string) - Required - The unique player tag to retrieve data for.

### Request Headers
- **Authorization** (string) - Required - The API authentication token.
```

--------------------------------

### Authenticate with Javascript

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/authentication.md

Examples for jQuery AJAX and Node.js. Note that client-side usage exposes your token.

```javascript
var settings = {
  async: true,
  crossDomain: true,
  url: "https://api.brawlapi.cf/v1/player?tag=Y2QPGG",
  method: "GET",
  headers: {
    Authorization: "a1234567890"
  }
};

$.ajax(settings).done(function(response) {
  console.log(response);
});
```

```javascript
const request = require("request");
request("https://api.brawlapi.cf/v1/player?tag=Y2QPGG", {
  headers: { Authorization: "a1234567890" }
});
```

```javascript
var request = require("request");

var options = {
  method: "GET",
  url: "https://api.brawlapi.cf/v1/player?tag=Y2QPGG",
  headers: { Authorization: "a1234567890" }
};

request(options, function(error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
```

--------------------------------

### GET /v1/events

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/endpoints/events.md

Retrieves a list of current and upcoming game events.

```APIDOC
## GET /v1/events

### Description
Retrieves the upcoming and current events from the game.

### Method
GET

### Endpoint
https://api.brawlapi.cf/v1/events

### Parameters
#### Query Parameters
- **type** (string) - Optional - The type of events to return (current/upcoming). Defaults to all.

### Response
#### Success Response (200)
- **current** (array) - List of current events.
- **upcoming** (array) - List of upcoming events.

#### Response Example
{
    "current": [
        {
            "slot": 4,
            "slotName": "Special Events",
            "startTimeInSeconds": 0,
            "startTime": "2018-12-10T07:18:38.360Z",
            "endTimeInSeconds": 22344,
            "endTime": "2018-12-10T14:00:00.360Z",
            "freeKeys": 10,
            "mapId": 1500023,
            "mapName": "G.G. Corral",
            "mapImageUrl": "https://fourjr.github.io/bs-assets/map_images/1500023.png",
            "gameMode": "Heist",
            "hasModifier": true,
            "modifierId": 3,
            "modifierName": "Meteor Shower"
        }
    ],
    "upcoming": [
        {
            "slot": 7,
            "slotName": "Ticketed Events",
            "startTimeInSeconds": 432744,
            "startTime": "2018-12-15T08:00:00.360Z",
            "endTimeInSeconds": 605544,
            "endTime": "2018-12-17T08:00:00.360Z",
            "freeKeys": 2,
            "mapId": 1500039,
            "mapName": "Keep Safe",
            "mapImageUrl": "https://fourjr.github.io/bs-assets/map_images/1500039.png",
            "gameMode": "Robo Rumble",
            "hasModifier": false,
            "modifierId": null,
            "modifierName": null
        }
    ]
}
```

--------------------------------

### GET /v1/player

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/authentication.md

Retrieves player information using a player tag. Requires an Authorization header.

```APIDOC
## GET /v1/player

### Description
Retrieves player data for a specific player tag.

### Method
GET

### Endpoint
https://api.brawlapi.cf/v1/player

### Parameters
#### Query Parameters
- **tag** (string) - Required - The player tag to retrieve information for.

### Request Example
curl -H "Authorization: YOUR_TOKEN" "https://api.brawlapi.cf/v1/player?tag=Y2QPGG"
```

--------------------------------

### GET /api/player/battlelog

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/endpoints/player_battlelog.md

Retrieves the recent battle history for a player identified by their tag.

```APIDOC
## GET /api/player/battlelog

### Description
Retrieves the recent battles of a player.

### Method
GET

### Endpoint
https://brawlapi.cf/api/player/battlelog

### Parameters
#### Query Parameters
- **tag** (string) - Required - The player tag of the user to retrieve
```

--------------------------------

### Global Top Players JSON Response

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/endpoints/top_players.md

Example structure of the JSON response returned for global leaderboard queries.

```json
[
  {
    "id": {
      "high": 1,
      "low": 809152
    },
    "tag": "2VQ82YGY",
    "name": "AKTwistiTwik",
    "nameColorCode": "4DDBA2",
    "avatarId": 28000041,
    "avatarUrl": "https://media.githubusercontent.com/media/fourjr/bs-assets/master/player_icons/28000041.png",
    "position": 1,
    "trophies": 23728,
    "clubName": "A Few Good Men",
    "expLevel": 100
  },
    ...
]
```

--------------------------------

### Authenticate with Swift NSURL

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/authentication.md

Uses URLSession and NSMutableURLRequest to perform an asynchronous authenticated GET request.

```swift
import Foundation

let headers = [
  "Authorization": "a1234567890",
  "Cache-Control": "no-cache",
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.brawlapi.cf/v1/player?tag=Y2QPGG")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

--------------------------------

### GET /v1/misc

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/endpoints/misc.md

Retrieves miscellaneous game data such as season end times, shop reset times, and current server date information.

```APIDOC
## GET /v1/misc

### Description
Retrieves miscellaneous data regarding the game, including timers for the season end and shop reset.

### Method
GET

### Endpoint
https://api.brawlapi.cf/v1/misc

### Response
#### Success Response (200)
- **timeUntilSeasonEndInSeconds** (integer) - Seconds remaining until the season ends.
- **timeUntilSeasonEnd** (string) - ISO 8601 timestamp for the season end.
- **timeUntilShopResetInSeconds** (integer) - Seconds remaining until the shop resets.
- **timeUntilShopReset** (string) - ISO 8601 timestamp for the shop reset.
- **serverDateYear** (integer) - The current server year.
- **serverDateDayOfYear** (integer) - The current day of the year.

#### Response Example
{
  "timeUntilSeasonEndInSeconds": 159390,
  "timeUntilSeasonEnd": "2019-04-08T08:00:00.000Z",
  "timeUntilShopResetInSeconds": 72990,
  "timeUntilShopReset": "2019-04-07T08:00:00.000Z",
  "serverDateYear": 2019,
  "serverDateDayOfYear": 96
}
```

--------------------------------

### GET https://api.brawlapi.cf/v1/player/search

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/endpoints/player_search.md

Retrieves a list of players matching the provided name or regex pattern. Limited to a maximum of 100 results.

```APIDOC
## GET https://api.brawlapi.cf/v1/player/search

### Description
Retrieves players by their name from the database. Only players previously seen by the API are returned, with a maximum limit of 100 results.

### Method
GET

### Endpoint
https://api.brawlapi.cf/v1/player/search

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the player to search for. Prepend with 'r:' to perform a regex search.

### Response
#### Success Response (200)
- **Array** (list) - A list of player objects containing 'name' and 'tag'.

#### Response Example
[
    {
        "name": "apple",
        "tag": "2PP"
    }
]
```

--------------------------------

### GET /v1/leaderboards/players

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/endpoints/top_players.md

Retrieves the global or regional top 200 players on the leaderboard.

```APIDOC
## GET /v1/leaderboards/players

### Description
This endpoint retrieves the global 200 top players on the leaderboard.

### Method
GET

### Endpoint
https://api.brawlapi.cf/v1/leaderboards/players

### Parameters
#### Query Parameters
- **count** (integer) - Optional - The number of players to return (1-200) [Default: 200]
- **brawler** (string) - Optional - A brawler leaderboard to fetch
- **region** (string) - Optional - "global" or the 2 character name of the region to fetch players of [Default: global]

### Response
#### Success Response (200)
- **items** (array) - List of player objects containing details such as tag, name, trophies, and rank.
```

--------------------------------

### Authenticate with Python requests

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/authentication.md

Uses the requests library to perform a synchronous GET request with an authorization header.

```python
import requests

url = "https://api.brawlapi.cf/v1/player?tag=Y2QPGG"

headers = {
    'Authorization': "a1234567890"
    }

response = requests.request("GET", url, headers=headers)

data = response.json()
```

--------------------------------

### GET /v1/leaderboards/clubs

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/endpoints/top_clubs.md

Retrieves the global or regional top 200 clubs on the leaderboard.

```APIDOC
## GET /v1/leaderboards/clubs

### Description
Retrieves the global 200 top clubs on the leaderboard. Supports filtering by count and region.

### Method
GET

### Endpoint
https://api.brawlapi.cf/v1/leaderboards/clubs

### Query Parameters
- **count** (integer) - Optional - The number of clubs to return (1-200). Default: 200.
- **region** (string) - Optional - "global" or the 2 character name of the region to fetch clubs. Default: global.

### Response
#### Success Response (200)
- **id** (object) - Club identifier (Global response only)
- **tag** (string) - Club tag
- **name** (string) - Club name
- **badgeId** (integer) - Badge identifier (Global response only)
- **badgeUrl** (string) - URL to the club badge image (Global response only)
- **position/rank** (integer) - Club leaderboard position
- **trophies** (integer) - Total club trophies
- **membersCount/memberCount** (integer) - Number of members in the club
```

--------------------------------

### Authenticate with Ruby NET::Http

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/authentication.md

Uses the standard library Net::HTTP to send a GET request with an authorization header.

```ruby

require 'uri'
require 'net/http'

url = URI("https://api.brawlapi.cf/v1/player?tag=Y2QPGG")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'a1234567890'

response = http.request(request)
puts response.read_body
```

--------------------------------

### GET /v1/player

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/endpoints/player.md

Retrieves a player profile including basic statistics and brawler information based on the provided player tag.

```APIDOC
## GET https://api.brawlapi.cf/v1/player

### Description
Retrieves player profiles, with basic stats and brawler info.

### Method
GET

### Endpoint
https://api.brawlapi.cf/v1/player

### Parameters
#### Query Parameters
- **tag** (string) - Required - The player tag of the user to retrieve
```

--------------------------------

### GET https://api.brawlapi.cf/v1/club/search

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/endpoints/club_search.md

Searches for in-game clubs based on the provided name. Note that the game only returns a maximum of 64 clubs.

```APIDOC
## GET https://api.brawlapi.cf/v1/club/search

### Description
This endpoint filters in-game clubs by name. The game only returns a maximum of 64 clubs.

### Method
GET

### Endpoint
https://api.brawlapi.cf/v1/club/search?name=NAME

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the clubs to search for.
```

--------------------------------

### Regional Top Players JSON Response

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/endpoints/top_players.md

Example structure of the JSON response returned for regional leaderboard queries.

```json
{
  "items": [
    {
      "tag": "#888UR8",
      "name": "ItstheUDAY",
      "nameColor": "0xfff9c908",
      "trophies": 15638,
      "rank": 1,
      "club": {
        "name": "Tribe Gaming"
      }
    },
    ...
  ]
}
```

--------------------------------

### Events JSON Response Structure

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/endpoints/events.md

Example of the JSON structure returned by the events endpoint, containing arrays for current and upcoming events.

```json
{
    "current": [
        ...
        {
            "slot": 4,
            "slotName": "Special Events",
            "startTimeInSeconds": 0,
            "startTime": "2018-12-10T07:18:38.360Z",
            "endTimeInSeconds": 22344,
            "endTime": "2018-12-10T14:00:00.360Z",
            "freeKeys": 10,
            "mapId": 1500023,
            "mapName": "G.G. Corral",
            "mapImageUrl": "https://fourjr.github.io/bs-assets/map_images/1500023.png",
            "gameMode": "Heist",
            "hasModifier": true,
            "modifierId": 3,
            "modifierName": "Meteor Shower"
        },
        ...
    ],
    "upcoming": [
        ...
        {
            "slot": 7,
            "slotName": "Ticketed Events",
            "startTimeInSeconds": 432744,
            "startTime": "2018-12-15T08:00:00.360Z",
            "endTimeInSeconds": 605544,
            "endTime": "2018-12-17T08:00:00.360Z",
            "freeKeys": 2,
            "mapId": 1500039,
            "mapName": "Keep Safe",
            "mapImageUrl": "https://fourjr.github.io/bs-assets/map_images/1500039.png",
            "gameMode": "Robo Rumble",
            "hasModifier": false,
            "modifierId": null,
            "modifierName": null
        }
        ...
    ]
}
```

--------------------------------

### GET /v1/club

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/endpoints/club.md

Retrieves a club profile including basic statistics and member information based on the provided club tag.

```APIDOC
## GET https://api.brawlapi.cf/v1/club

### Description
Retrieves club profiles, with basic stats and member info.

### Method
GET

### Endpoint
https://api.brawlapi.cf/v1/club

### Parameters
#### Query Parameters
- **tag** (string) - Required - The club tag of the club to retrieve
```

--------------------------------

### Event Notification Payload Structure

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/event_notifications.md

The JSON structure received via POST request containing metadata for ended and newly started events.

```json
{
    "old": [
        {
            event metadata (refer to /events)
        }
    ],
    "new": [
        {
            event metadata (refer to /events)
        }
    ]
}
```

--------------------------------

### Configure Docsify for BrawlAPI

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/index.html

Sets up the global $docsify object to manage documentation behavior, navigation, and visual styling.

```javascript
window.$docsify = { name: 'BrawlAPI', loadSidebar: true, subMaxLevel: 2, auto2top: true, formatUpdated: '{YYYY}-{MM}-{DD} {HH}:{mm}', themeColor: '#fdd80e', noCompileLinks: [ '/json', '/json/*.json' ], }
```

--------------------------------

### Authenticate with C#

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/authentication.md

Standard C# implementation using WebHeaderCollection.

```csharp
public string Get(string url)
{
    WebHeaderCollection headers = new WebHeaderCollection();
    headers.Add("Authorization: a1234567890");
    HttpWebRequest getRequest = (HttpWebRequest)WebRequest.Create(url);
    getRequest.Method = "GET";
    getRequest.Headers = headers;
    WebResponse apiResponse = getRequest.GetResponse();
    StreamReader reader = new StreamReader(apiResponse.GetResponseStream(), Encoding.UTF8);
    string responseString = reader.ReadToEnd();
    reader.Close();
    apiResponse.Close();

    return responseString;
}
```

--------------------------------

### Authenticate with cURL

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/authentication.md

Use the Authorization header to authenticate cURL requests.

```bash
curl --header "Authorization: a1234567890" https://api.brawlapi.cf/v1/player?tag=Y2QPGG
```

```bash
curl -X GET \
  https://api.brawlapi.cf/v1/player?tag=Y2QPGG \
  -H 'Authorization: a1234567890'
```

--------------------------------

### Retrieve Miscellaneous Game Data

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/endpoints/misc.md

The endpoint returns a JSON object containing timing information for seasons and shop resets, along with current server date details.

```json
{
  "timeUntilSeasonEndInSeconds": 159390,
  "timeUntilSeasonEnd": "2019-04-08T08:00:00.000Z",
  "timeUntilShopResetInSeconds": 72990,
  "timeUntilShopReset": "2019-04-07T08:00:00.000Z",
  "serverDateYear": 2019,
  "serverDateDayOfYear": 96
}
```

--------------------------------

### Authenticate with C# RestSharp

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/authentication.md

Implementation using the RestSharp library.

```csharp
var client = new RestClient("https://api.brawlapi.cf/v1/player?tag=Y2QPGG");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "a1234567890");
IRestResponse response = client.Execute(request);
```

--------------------------------

### Event Notification Webhook

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/event_notifications.md

Describes the structure of the POST request sent to the user's web server when a new event begins.

```APIDOC
## POST [Webhook Endpoint]

### Description
Receives a notification when a new event starts. The payload contains metadata for events that have ended and events that have started.

### Method
POST

### Request Body
- **old** (array) - List of event metadata for events that have just ended.
- **new** (array) - List of event metadata for events that have just started.

### Request Example
{
    "old": [
        { "event_metadata": "..." }
    ],
    "new": [
        { "event_metadata": "..." }
    ]
}
```

--------------------------------

### Rate Limit Headers

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/ratelimit.md

The API includes standard headers in responses to indicate current rate limit status and reset times.

```APIDOC
## Rate Limit Headers

### Description
These headers are included in API responses to inform the client about their current rate limit status.

### Headers
- **X-Ratelimit-Limit** (integer) - The total amount of requests you can make per time window.
- **X-Ratelimit-Remaining** (integer) - Requests left for the current time window.
- **X-Ratelimit-Reset** (integer) - Unix seconds when your ratelimit resets.
```

--------------------------------

### Player Search JSON Response Structure

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/endpoints/player_search.md

The response returns an array of player objects containing the name and tag.

```json
[
    {
        "name": "apple",
        "tag": "2PP"
    },
    ...
]
```

--------------------------------

### Global Clubs JSON Response Structure

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/endpoints/top_clubs.md

Represents the JSON schema for global club leaderboard entries.

```json
[
  {
    "id": {
      "high": 0,
      "low": 2250634
    },
    "tag": "YLQ9VRGP",
    "name": "Omen",
    "badgeId": 2,
    "badgeUrl": "https://media.githubusercontent.com/media/fourjr/bs-assets/master/club_badges/clan_badge_01_03.png",
    "position": 1,
    "trophies": 1612573,
    "membersCount": 98
  },
    ...
]
```

--------------------------------

### Regional Clubs JSON Response Structure

Source: https://github.com/zihadmahiuddin/brawlapi-docs/blob/master/endpoints/top_clubs.md

Represents the JSON schema for regional club leaderboard entries.

```json
[
  {
    "tag": "#CC8JLV8",
    "name": "Tribe Draco",
    "trophies": 1027556,
    "rank": 1,
    "memberCount": 94
  },
    ...
]
```
Tokens:
Raw