Participant duty operations

Participant operations apply decisions made by a Slack member. Cover and swap requests leave duty unchanged until the selected recipient accepts.

You need: an authenticated Round Robin access token for a signed-in Slack member and access to the rotation or workspace. Team API keys cannot perform these participant actions.

Preview before submitting

1. Send the proposed terms to the cover or swap preview operation.
2. Review the returned intervals and any availability conflicts. Keep the response’s ETag.
3. Submit with that value in If-Match and a caller-generated operationId.
4. To respond to an existing request, include the reviewed revision in expectedRevision.

Use a new operation identifier for a new action. If a response is lost, retry the same body with the same identifier. Do not reuse it for changed terms.

Acceptance previews let the recipient review the incoming duty. A swap requester cannot acknowledge the recipient’s conflicts for them. Acceptance changes both swap intervals together; completed service remains unchanged.

New swap proposals exchange two full future shifts. Use the complete candidate boundaries; both starts must remain after the current time when submitting. Both shifts must end within six months.

For a pending swap, a preview leg with hasStarted: true contains the remaining interval in from and to. Review that interval and include its key in acknowledgedStartedLegKeys when accepting. Include every started leg, even when it is the duty the requester receives. These keys record remaining-time consent separately from availability conflict acknowledgments. If another shift starts before submission, preview again and obtain consent for it. A pending proposal expires when either original interval ends.

Availability checks include manual absences, applicable Google Calendar events and unknown availability. A conflicting assignment for the same duty period blocks the write. Review canAcknowledge before supplying a conflict identifier.

Read requests with an API key

The /v1/rotations/{rotationId}/cover-requests and /v1/rotations/{rotationId}/swap-requests GET operations require read:oncall. The key’s workspace and rotation access still apply. Action capabilities from an API-key read do not authorize participant writes.

Cover lists return at most 100 requests per page. Pass nextCursor as cursor with the same from and to until complete is true. A malformed cursor or changed range returns invalidCoverCursor; restart without the cursor.

Swap candidates accept a UTC range of at most 31 days, ending after the current time and within six months. Candidates contain full future shifts. Started shifts are excluded, and selectableFrom equals from. Inspect complete and limitations before treating the result as exhaustive.

Preview an availability change

Send the proposal to POST /v1/teams/{teamId}/availability/impact-preview. This operation does not save availability or change duty.

Supply a UTC preview range of at most 31 days, ending after the current time and within six months. rotationLimit accepts 1 through 5. Continue with nextAfterRotationId as afterRotationId to read other pages.

The response’s complete describes paging. Each rotation also has its own complete, sourceStatuses and limitations. Check both levels. An empty interval list with an incomplete rotation does not establish that the absence has no effect.

Pass expectedPreviewRevision to compare a reviewed preview with a fresh one. A false matchesExpectedRevision means the comparison changed; review it again before saving through the availability workflow.

Recover from a refusal

Result	What to do
428	Include If-Match from a current preview.
412	Refresh the preview and review the current terms before retrying.
operationIdConflict	Use a new identifier for changed terms; retain the original for an identical retry.
coverRequestChanged or swapRequestChanged	Reload the request revision and preview again.
swapRequesterConsentChanged	Create a new proposal so the requester can review the changed availability.
swapShiftStarted	Choose a future shift and create a new preview.
swapFullShiftRequired	Use the full start and end returned by the candidate read.
swapRemainingTimeConsentRequired	Preview again and obtain consent for every started leg before supplying its key.
swapRequestExpired	Either offered interval has ended. Create a proposal with future shifts.
invalidSwapRange or invalidImpactRange	Check UTC offsets, ordering, range length and future horizon.

Next steps

• Authentication: choose the correct bearer credential.
• Request cover: the member workflow.
• Swap duty: review both sides of an exchange.