Skip to content
Round RobinRound Robin

Preview a cover request

POST
/v1/rotations/{rotationId}/cover-requests/preview
curl --request POST \
  --url https://api.roundrobinbot.eu/v1/rotations/example/cover-requests/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json-patch+json' \
  --data '{ "operationId": "example", "cellId": "example", "from": "2026-04-15T12:00:00Z", "to": "2026-04-15T12:00:00Z", "recipientUserIds": [ "example" ], "reason": "example" }'

Requires a Slack member access token. API keys are refused. Returns the proposed intervals and rotation ETag without changing duty or creating a request.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
rotationId
required
string

Request Bodyrequired

Section titled “Request Bodyrequired”

UTC interval and selected audience for a new cover request.

object
operationId

Caller-generated mutation identity, at most 128 characters. Reuse only for an identical retry.

string
cellId

Stable cell identifier from the rotation or personal duty read.

string
from

Inclusive requested start, with UTC offset zero.

string format: date-time
to

Exclusive requested end, with UTC offset zero.

string format: date-time
recipientUserIds

Between 1 and 100 distinct eligible Slack user identifiers, excluding the requester.

Array<string>
reason

Optional explanation, at most 2000 characters. Use an empty string when omitted.

string
Examplegenerated
{
  "operationId": "example",
  "cellId": "example",
  "from": "2026-04-15T12:00:00Z",
  "to": "2026-04-15T12:00:00Z",
  "recipientUserIds": [
    "example"
  ],
  "reason": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json

Conflict evaluation for the proposed terms. A preview does not change duty.

object
effectiveFrom
required

The later of the requested start and preview time. The actual write can begin later.

string format: date-time
to
required

The requested exclusive UTC end.

string format: date-time
conflicts
required

Observed conflicts and source uncertainties.

Array<object>

A conflict or an uncertainty affecting the proposed assignment.

object
id
required

The acknowledgment identifier for this conflict and the previewed terms.

string
type
required

absence, sameCellArrangement or unknownAvailability.

string
userId
required

The affected person’s Slack user identifier.

string
from
required

The inclusive UTC start of the conflict intersection with the requested interval.

string format: date-time
to
required

The exclusive UTC end of the conflict intersection with the requested interval.

string format: date-time
source
required

arrangement, manualAvailability, googleCalendar or slackStatus.

string
canAcknowledge
required

Whether explicit acknowledgment permits proceeding with this conflict. False means the conflict blocks the write.

boolean
canCommit
required

Whether every observed conflict permits acknowledgment and has been acknowledged. The write rechecks current state.

boolean
turnSelection
One of:
null
Examplegenerated
{
  "effectiveFrom": "2026-04-15T12:00:00Z",
  "to": "2026-04-15T12:00:00Z",
  "conflicts": [
    {
      "id": "example",
      "type": "example",
      "userId": "example",
      "from": "2026-04-15T12:00:00Z",
      "to": "2026-04-15T12:00:00Z",
      "source": "example",
      "canAcknowledge": true
    }
  ],
  "canCommit": true,
  "turnSelection": {
    "kind": "example",
    "from": "2026-04-15T12:00:00Z",
    "to": "2026-04-15T12:00:00Z"
  }
}