Skip to content

Rotate to the next person on duty

POST
/v1/rotations/{rotationId}/rotate
curl --request POST \
--url https://api.roundrobinbot.eu/v1/rotations/example/rotate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json-patch+json' \
--header 'If-Match: example' \
--data '{ "cancelArrangements": true }'

Hands the shift on to the next person, exactly as the Rotate button does, on a rotation handed over by hand and on one a cadence fires on. Answers with the new on-duty state and a fresh ETag. A rotate that would leave everybody where they are answers 200 with the current state and the ETag sent, which stays valid; a stale If-Match is still refused with 412. On a scheduled window a rotate moves the order of every later turn, so it cancels what is planned against a turn whose owner it changes: accepted covers, swaps, direct assignments, and cover and swap requests still waiting. Arrangements on turns whose owner does not change, on windows handed over by hand, and absences stay. A rotate that would cancel any answers 409 with the code rotate_cancels_arrangements and a cancels list, changes nothing and leaves the ETag valid; send {“cancelArrangements”: true} to rotate and cancel them. A swap is cancelled whole: both legs are listed, sharing one requestId. A plan that cannot be read answers 503 with rotate_plan_unavailable and changes nothing; send the same request again. A rotation bound to PagerDuty or Jira Service Management answers 409 with external_rotation_is_read_only.

rotationId
required
string
If-Match
required
string

The ETag from your last read of this resource, sent back exactly as you received it, quotes included. The write happens only if nothing changed in between: a stale validator is answered 412 and nothing is written. Send * to write against whatever is current on purpose. Omitting the header is 428, never an unconditional write. https://docs.roundrobinbot.eu/api/conventions/#conditional-writes

One of:
null

Example generated

{
"cancelArrangements": true
}

OK

Media typeapplication/json

Current on-duty assignments for a rotation. Responses with externalAssignments have no ETag; read the assignment freshness and coverage fields on each response.

object
externalAssignments
One of:
null
rotationId

Rotation ID.

string
nobodyOnCallReason

Why nobody is on duty: nobody-on-call-unplanned when a running lane in an open window has nobody in it, nobody-on-call-as-arranged when every running lane is shut by its hours. The two spellings the duty history uses. Absent while any lane is live, even if another lane has no one: an empty onCall with no reason here is a person with no Slack identity, so read externalAssignments or unmappedExternalDuty. Lanes a downgrade stopped count for neither.

null | string
onCall

Current mapped Slack assignments. An empty list does not establish a coverage gap: check externalAssignments or unmappedExternalDuty.

Array<object>

One current mapped Slack assignment. A user can appear more than once when they hold multiple assignments.

object
userId

Slack user ID of the person on duty.

string
turn

Position in the native turn order. External assignments have no native turn order.

integer format: int32
cellId

Identifier of the lane in a window holding this assignment.

null | string
laneId

The lane. Lanes for external assignments do not identify provider roles.

null | string
laneName

Lane name, when available.

null | string
windowId

The window. External assignment windows do not define provider recurrence.

null | string
windowName

Window name, when available.

null | string
since

Assignment start in UTC, when known.

null | string format: date-time
coveredUntil

Exclusive end in UTC of this stretch of cover: the window closing, or the turn ending if that comes first. Null while nothing bounds the stretch.

null | string format: date-time
turnEnds

When this person’s turn ends in UTC: the next hand-over of the lane in its window, which can be later than coveredUntil when the window closes first. Null where nothing hands it over.

null | string format: date-time
skippedForAbsence

Members skipped for absence when this assignment began.

Array<object>

A member skipped because of an absence at assignment time.

object
userId

Slack user ID of the skipped member.

string
from

Absence start in UTC, when known.

null | string format: date-time
until

Absence end in UTC, when known.

null | string format: date-time
source

Absence source: googleCalendar, internalAvailability or slackStatus (a Slack status at a scheduled hand-over). Null when the source is unknown.

null | string
nextOnCall

Who takes each lane next, one entry per running lane in each window of a native rotation, earliest start first, ties in window order and then lane order. A lane whose window is shut lists the person who comes back when it opens (comingBack); otherwise the person its next hand-over deals. Absences are not resolved, since the scheduler skips somebody who is away only when it deals. For a window nothing fires on, the entry is what a rotate of the whole rotation does: a lane nobody on its list is free to take has no entry and is listed in seatsWithNobodyFree. Empty for a randomised rotation, which draws at the hand-over, for a switched-off rotation, and for a provider-owned one (read externalAssignments).

Array<object> | null

The person who takes one lane in a window next, and when.

object
userId

Slack user ID of the person who takes the lane.

string
turn

Their position in the native turn order.

integer format: int32
cellId

Identifier of the lane in a window the person takes.

string
laneId

The lane.

string
laneName

Lane name, when available.

null | string
windowId

The window.

string
windowName

Window name, when available.

null | string
since

When the person takes the lane in UTC: the window’s next hand-over, or the moment it opens where the same person is coming back. Null where the window has no computed firing (a manual one).

null | string format: date-time
turnEnds

When their turn ends in UTC, where the window has a hand-over after that.

null | string format: date-time
comingBack

Whether this is the lane’s holder resuming when a shut window opens, rather than a new person being dealt. Read since as a hand-over only where this is false.

boolean
seatsWithNobodyFree

The lanes in a window that a rotate leaves as they are, because nobody on their list is free: everyone on the list either holds this lane or stays on duty in a lane the rotate does not change. Such a lane has no entry in nextOnCall. Listed only for a window nothing fires on, which is handed over by a rotate; empty for a window that hands over on a schedule, for a randomised rotation, for a switched-off rotation, and for a provider-owned one.

Array<object> | null

A lane in a window that a rotate leaves as it is, because nobody on its list is free to take it.

object
cellId

Identifier of the lane in a window, the same cellId the on-call entries carry.

string
laneId

The lane.

string
laneName

Lane name, when available.

null | string
windowId

The window.

string
windowName

Window name, when available.

null | string
unmappedExternalDuty
One of:
null
users

Directory records for current mapped Slack users and skipped members when ?expand=users is requested. Null otherwise. Expansion disables ETag validation.

Array<object> | null

A Slack user, as Round Robin knows them.

object
id

The Slack user id.

string
teamId

The workspace that owns this person’s directory entry, which under Enterprise Grid can differ from the calling key’s workspace.

string
displayName
null | string
realName
null | string
email

Null when the install was never granted users:read.email, not only when unknown.

null | string
isGuest
boolean
isExternal

A Slack Connect person: visible through a shared channel, never a member of the workspace.

boolean
isDeleted

Deactivated in Slack, or gone from the workspace. These people are still answered rather than hidden, so an id a rotation still names resolves to something you can render. A person nothing in the workspace names any more (no rotation, role, partner schedule mapping, or open cover, swap or arrangement) is removed 30 days after they left. Their id then answers 404 on this endpoint, on the availability of a person and on a person’s shifts.

boolean
avatarUrl

The person’s Slack avatar, at 192px.

null | string
timeZone

The person’s Slack time zone, as an IANA identifier (Europe/Rome). Absent when Round Robin has not seen one for them.

null | string

Example generated

{
"externalAssignments": {
"asOfUtc": "2026-04-15T12:00:00Z",
"state": "example",
"noAnswerReason": "example",
"coverage": "example",
"lastSuccessfulReadUtc": "2026-04-15T12:00:00Z",
"lastReadFailureUtc": "2026-04-15T12:00:00Z",
"knownFromUtc": "2026-04-15T12:00:00Z",
"knownUntilUtc": "2026-04-15T12:00:00Z",
"current": [
{
"localAssignmentId": "example",
"cellId": "example",
"user": "example",
"externalName": "example",
"externalEmail": "example",
"sinceUtc": "2026-04-15T12:00:00Z",
"untilUtc": "2026-04-15T12:00:00Z",
"externalAssignment": {
"memberKind": "example",
"participantId": "example",
"sourceType": "example",
"rotationId": "example",
"shiftId": "example",
"overrideId": "example",
"originalStartUtc": "2026-04-15T12:00:00Z",
"originalEndUtc": "2026-04-15T12:00:00Z"
}
}
],
"requiredAssignmentCount": 1,
"assignedAssignmentCount": 1,
"lastReadFailure": "example",
"distinctResponderCount": 1,
"distinctParticipantCount": 1,
"unmappedAssignmentCount": 1,
"emptyAssignmentCount": 1,
"nextChange": {
"atUtc": "2026-04-15T12:00:00Z",
"starting": [
{
"localAssignmentId": "example",
"cellId": "example",
"user": "example",
"externalName": "example",
"externalEmail": "example",
"sinceUtc": "2026-04-15T12:00:00Z",
"untilUtc": "2026-04-15T12:00:00Z",
"externalAssignment": {
"memberKind": "example",
"participantId": "example",
"sourceType": "example",
"rotationId": "example",
"shiftId": "example",
"overrideId": "example",
"originalStartUtc": "2026-04-15T12:00:00Z",
"originalEndUtc": "2026-04-15T12:00:00Z"
}
}
],
"continuing": [
{
"localAssignmentId": "example",
"cellId": "example",
"user": "example",
"externalName": "example",
"externalEmail": "example",
"sinceUtc": "2026-04-15T12:00:00Z",
"untilUtc": "2026-04-15T12:00:00Z",
"externalAssignment": {
"memberKind": "example",
"participantId": "example",
"sourceType": "example",
"rotationId": "example",
"shiftId": "example",
"overrideId": "example",
"originalStartUtc": "2026-04-15T12:00:00Z",
"originalEndUtc": "2026-04-15T12:00:00Z"
}
}
],
"ending": [
{
"localAssignmentId": "example",
"cellId": "example",
"user": "example",
"externalName": "example",
"externalEmail": "example",
"sinceUtc": "2026-04-15T12:00:00Z",
"untilUtc": "2026-04-15T12:00:00Z",
"externalAssignment": {
"memberKind": "example",
"participantId": "example",
"sourceType": "example",
"rotationId": "example",
"shiftId": "example",
"overrideId": "example",
"originalStartUtc": "2026-04-15T12:00:00Z",
"originalEndUtc": "2026-04-15T12:00:00Z"
}
}
]
}
},
"rotationId": "example",
"nobodyOnCallReason": "example",
"onCall": [
{
"userId": "example",
"turn": 1,
"cellId": "example",
"laneId": "example",
"laneName": "example",
"windowId": "example",
"windowName": "example",
"since": "2026-04-15T12:00:00Z",
"coveredUntil": "2026-04-15T12:00:00Z",
"turnEnds": "2026-04-15T12:00:00Z",
"skippedForAbsence": [
{
"userId": "example",
"from": "2026-04-15T12:00:00Z",
"until": "2026-04-15T12:00:00Z",
"source": "example"
}
]
}
],
"nextOnCall": [
{
"userId": "example",
"turn": 1,
"cellId": "example",
"laneId": "example",
"laneName": "example",
"windowId": "example",
"windowName": "example",
"since": "2026-04-15T12:00:00Z",
"turnEnds": "2026-04-15T12:00:00Z",
"comingBack": true
}
],
"seatsWithNobodyFree": [
{
"cellId": "example",
"laneId": "example",
"laneName": "example",
"windowId": "example",
"windowName": "example"
}
],
"unmappedExternalDuty": {
"email": "example",
"name": "example",
"until": "2026-04-15T12:00:00Z"
},
"users": [
{
"id": "example",
"teamId": "example",
"displayName": "example",
"realName": "example",
"email": "example",
"isGuest": true,
"isExternal": true,
"isDeleted": true,
"avatarUrl": "example",
"timeZone": "example"
}
]
}

Bad Request

Media typeapplication/json
object
type
null | string
title
null | string
status
null | integer format: int32
detail
null | string
instance
null | string

Example generated

{
"type": "example",
"title": "example",
"status": 1,
"detail": "example",
"instance": "example"
}

Unauthorized

Media typeapplication/json
object
type
null | string
title
null | string
status
null | integer format: int32
detail
null | string
instance
null | string

Example generated

{
"type": "example",
"title": "example",
"status": 1,
"detail": "example",
"instance": "example"
}

Forbidden

Media typeapplication/json
object
type
null | string
title
null | string
status
null | integer format: int32
detail
null | string
instance
null | string

Example generated

{
"type": "example",
"title": "example",
"status": 1,
"detail": "example",
"instance": "example"
}

Not Found

Media typeapplication/json
object
type
null | string
title
null | string
status
null | integer format: int32
detail
null | string
instance
null | string

Example generated

{
"type": "example",
"title": "example",
"status": 1,
"detail": "example",
"instance": "example"
}

Conflict

Media typeapplication/json

The problem a rotate answers 409 with: rotate_cancels_arrangements lists what it would cancel, external_rotation_is_read_only and write_conflict carry no list.

object
type

The problem type.

null | string
title

A short name of the refusal.

null | string
status

The HTTP status.

integer format: int32
detail

What to do next.

null | string
code

The refusal code: rotate_cancels_arrangements, external_rotation_is_read_only or write_conflict.

null | string
cancels

What the rotate would cancel, with rotate_cancels_arrangements.

Array<object> | null

One arrangement or request a rotate would cancel. Unknown fields are absent.

object
kind

acceptedCover, swapLeg (one entry per leg), directAssignment, or a request still waiting for an answer: coverRequest or swapRequest.

string
arrangementId

The arrangement that would be cancelled; absent on a request still waiting.

null | string
requestId

The cover or swap request: of a request, and of an accepted cover or a swap leg that came from one. Both legs of one swap carry the same id.

null | string
cellId

The lane in a window it holds.

string
laneName

The lane’s name; absent for a lane with no name.

null | string
from

When it begins, in UTC.

string format: date-time
to

When it ends, in UTC.

string format: date-time
turnOwnerUserId

Whose turn it is: a cover’s or a request’s requester, a swap leg’s owner, a direct assignment’s owner of the turn.

null | string
takerUserId

Who takes the turn over: an accepted cover’s cover and a direct assignment’s assignee, a swap leg’s other swapper, a cover request’s person asked (when one person was), a swap request’s proposed partner.

null | string

Example generated

{
"type": "example",
"title": "example",
"status": 1,
"detail": "example",
"code": "example",
"cancels": [
{
"kind": "example",
"arrangementId": "example",
"requestId": "example",
"cellId": "example",
"laneName": "example",
"from": "2026-04-15T12:00:00Z",
"to": "2026-04-15T12:00:00Z",
"turnOwnerUserId": "example",
"takerUserId": "example"
}
]
}

Precondition Failed

Media typeapplication/json
object
type
null | string
title
null | string
status
null | integer format: int32
detail
null | string
instance
null | string

Example generated

{
"type": "example",
"title": "example",
"status": 1,
"detail": "example",
"instance": "example"
}

Precondition Required

Media typeapplication/json
object
type
null | string
title
null | string
status
null | integer format: int32
detail
null | string
instance
null | string

Example generated

{
"type": "example",
"title": "example",
"status": 1,
"detail": "example",
"instance": "example"
}

Service Unavailable

Media typeapplication/json
object
type
null | string
title
null | string
status
null | integer format: int32
detail
null | string
instance
null | string

Example generated

{
"type": "example",
"title": "example",
"status": 1,
"detail": "example",
"instance": "example"
}