> For the complete documentation index, see [llms.txt](https://docs.fiveroster.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fiveroster.com/api-management/api-version-1.0.md). # API Version 1.0 {% hint style="info" %} The FiveRoster API is currently in a BETA and you may experience bugs. Please log a support ticket if you encounter any problems. {% endhint %} ## 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: {% tabs %} {% tab title="401 (Missing API Key)" %} ```json { "error": [ "code": "missing_api_key", "message": "API key missing" ] } ``` {% endtab %} {% tab title="401 (Invalid API Key)" %} ```json { "error": [ "code": "invalid_api_key", "message": "Invalid API key" ] } ``` {% endtab %} {% tab title="401 (Expired API Key)" %} 
{
  "error": [
    "code": "expired_api_key",
    "message": "API key expired"
  ]
}
{% endtab %} {% endtabs %} ## 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**. ```json { "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)** ```json { "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 | | ---------------------------- | ------------------------------------------------------------------------------------------- | | id | 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)** ```json { "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)** ```json { "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. {% tabs %} {% tab title="Javascript" %} ```javascript 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)); ``` {% endtab %} {% tab title="PHP cURL" %} ```php $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); ``` {% endtab %} {% tab title="Python" %} ```python 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) ``` {% endtab %} {% tab title="C# (.NET HttpClient)" %} ```csharp 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); } } } ``` {% endtab %} {% endtabs %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.fiveroster.com/api-management/api-version-1.0.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.