Update a layer · On-Call API

PATCH/api/v1/schedules/{id}/layers/{layerID}

Changes a layer. name, priority, rotation_type, rotation_start and handoff_time keep their value when left out or empty (so priority cannot be set back to 0 here), and so does rotation_unit. handoff_day keeps its value when left out and is written when sent, 0 included; handoff_weekday is written when sent and cannot be cleared. The restrict_* fields change only when sent; send empty strings for both times (and an empty weekday list) to turn a shift back into an all-day layer.

Permission (API-key scope): oncall:schedule:write.

Authorization

Any one of:

bearerAuth (oncall:schedule:write)
apiKeyHeader (oncall:schedule:write)

Parameters

Path parameters

id string required
The schedule's id.
Example: 5b1c7d2e-8f3a-4b9c-a0d1-e2f3a4b5c6d7
layerID string required
The layer's id. It must belong to the schedule in the path.
Example: 7c3d9e1f-2a4b-4c6d-8e0f-1a2b3c4d5e6f

Request body required

Content type: application/json

Type: ScheduleLayerWrite

On create name and rotation_type are required.

name string
priority integer
rotation_type RotationType
One of: daily weekly custom
rotation_start string (date-time)
RFC 3339. Defaults to now on create.
handoff_day integer
For a custom rotation, the days (1–365) or, with rotation_unit hour, the hours (1–168) each turn lasts.
Minimum: 0
rotation_unit string
What handoff_day counts on a custom rotation; day when left out.
One of: day hour
handoff_weekday integer
The weekday a weekly rotation hands over on, 0 (Sunday) to 6.
Minimum: 0 · Maximum: 6
handoff_time string
HH:MM, 00:00–23:59, on the schedule's clock.
Example: 09:00
restrict_to_weekdays array of integer
0 is Sunday.
restrict_start_time string
HH:MM; give the end too. Empty clears the window.
restrict_end_time string
HH:MM; may be earlier than the start for a shift across midnight.

Responses

`200`

The layer after the change.

Content type: application/json

Type: object

data ScheduleLayer required
Show ScheduleLayer properties
- id string
- schedule_id string
- name string
- priority integer
  Lower numbers win. When several layers have someone on call, the layer with the smallest priority decides who is paged.
- rotation_type RotationType
  One of: daily weekly custom
- rotation_start string (date-time)
  When the rota's first turn started.
- handoff_day integer
  For a custom rotation, the days (or, with rotation_unit hour, the hours) each turn lasts. Daily and weekly rotations ignore it.
- handoff_time string
  HH:MM of the handover.
- rotation_unit string
  What handoff_day counts on a custom rotation, day or hour; empty means day.
- handoff_weekday integer | null
  The weekday a weekly rotation hands over on, 0 (Sunday) to 6; null is the weekday rotation_start falls on.
- restrict_to_weekdays array of integer
- restrict_start_time string
  HH:MM
- restrict_end_time string
  HH:MM
- rotations array of ScheduleRotation
  Show ScheduleRotation properties
  - id string
  - layer_id string
  - user_id string
  - position integer
    0-based place in the rota.
  - created_at string (date-time)
- active_from string (date-time)
  Set on a layer that replaces another from a later moment; it applies from then.
- active_until string (date-time)
  Set on a layer that a change replaces from a later moment; it applies until then.
- replaces_layer_id string
  On a changed copy, the layer it replaces.
- created_at string (date-time)
- updated_at string (date-time)
success boolean required
Value: true

`400`

The body is not JSON (INVALID_BODY); a sent rotation_type, handoff_time, rotation_start, handoff_day, rotation_unit or handoff_weekday is invalid as on create, or a weekday or the shift window is invalid (VALIDATION_FAILED).

Content type: application/json

Type: ValidationError

error object required
- code string required
  Value: VALIDATION_FAILED
- message string required
- request_id string
  The request's X-Request-ID. Quote it to support.
- details array of object required
  - field string
  - message string

`401`

No API key was sent, or it is unknown, revoked or expired (UNAUTHORIZED).

Content type: application/json

Type: Error

error object required
- code string required
  Machine-readable code. Branch on this.
- message string required
  Human-readable explanation.
- request_id string
  The request's X-Request-ID. Quote it to support.

`403`

The key lacks the scope this endpoint needs (FORBIDDEN).

Content type: application/json

Type: Error

error object required
- code string required
  Machine-readable code. Branch on this.
- message string required
  Human-readable explanation.
- request_id string
  The request's X-Request-ID. Quote it to support.

`404`

No such schedule, or no such layer on it (NOT_FOUND).

Content type: application/json

Type: Error

error object required
- code string required
  Machine-readable code. Branch on this.
- message string required
  Human-readable explanation.
- request_id string
  The request's X-Request-ID. Quote it to support.

`429`

Too many requests (RATE_LIMITED). Wait Retry-After seconds.

Headers

Retry-After integer
Seconds to wait.

Content type: application/json

Type: Error

error object required
- code string required
  Machine-readable code. Branch on this.
- message string required
  Human-readable explanation.
- request_id string
  The request's X-Request-ID. Quote it to support.

`500`

Something went wrong on EvoHub's side (INTERNAL_ERROR). Retry later.

Content type: application/json

Type: Error

error object required
- code string required
  Machine-readable code. Branch on this.
- message string required
  Human-readable explanation.
- request_id string
  The request's X-Request-ID. Quote it to support.

Example request

curl -X PATCH 'https://evohub.io/api/v1/schedules/5b1c7d2e-8f3a-4b9c-a0d1-e2f3a4b5c6d7/layers/7c3d9e1f-2a4b-4c6d-8e0f-1a2b3c4d5e6f' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  -d '{
  "handoff_day": 1,
  "restrict_end_time": "",
  "restrict_start_time": "",
  "restrict_to_weekdays": []
}'