API Version 1.0

The FiveRoster API is currently in a BETA and you may experience bugs. Please log a support ticket if you encounter any problems.

Authentication

In order to authenticate with the FiveRoster API, you'll need to provide the API key you have generated in the header of the request under "X-API-KEY". The API may return a variety of different error messages:

{
  "error": [
    "code": "missing_api_key",
    "message": "API key missing"
  ]
}

{
  "error": [
    "code": "invalid_api_key",
    "message": "Invalid API key"
  ]
}

{
  "error": [
    "code": "expired_api_key",
    "message": "API key expired"
  ]
}

Rate Limiting

The API has several protections in place to prevent API spam and misuse. By default, the API will rate limit IP addresses that attempt to make more than 50 requests per minute.

{
  "error": [
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Try again in 60 seconds."
  ]
}

Retrieve all roster information

GET /api/v1/rosters

This endpoint is used to retrieve all roster information for a given Discord server and is returned in a JSON format. Rank information and flags are not omitted at this point for all rosters.

Headers

Name

Value

Content-Type

application/json

X-API-KEY

Generated API Key

Example Response (200 OK)

{
    "data": [
        {
            "id": "47fcc2eb-624a-4eb8-83c2-18de03152v46",
            "name": "Los Santos Police Department",
            "guild_id": "1367933128899865454",
            "active_players": 19,
            "role_access": "[\"13678763030299115823\"]",
            "announcement_channels": "[\"1868017104954533704\"]",
            "announce_demotions": 0,
            "announce_demotions_channels": "[]",
            "announce_strikes": 0,
            "announce_strikes_channels": "[]",
            "created_by": "494901188844847121"
        },
        ...
    ]
}

Field

Description

The unique roster UUID

name

Name of the roster

guild_id

The Discord server ID

active_players

Count of players within the roster

role_access

Array of Discord roles that have access to view the specific roster

announcement_channels

Array of Discord channels that will receive roster notifications (appointments, promotions)

announce_demotions

Boolean if FiveRoster will announce demotion events

announce_demotion_channels

Array of Discord channels that will receive roster demotion alerts

announce_strikes

Boolean if FiveRoster will announce strike events

announce_strikes_channels

Array of Discord channels that will receive roster strike alerts

created_by

Discord user ID of the individual who created the roster

Retrieve specific roster information

GET /api/v1/rosters/{roster_uuid}

This endpoint is used to retrieve specific roster information for a given Discord server and is returned in a JSON format. Rank information and flags IS omitted at this point for the roster.

Headers

Name

Value

Content-Type

application/json

X-API-KEY

Generated API Key

Example Response (200 OK)

{
    "data": {
        "id": "47fcc2eb-624a-4eb8-83c2-18de03152v46",
        "name": "Los Santos Police Department",
        "guild_id": "1367933128899865454",
        "active_players": 32,
        "role_access": "[\"1367946303022911583\"]",
        "flags": [{
            "id": 1,
            "name": "K-9",
            "attached_roles": ["1368538350297295944"],
            "access_roles": null
        }, {
            "id": 2,
            "name": "FTO",
            "attached_roles": ["1368538350297295944"],
            "access_roles": ["2"]
            // Access roles are for the roster management
            // [1] = Read Only
            // [2] = Manager
            // [3] = Administrator
        }, {
            "id": 4,
            "name": "Air Unit",
            "attached_roles": ["1368538350297295944"],
            "access_roles": null
        },
        ...],
        "ranks": [{
            "id": "4b3a1990-3b3a-48j8-8354-091a05f73fb5",
            "name": "Chief of Police",
            "discord_roles": "[\"1368537558136651874\"]",
            "access_roles": "[\"3\"]",
            "is_dynamic": 0,
            "callsign_prefix": "R-",
            "callsign_range": "0,0",
            "static_callsign": "01",
            "shortcode": "Chief"
        }, {
            "id": "af879926-135d-46d5-850c-78a9a5ec66324",
            "name": "Assistant Chief",
            "discord_roles": "[\"1368537558136651874\"]",
            "access_roles": "[\"3\"]",
            "is_dynamic": 0,
            "callsign_prefix": "R-",
            "callsign_range": "0,0",
            "static_callsign": "02",
            "shortcode": "AsstC"
        }, {
            "id": "bc307a3f-0219-43d8-b7aa-375009153",
            "name": "Deputy Chief",
            "discord_roles": "[\"1368537558136651874\"]",
            "access_roles": "[\"3\"]",
            "is_dynamic": 0,
            "callsign_prefix": "R-",
            "callsign_range": "0,0",
            "static_callsign": "03",
            "shortcode": "DepC"
        },
        {
            "id": "a7937764-0193-459e-89b4-1b196b84ea19",
            "name": "Lieutenant",
            "discord_roles": "[\"1368537558136651874\"]",
            "access_roles": "[\"1\"]",
            "is_dynamic": 1,
            "callsign_prefix": "R-",
            "callsign_range": "21,26",
            "static_callsign": "0",
            "shortcode": "LT"
        },
        ...
        ],
        "announcement_channels": "[\"1368537558136651874\"]",
        "announce_demotions": 0,
        "announce_demotions_channels": "[]",
        "announce_strikes": 0,
        "announce_strikes_channels": "[]",
        "created_by": "494901188844847121"
    }
}

Retrieve roster player information

GET /api/v1/rosters/{roster_uuid}/players

This endpoint is used to retrieve all roster player information for a given roster and is returned in a JSON format. This only includes players enrolled actively on the roster itself.

Headers

Name

Value

Content-Type

application/json

X-API-KEY

Generated API Key

Example Response (200 OK)

{
    "data": [{
        "player_id": 494901138843847227,
        "player_name": "Ryneide",
        "rank": "Chief of Police",
        "callsign": "R-01",
        "status": "Active",
        "flags": [1],
        "strikes": [{
            "strike_info": "Player was driving erratically and not following department guidelines.",
            "issued_by": "494901138843847227",
            "issued_date": "2025-06-27T04:02:24.000000Z"
        }],
        "notes": "Example notes here.",
        "promoted_at": "2025-06-18T02:09:01.000000Z"
    },
    ...]
}

Code Examples

Here are some examples of how to request information from the FiveRoster API.

fetch('https://fiveroster.com/api/v1/rosters', {
  headers: {
    'X-API-KEY': 'YOUR_API_KEY_HERE'
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://fiveroster.com/api/v1/rosters");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-KEY: YOUR_API_KEY_HERE'
]);

$response = curl_exec($ch);

if(curl_errno($ch)){
    echo 'Error:' . curl_error($ch);
} else {
    $data = json_decode($response, true);
    print_r($data);
}

curl_close($ch);

import requests

headers = {
    'X-API-KEY': 'YOUR_API_KEY_HERE'
}

response = requests.get('https://fiveroster.com/api/v1/rosters', headers=headers)
if response.ok:
    data = response.json()
    print(data)
else:
    print("Error:", response.status_code)

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program {
    static async Task Main() {
        HttpClient client = new HttpClient();
        client.DefaultRequestHeaders.Add("X-API-KEY", "YOUR_API_KEY_HERE");

        var response = await client.GetAsync("https://fiveroster.com/api/v1/rosters");
        if (response.IsSuccessStatusCode) {
            string data = await response.Content.ReadAsStringAsync();
            Console.WriteLine(data);
        } else {
            Console.WriteLine("Error: " + response.StatusCode);
        }
    }
}

PreviousManaging API Keys NextRead-only Roster Access

Last updated 4 days ago