Roster Endpoint - API Documentation

Overview

This endpoint returns the complete roster data for a specified page, including all ranks, users, certifications, and subdivisions. The response includes detailed information about each rank, the users in each rank, and separate sections for certifications and subdivisions.

If patrol logs are enabled for the page, patrol hours will be included for each user.

Note: This endpoint provides a hierarchical view of the roster data. If you need a flat list of all users, use the /api/roster/{page_id}/users endpoint instead.

Parameters

Path Parameters

Name	Type	Required	Description
page_id	string	Yes	The UUID of the roster page (e.g., c88006c8-b9ea-433c-8a8b-749ec1af0756)

Headers

Name	Required	Description
X-API-Key	Yes	Your API key for authentication

Response

Response Fields

Field	Type	Description
page_id	string	The UUID of the roster page
owner_id	string	The Discord ID of the roster owner
custom_title	string	The custom title of the roster
description	string	The description of the roster
custom_url_path	string	The custom URL path of the roster
public_url	string	The public URL of the roster
ranks	array	Array of rank objects
ranks[].rank_name	string	The name of the rank
ranks[].role_id	string	The Discord role ID associated with the rank
ranks[].is_command	boolean	Whether the rank is a command rank
ranks[].users	array	Array of user objects in this rank
ranks[].users[].name	string	The name of the user
ranks[].users[].rank	string	The rank of the user
ranks[].users[].discord_id	string	The Discord ID of the user
ranks[].users[].discord_username	string	The Discord username of the user
ranks[].users[].certifications	array	Array of certification names the user has
ranks[].users[].subdivisions	array	Array of subdivision names the user belongs to
ranks[].users[].promotion_date	string	The date the user was promoted to their current rank (YYYY-MM-DD)
ranks[].users[].promotion_officer	string	The name of the officer who promoted the user
ranks[].users[].patrol_hours	number	The number of patrol hours the user has (if patrol logs are enabled)

Example Response

{
  "page_id": "c88006c8-b9ea-433c-8a8b-749ec1af0756",
  "owner_id": "123456789012345678",
  "custom_title": "Example Roster",
  "description": "This is an example roster",
  "custom_url_path": "example-roster",
  "public_url": "https://autorosters.com/r/example-roster",
  "ranks": [
    {
      "rank_name": "Commander",
      "role_id": "123456789012345678",
      "is_command": true,
      "users": [
        {
          "name": "John Doe",
          "rank": "Commander",
          "discord_id": "123456789012345678",
          "discord_username": "johndoe",
          "certifications": [
            "First Aid",
            "Basic Fire Fighting"
          ],
          "subdivisions": [
            "Fire Department",
            "Rapid Response Team"
          ],
          "promotion_date": "2024-01-15",
          "promotion_officer": "Captain Smith",
          "patrol_hours": 42.5
        }
      ]
    },
    {
      "rank_name": "Lieutenant",
      "role_id": "876543210987654321",
      "is_command": true,
      "users": [
        {
          "name": "Jane Smith",
          "rank": "Lieutenant",
          "discord_id": "987654321098765432",
          "discord_username": "janesmith",
          "certifications": [
            "Advanced Fire Fighting",
            "Hazardous Materials Handling"
          ],
          "subdivisions": [
            "Fire Department",
            "Rapid Response Team"
          ],
          "promotion_date": "2023-12-01",
          "promotion_officer": "Captain Johnson",
          "patrol_hours": 68.2
        }
      ]
    }
  ]
}

Error Responses

404 Not Found

{
  "error": "Roster page not found"
}

401 Unauthorized

{
  "error": "Invalid or missing API key"
}

403 Forbidden

{
  "error": "API access requires premium subscription"
}

403 Forbidden - Permission Denied

{
  "error": "You do not have permission to access this roster"
}

This error occurs when you try to access a roster that you don't own. For security reasons, API keys can only access rosters owned by the user who created the API key.

Code Examples

cURL

curl -X GET "https://autorosters.com/api/roster/c88006c8-b9ea-433c-8a8b-749ec1af0756" \
     -H "X-API-Key: your-api-key-here"

Python

import requests

api_key = "your-api-key-here"
page_id = "c88006c8-b9ea-433c-8a8b-749ec1af0756"
url = f"https://autorosters.com/api/roster/${page_id}"

headers = {
    "X-API-Key": api_key
}

response = requests.get(url, headers=headers)
data = response.json()

print(data)

JavaScript

const apiKey = "your-api-key-here";
const pageId = "c88006c8-b9ea-433c-8a8b-749ec1af0756";
const url = `https://autorosters.com/api/roster/${page_id}`;

fetch(url, {
  method: "GET",
  headers: {
    "X-API-Key": apiKey
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));

GET /api/roster/{page_id}