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 arotationType that controls how rotationLengthDays is interpreted:
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
The UUID of the schedule to add the layer to.
Request body
Display name for the layer. Must be unique within the schedule. 1–255 characters.
Rotation frequency. One of
daily, weekly, or custom.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.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.ISO 8601 datetime when this layer becomes active. The rotation starts from this point and the first participant in
participantIds is on call.ISO 8601 datetime when this layer stops being active. Pass
null (or omit) for an open-ended layer with no end date.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
The created rotation layer.
Error codes
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
The UUID of the parent schedule.
The UUID of the layer to update.
Request body
New display name for the layer. Must be unique within the schedule. 1–255 characters.
Updated rotation type. One of
daily, weekly, or custom.Updated number of days per rotation shift. Minimum
1.Updated handoff time. Format:
HH:MM or HH:MM:SS in 24-hour format.Updated ISO 8601 datetime when the layer becomes active.
Updated ISO 8601 datetime when the layer ends. Pass
null to remove the end date and make the layer open-ended.Updated ordered list of user IDs. Must contain 1–100 entries, all of whom must be org members.
Response fields
The updated rotation layer object.
Error codes
DELETE /oncall/schedules/{scheduleId}/layers/{layerId}
Remove a rotation layer from a schedule. This action is permanent and cannot be undone.
Path parameters
The UUID of the parent schedule.
The UUID of the layer to delete.
Response fields
true when the layer was deleted.Error codes
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
The UUID of the schedule whose layers should be reordered.
Request body
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
Always
true on success. Re-fetch the schedule (or the layer list) to observe the new position values.