Skip to content

Preview a freeze

POST
/v1/rotations/{rotationId}/freeze/preview
curl --request POST \
--url https://api.roundrobinbot.eu/v1/rotations/example/freeze/preview \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json-patch+json' \
--data '{ "startsUtc": "2026-04-15T12:00:00Z", "endsUtc": "2026-04-15T12:00:00Z", "mode": "example" }'

Answers what the freeze would do without setting it: the handovers of the unchanged cadence it would drop, and for each lane and window who is on duty now, when the next regular handover comes and who takes it. Takes the same body as the freeze itself and is refused for the same reasons.

rotationId
required
string
One of:
null

Example generated

{
"startsUtc": "2026-04-15T12:00:00Z",
"endsUtc": "2026-04-15T12:00:00Z",
"mode": "example"
}

OK

Media typeapplication/json

What a freeze would do, without setting it.

object
freeze

A rotation’s freeze: from its start to its end every handover of the rotation is dropped, and the first handover after the end is the next one the unchanged cadence already had.

object
startsUtc

When the freeze starts.

string format: date-time
endsUtc

When the freeze ends.

string format: date-time
mode

keepOnDuty (holders stay on duty) or nobodyOnDuty (nobody is on duty until the end).

string
droppedHandoversUtc

The handovers of the unchanged cadence that fall inside the freeze and are dropped, in order.

Array<string>
seats
Array<object>

One lane in one window that a freeze touches.

object
cellId

The lane in a window this entry is about. Name kept for the grid cell it identifies.

string
laneName

The lane’s name, absent on a rotation with one lane.

null | string
windowId
string
userId

Who is on duty there now; absent when nobody is.

null | string
nextHandoverUtc

This lane’s next regular handover once the freeze is over; absent where nothing fires on its window.

null | string format: date-time
nextHolderUserId

Who is on duty from that first regular handover; absent when the plan has no name for it yet (a randomised plan).

null | string
droppedHandoversUtc

The handovers of this window that the freeze drops.

Array<string>
nobodyOnDutyFromUtc

In nobodyOnDuty mode, when nobody is on duty here from. Absent in keepOnDuty mode.

null | string format: date-time
nobodyOnDutyUntilUtc

In nobodyOnDuty mode, when the person on duty before is back on duty. Absent in keepOnDuty mode.

null | string format: date-time
returnsUserId

In nobodyOnDuty mode, who is back on duty at the end: the person on duty now.

null | string

Example generated

{
"freeze": {
"startsUtc": "2026-04-15T12:00:00Z",
"endsUtc": "2026-04-15T12:00:00Z",
"mode": "example",
"droppedHandoversUtc": [
"2026-04-15T12:00:00Z"
]
},
"seats": [
{
"cellId": "example",
"laneName": "example",
"windowId": "example",
"userId": "example",
"nextHandoverUtc": "2026-04-15T12:00:00Z",
"nextHolderUserId": "example",
"droppedHandoversUtc": [
"2026-04-15T12:00:00Z"
],
"nobodyOnDutyFromUtc": "2026-04-15T12:00:00Z",
"nobodyOnDutyUntilUtc": "2026-04-15T12:00:00Z",
"returnsUserId": "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
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"
}