Learn how to interact with Rotation App programmatically using our REST API to get on-call users, assign users, and manage rotation queues.

The Rotation App REST API provides developers with programmatic access to rotation data and controls. Use this API to build custom applications, scripts, and integrations that interact directly with your rotations through HTTP requests.

Example use cases:

• Build monitoring dashboards that fetch current on-call users via API calls.
• Create custom scheduling scripts that assign users based on complex business logic.
• Integrate rotation data into existing applications and services (project management, incident management, etc.)
• Develop automated tools that manage rotation queues programmatically instead of on a schedule.
• Build custom incident management systems that query and update rotations.

API Base URL and Authentication

All API requests should be made to:

https://api.rotation.app/v1/t/<team_id>/r/<rotation_id>/<action_type>

URL Parameters:

• team_id: Your Slack workspace/team ID
• rotation_id: The unique identifier of your rotation
• action_type: The specific API action you want to perform

Authentication:

All API requests require authentication using an API key. Include your API key in the x-api-key header:

-H "x-api-key: YOUR_API_KEY"

Learn how to configure your API key

Finding Your Team and Rotation IDs

To use the API, you’ll need your team_id and rotation_id. Learn how to find these identifiers in our dedicated guide: Learn how to find your rotation and team IDs

Available API Actions

• Get Current On-Call Users
• Get Next Users in Queue
• Assign Specific User
• Assign Next User(s)
• Shuffle Rotation Queue

Get Current On-Call Users

Retrieve the list of users currently assigned to the rotation.

Endpoint: GET /v1/t/<team_id>/r/<rotation_id>/get_on_call_user_ids

Parameters: None required

Example Request:

curl -X GET "https://api.rotation.app/v1/t/T123456/r/ROTA123/get_on_call_user_ids" \
  -H "x-api-key: YOUR_API_KEY"

Response Format:

{
  "on_call_user_ids": ["user_id_1", "user_id_2", "user_id_3"],
  "on_call_user_ids_0": "user_id_1",
  "on_call_user_ids_1": "user_id_2",
  "on_call_user_ids_2": "user_id_3"
}

Response Fields:

• on_call_user_ids: Array of user IDs currently on call
• on_call_user_ids_<index>: Individual user ID at the specified index (provided for no-code tool compatibility)

Get Next Users in Queue

Retrieve the list of users who are next in the rotation queue.

Endpoint: GET /v1/t/<team_id>/r/<rotation_id>/get_next_user_ids

Parameters: None required

Example Request:

curl -X GET "https://api.rotation.app/v1/t/T123456/r/ROTA123/get_next_user_ids" \
  -H "x-api-key: YOUR_API_KEY"

Response Format:

{
  "next_user_ids": ["user_id_1", "user_id_2", "user_id_3"],
  "next_user_ids_0": "user_id_1",
  "next_user_ids_1": "user_id_2",
  "next_user_ids_2": "user_id_3"
}

Response Fields:

• next_user_ids: Array of user IDs who are next in the rotation
• next_user_ids_<index>: Individual user ID at the specified index (provided for no-code tool compatibility)

Assign Specific User

Assign a specific user to be on call for the rotation.

Endpoint: POST /v1/t/<team_id>/r/<rotation_id>/assign_user

Body Parameters:

• user_id (required): The ID of the user to assign

Example Request:

curl -X POST "https://api.rotation.app/v1/t/T123456/r/ROTA123/assign_user" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user_id_1"}'

Response Format:

{
  "on_call_user_ids": ["user_id_1"],
  "on_call_user_ids_0": "user_id_1"
}

Response Fields:

• on_call_user_ids: Updated array of user IDs now on call
• on_call_user_ids_<index>: Individual user ID at the specified index

Assign Next User(s)

Assign the next user(s) in the rotation queue to be on call.

Endpoint: POST /v1/t/<team_id>/r/<rotation_id>/assign_next

Parameters: None required

Example Request:

curl -X POST "https://api.rotation.app/v1/t/T123456/r/ROTA123/assign_next" \
  -H "x-api-key: YOUR_API_KEY"

Response Format:

{
  "on_call_user_ids": ["user_id_1", "user_id_2", "user_id_3"],
  "on_call_user_ids_0": "user_id_1",
  "on_call_user_ids_1": "user_id_2",
  "on_call_user_ids_2": "user_id_3"
}

Response Fields:

• on_call_user_ids: Updated array of user IDs now on call
• on_call_user_ids_<index>: Individual user ID at the specified index

Shuffle Rotation Queue

Randomize the order of users in the rotation queue.

Endpoint: POST /v1/t/<team_id>/r/<rotation_id>/shuffle_rotation_queue

Body Parameters:

• include_currently_on_call (optional): Boolean indicating whether currently on-call users should be included in the shuffle

Example Request:

curl -X POST "https://api.rotation.app/v1/t/T123456/r/ROTA123/shuffle_rotation_queue" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"include_currently_on_call": true}'

Response Format:

{
  "on_call_user_ids": ["user_id_1", "user_id_2", "user_id_3"],
  "on_call_user_ids_0": "user_id_1",
  "on_call_user_ids_1": "user_id_2",
  "on_call_user_ids_2": "user_id_3"
}

Response Fields:

• on_call_user_ids: Updated array of user IDs now on call after shuffle
• on_call_user_ids_<index>: Individual user ID at the specified index

Integration Examples

Dashboard Integration

Use get_on_call_user_ids to display current on-call users on monitoring dashboards or status pages.

Incident Management

Combine get_on_call_user_ids with incident management tools to automatically assign incidents to the current on-call user.

Custom Scheduling

Use assign_user and assign_next to implement custom scheduling logic based on external factors like workload or availability.

Load Balancing

Use shuffle_rotation_queue periodically to ensure fair distribution of on-call duties across team members.