Rotation layers

Rotation layers are sub-resources of schedules. Each layer defines a rotation pattern — who rotates, how frequently, and during what time window. A schedule can have multiple layers; when resolving who is on call, Scaling evaluates all active layers for that schedule. Each layer has a position (integer, unique per schedule) that controls precedence for ownership resolution. Lower position = higher precedence; position 0 is the owner-bearing layer — its resolved participant becomes the Schedule Owner at incident creation. New layers are appended at the next available position; use the reorder endpoint to change the order.

All layer endpoints require the parent schedule’s ID in the path. To manage the schedule itself (name, timezone, description), see Schedules.

Rotation types

Each layer has a rotationType that controls how rotationLengthDays is interpreted:

`rotationType`	Behavior
`daily`	Each participant is on call for one day. `rotationLengthDays` must be `1`.
`weekly`	Each participant is on call for one week. `rotationLengthDays` must be `7`.
`custom`	Each participant is on call for `rotationLengthDays` days. Set to any value ≥ 1.

The handoffTime field specifies the time of day (in the parent schedule’s timezone) when the rotation hands off from one participant to the next.

`POST /oncall/schedules/{scheduleId}/layers`

Add a rotation layer to an existing schedule. The layer name must be unique within the schedule.

Path parameters

scheduleId

string

required

The UUID of the schedule to add the layer to.

Request body

name

string

required

Display name for the layer. Must be unique within the schedule. 1–255 characters.

rotationType

string

required

Rotation frequency. One of daily, weekly, or custom.

rotationLengthDays

number

required

Number of days each participant is on call before the rotation advances. Minimum 1. For daily this should be 1; for weekly this should be 7.

handoffTime

string

required

Time of day when the rotation hands off to the next participant. Format: HH:MM or HH:MM:SS in 24-hour time (e.g. 09:00). Interpreted in the schedule’s timezone.

effectiveFrom

string

required

ISO 8601 datetime when this layer becomes active. The rotation starts from this point and the first participant in participantIds is on call.

effectiveUntil

string | null

ISO 8601 datetime when this layer stops being active. Pass null (or omit) for an open-ended layer with no end date.

participantIds

string[]

required

Ordered list of Clerk user IDs for the rotation. The rotation cycles through this list in order. Must contain at least 1 and at most 100 entries. All participants must be members of your organization.

Response fields

data

object

required

The created rotation layer.

Show Layer object fields

string

required

Unique layer ID (UUID).

scheduleId

string

required

ID of the parent schedule.

orgId

string

required

The organization this layer belongs to.

name

string

required

Display name of the layer.

position

integer

required

Ordering within the parent schedule. Lower = higher precedence; position 0 is the owner-bearing layer. Unique per schedule.

rotationType

string

required

daily, weekly, or custom.

rotationLengthDays

number

required

Number of days per rotation shift.

handoffTime

string

required

Handoff time in HH:MM format.

effectiveFrom

string

required

ISO 8601 datetime when the layer becomes active.

effectiveUntil

string | null

required

ISO 8601 datetime when the layer ends, or null for no end date.

participantIds

string[]

required

Ordered list of user IDs in the rotation.

createdAt

string

required

ISO 8601 creation timestamp.

updatedAt

string

required

ISO 8601 last-updated timestamp.

curl --request POST \
  --url https://api.scaling.cloud/v1/oncall/schedules/a1b2c3d4-e5f6-7890-abcd-ef1234567890/layers \
  --header 'Authorization: Bearer scl_live_your_api_key_here' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Primary rotation",
    "rotationType": "weekly",
    "rotationLengthDays": 7,
    "handoffTime": "09:00",
    "effectiveFrom": "2026-05-01T00:00:00.000Z",
    "effectiveUntil": null,
    "participantIds": ["user_aaa111", "user_bbb222", "user_ccc333"]
  }'

{
  "data": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "scheduleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "orgId": "org_2abc123def456",
    "name": "Primary rotation",
    "rotationType": "weekly",
    "rotationLengthDays": 7,
    "handoffTime": "09:00",
    "effectiveFrom": "2026-05-01T00:00:00.000Z",
    "effectiveUntil": null,
    "participantIds": ["user_aaa111", "user_bbb222", "user_ccc333"],
    "createdAt": "2026-04-07T10:00:00.000Z",
    "updatedAt": "2026-04-07T10:00:00.000Z"
  }
}

Error codes

HTTP	Code	Description
`400`	`invalid_participant`	One or more `participantIds` are not members of your organization.
`401`	`not_authorized`	Missing or invalid API key.
`404`	`not_found`	No schedule found with the given `scheduleId`.
`500`	`server_error`	Unexpected server error.

`PATCH /oncall/schedules/{scheduleId}/layers/{layerId}`

Update one or more fields on an existing rotation layer. All fields are optional — only the fields you include are updated.

Path parameters

scheduleId

string

required

The UUID of the parent schedule.

layerId

string

required

The UUID of the layer to update.

Request body

name

string

New display name for the layer. Must be unique within the schedule. 1–255 characters.

rotationType

string

Updated rotation type. One of daily, weekly, or custom.

rotationLengthDays

number

Updated number of days per rotation shift. Minimum 1.

handoffTime

string

Updated handoff time. Format: HH:MM or HH:MM:SS in 24-hour format.

effectiveFrom

string

Updated ISO 8601 datetime when the layer becomes active.

effectiveUntil

string | null

Updated ISO 8601 datetime when the layer ends. Pass null to remove the end date and make the layer open-ended.

participantIds

string[]

Updated ordered list of user IDs. Must contain 1–100 entries, all of whom must be org members.

Response fields

data

object

required

The updated rotation layer object.

curl --request PATCH \
  --url https://api.scaling.cloud/v1/oncall/schedules/a1b2c3d4-e5f6-7890-abcd-ef1234567890/layers/c3d4e5f6-a7b8-9012-cdef-123456789012 \
  --header 'Authorization: Bearer scl_live_your_api_key_here' \
  --header 'Content-Type: application/json' \
  --data '{
    "participantIds": ["user_aaa111", "user_bbb222", "user_ccc333", "user_fff666"],
    "handoffTime": "10:00"
  }'

{
  "data": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "scheduleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "orgId": "org_2abc123def456",
    "name": "Primary rotation",
    "rotationType": "weekly",
    "rotationLengthDays": 7,
    "handoffTime": "10:00",
    "effectiveFrom": "2026-05-01T00:00:00.000Z",
    "effectiveUntil": null,
    "participantIds": ["user_aaa111", "user_bbb222", "user_ccc333", "user_fff666"],
    "createdAt": "2026-04-07T10:00:00.000Z",
    "updatedAt": "2026-04-07T11:15:00.000Z"
  }
}

Error codes

HTTP	Code	Description
`400`	`invalid_participant`	One or more `participantIds` are not members of your organization.
`401`	`not_authorized`	Missing or invalid API key.
`404`	`not_found`	No layer found with the given `layerId` on this schedule.
`409`	`layer_edit_would_orphan_overrides`	The new `effectiveFrom`/`effectiveUntil` would leave existing overrides outside the layer’s effective window. `details.blockingOverrides` lists every offending override’s `id`, `startTime`, and `endTime` so you can cancel or move them before retrying.
`500`	`server_error`	Unexpected server error.

`DELETE /oncall/schedules/{scheduleId}/layers/{layerId}`

Remove a rotation layer from a schedule. This action is permanent and cannot be undone.

Path parameters

scheduleId

string

required

The UUID of the parent schedule.

layerId

string

required

The UUID of the layer to delete.

Response fields

success

boolean

required

true when the layer was deleted.

curl --request DELETE \
  --url https://api.scaling.cloud/v1/oncall/schedules/a1b2c3d4-e5f6-7890-abcd-ef1234567890/layers/c3d4e5f6-a7b8-9012-cdef-123456789012 \
  --header 'Authorization: Bearer scl_live_your_api_key_here'

{
  "success": true
}

Error codes

HTTP	Code	Description
`401`	`not_authorized`	Missing or invalid API key.
`404`	`not_found`	No layer found with the given `layerId` on this schedule.
`409`	`layer_has_dependent_overrides`	One or more overrides — past, present, or future — still reference this layer. `details.blockingOverrides` lists every blocking override’s `id`, `startTime`, and `endTime`; cancel each before retrying.
`500`	`server_error`	Unexpected server error.

`PUT /oncall/schedules/{scheduleId}/layers/order`

Reorder the rotation layers of a schedule (PUT-full-replacement). Send the full ordered list of layer IDs; the server assigns each layer’s position from its index in the array (layerIds[0] becomes position 0, the owner-bearing layer). The request must reference every existing layer of the schedule exactly once — no additions, no removals, no duplicates. Use POST .../layers and DELETE .../layers/{layerId} for those operations.

Path parameters

scheduleId

string

required

The UUID of the schedule whose layers should be reordered.

Request body

layerIds

string[]

required

Full ordered list of rotation layer IDs for the schedule. Each ID must reference an existing layer on this schedule; the array must contain every layer exactly once.

Response fields

success

boolean

required

Always true on success. Re-fetch the schedule (or the layer list) to observe the new position values.

curl --request PUT \
  --url https://api.scaling.cloud/v1/oncall/schedules/a1b2c3d4-e5f6-7890-abcd-ef1234567890/layers/order \
  --header 'Authorization: Bearer scl_live_your_api_key_here' \
  --header 'Content-Type: application/json' \
  --data '{
    "layerIds": [
      "d4e5f6a7-b8c9-0123-defa-234567890123",
      "c3d4e5f6-a7b8-9012-cdef-123456789012"
    ]
  }'

{ "success": true }

Error codes

HTTP	Code	Description
`400`	`invalid_reorder_request`	The `layerIds` array does not include every existing layer exactly once.
`401`	`not_authorized`	Missing or invalid API key, or caller lacks the admin role.
`404`	`not_found`	Schedule not found in your organization.
`500`	`server_error`	Unexpected server error.

Overview

Incidents

On-call Schedules

Escalation Policies

Team

Rotation layers

Rotation types

`POST /oncall/schedules/{scheduleId}/layers`

Path parameters

Request body

Response fields

Error codes

`PATCH /oncall/schedules/{scheduleId}/layers/{layerId}`

Path parameters

Request body

Response fields

Error codes

`DELETE /oncall/schedules/{scheduleId}/layers/{layerId}`

Path parameters

Response fields

Error codes

`PUT /oncall/schedules/{scheduleId}/layers/order`

Path parameters

Request body

Response fields

Error codes

Overview

Incidents

On-call Schedules

Escalation Policies

Team

Documentation Index

​Rotation types

​POST /oncall/schedules/{scheduleId}/layers

​Path parameters

​Request body

​Response fields

​Error codes

​PATCH /oncall/schedules/{scheduleId}/layers/{layerId}

​Path parameters

​Request body

​Response fields

​Error codes

​DELETE /oncall/schedules/{scheduleId}/layers/{layerId}

​Path parameters

​Response fields

​Error codes

​PUT /oncall/schedules/{scheduleId}/layers/order

​Path parameters

​Request body

​Response fields

​Error codes

Rotation types

`POST /oncall/schedules/{scheduleId}/layers`

Path parameters

Request body

Response fields

Error codes

`PATCH /oncall/schedules/{scheduleId}/layers/{layerId}`

Path parameters

Request body

Response fields

Error codes

`DELETE /oncall/schedules/{scheduleId}/layers/{layerId}`

Path parameters

Response fields

Error codes

`PUT /oncall/schedules/{scheduleId}/layers/order`

Path parameters

Request body

Response fields

Error codes