The Round Robin API
The public API exposes rotation reads, configuration and duty actions under /v1. Use it to connect an integration or submit a decision as an authenticated participant.
You need: the credential required by the operation. Most integration operations use a team API key; participant actions use a Round Robin access token for a signed-in Slack member.
Make your first call
Section titled “Make your first call”Create an integration key under Settings → API keys. Call GET /v1/keys/self with the key in the bearer header to check its workspace, scopes and rotation access.
The production API is https://api.roundrobinbot.eu. Use credentials issued for that environment. See authentication.
Ask who is on call
Section titled “Ask who is on call”Call GET /v1/rotations/{rotationId}/on-call. Add expand=users when you also need the named users’ directory details.
When a response returns an ETag, keep it for supported conditional reads or writes. See conventions.
What you can read
Section titled “What you can read”| Task | Endpoint |
|---|---|
| Find rotations | GET /v1/rotations |
| Read a rotation | GET /v1/rotations/{rotationId} |
| Read projected duty | GET /v1/rotations/{rotationId}/schedule |
| Read direct assignments | GET /v1/rotations/{rotationId}/duty-arrangements |
| Read cover requests | GET /v1/rotations/{rotationId}/cover-requests |
| Read swap requests | GET /v1/rotations/{rotationId}/swap-requests |
| Find duty for a swap | GET /v1/rotations/{rotationId}/swap-requests/candidates |
Supply the range and pagination parameters required by each operation. A limited or incomplete result does not establish that no other duty exists.
What you can change
Section titled “What you can change”| Task | Access |
|---|---|
| Rotate or set on duty | Team API key with write:duty |
| Create, change or restore a direct assignment | Team API key with write:duty |
| Create or configure rotations and coverage | Team API key with write:rotation |
| Manage rotation availability | Team API key with write:rotation |
| Propose or respond to cover and swaps | Authenticated member with the required participant permission |
Read or preview the current state before submitting. Most writes to an existing rotation require If-Match; duty actions also use an operation identifier for retries. See conventions and participant duty operations.
For direct assignments, use the duty-arrangements/preview operation before creating a replacement. Read {arrangementId}/restore-preview before ending it. Restoration follows the current schedule and availability; it does not guarantee the original person returns.
Read the past
Section titled “Read the past”A rotation’s history endpoint describes recorded service. Use history to answer who actually held duty, and the schedule endpoint for projections.
A missing user identifier does not by itself establish an uncovered interval. Check the response’s explicit state.
Read who changed what
Section titled “Read who changed what”A rotation’s activity endpoint identifies recorded changes and their actors. Use its date range to investigate the operation you are checking.
Lanes, windows and cells
Section titled “Lanes, windows and cells”A lane is a place for one person on duty. A coverage window specifies its hours and time zone. A cell pairs a lane with a window.
Read the current rotation before replacing coverage. A coverage replacement can remove lanes or windows omitted from the request. Review the complete submitted grid before writing.
Say who is away
Section titled “Say who is away”Rotation availability operations record an absence for a member. Check the scope, dates and person before submitting it.
For a member’s proposed availability, use the availability-impact preview to compare the affected duty without saving the change. Review existing assignments, cover and swaps that remain commitments.
Versions
Section titled “Versions”Use the published /v1 routes and their reference contracts. Dashboard-only routes are separate from the public API.
Next steps
Section titled “Next steps”- Authentication: select and send a credential.
- Scopes and access: restrict an integration key.
- Participant duty operations: preview and submit member decisions.
- API reference: operation parameters and response schemas.