Skip to content
Round RobinRound Robin

Preview availability impact

POST
/v1/teams/{teamId}/availability/impact-preview
curl --request POST \
  --url https://api.roundrobinbot.eu/v1/teams/example/availability/impact-preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json-patch+json' \
  --data '{ "proposal": { "startTime": "2026-04-15T12:00:00Z", "endTime": "2026-04-15T12:00:00Z", "timeZone": "example", "reason": "example", "rotationScope": 1, "rotationIds": [ "example" ], "recurrenceRule": { "type": 1, "interval": 1, "daysOfWeek": [ "sunday" ], "dayOfMonth": 1, "weekOfMonth": 1, "nthWeekdayDayOfWeek": "sunday", "endType": 1, "maxOccurrences": 1, "endDateUtc": "2026-04-15T12:00:00Z" }, "isActive": true }, "previewFrom": "2026-04-15T12:00:00Z", "previewTo": "2026-04-15T12:00:00Z", "afterRotationId": "example", "rotationLimit": 1, "replacedSettingId": "example", "expectedPreviewRevision": "example" }'

Requires a Slack member access token for this workspace. API keys cannot perform this preview. Compares current duty with the proposed availability without saving it or changing duty. Supply UTC preview dates spanning at most 31 days, ending after the current time and within six months. Set rotationLimit from 1 through 5. Continue with nextAfterRotationId as afterRotationId. The response complete describes paging. Check each rotation’s complete, source states and limitationCodes separately. Pass expectedPreviewRevision to compare with a reviewed preview; false matchesExpectedRevision means it changed. Invalid ranges return 422 with invalidImpactRange; invalid proposals return 422 with invalidAvailabilityTerms.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
teamId
required
string

Request Bodyrequired

Section titled “Request Bodyrequired”
object
proposal
object
startTime
string format: date-time
endTime
string format: date-time
timeZone
string
reason
null | string
rotationScope
integer format: int32
rotationIds
Array<string>
recurrenceRule
One of:
null
isActive
boolean
previewFrom
string format: date-time
previewTo
string format: date-time
afterRotationId
null | string
rotationLimit
integer format: int32
replacedSettingId
null | string
expectedPreviewRevision
null | string

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json
object
asOfUtc
required
string format: date-time
effectiveFrom
required
string format: date-time
to
required
string format: date-time
previewRevision
required
string
matchesExpectedRevision
required
null | boolean
complete
required
boolean
nextAfterRotationId
required
null | string
rotations
required
Array<object>

The effect of an availability change on one rotation.

object
rotationId
required

The rotation identifier.

string
rotationName
required

The name of the rotation.

string
rotationVersion
required

The version of the rotation the effect was read at.

integer format: int64
sourceStatuses
required

How each availability source answered.

Array<object>
object
source
required
string
state
required
string
complete
required

False when the effect may be incomplete.

boolean
limitationCodes
required

The reasons the effect may be incomplete, each as a code with the availability source it concerns when it concerns one. Empty when complete is true.

Array<object>

One reason a read is not exhaustive, with the availability source it concerns when it concerns one.

object
code
required

The reason, one of recurrenceExpansionIncomplete, manualAvailabilityUnavailable, googleCalendarUnavailable, proposalRecurrenceIncomplete, externalRotation, rotationDisabled, calendarFreshnessUnknown, projectionUnavailable, candidateHorizon, randomFutureUnknown or manualFutureContingent.

string
source

The availability source the reason is about, manualAvailability or googleCalendar. Absent when it is about no source.

null | string
intervals
required

The intervals whose holders change.

Array<object>
object
cellId
required
string
from
required
string format: date-time
to
required
string format: date-time
beforeUserIds
required
Array<string>
afterUserIds
required
Array<string>
kind
required
string
arrangementIds
required
Array<string>
arrangementKinds
required
Array<string>
laneName
null | string
windowName
null | string
Examplegenerated
{
  "asOfUtc": "2026-04-15T12:00:00Z",
  "effectiveFrom": "2026-04-15T12:00:00Z",
  "to": "2026-04-15T12:00:00Z",
  "previewRevision": "example",
  "matchesExpectedRevision": true,
  "complete": true,
  "nextAfterRotationId": "example",
  "rotations": [
    {
      "rotationId": "example",
      "rotationName": "example",
      "rotationVersion": 1,
      "sourceStatuses": [
        {
          "source": "example",
          "state": "example"
        }
      ],
      "complete": true,
      "limitationCodes": [
        {
          "code": "example",
          "source": "example"
        }
      ],
      "intervals": [
        {
          "cellId": "example",
          "from": "2026-04-15T12:00:00Z",
          "to": "2026-04-15T12:00:00Z",
          "beforeUserIds": [
            "example"
          ],
          "afterUserIds": [
            "example"
          ],
          "kind": "example",
          "arrangementIds": [
            "example"
          ],
          "arrangementKinds": [
            "example"
          ],
          "laneName": "example",
          "windowName": "example"
        }
      ]
    }
  ]
}