Spectate
Spectate API
Spectate API

On-call

Download schema

Who gets paged when an escalation path's notify_on_call step runs. A schedule has rotation layers, where members take turns, and overrides, where someone covers for a while. Overrides win over every layer; where layers overlap, the top one wins. On-call is part of the Team plan and up.

List on-call schedules

GET
https://api.spectate.net/v1
/on-call-schedules

Returns the team's schedules, by name, each with who is on call now and the next handoff.

List on-call schedules › query Parameters

page
​integer

Page number, from 1.

Default: 1
per_page
​integer

Schedules per page, 1 to 100.

Default: 25

List on-call schedules › Responses

Paginated set of OnCallSchedule

current_page
​integer · min: 1 · required
​OnCallSchedule[] · required
first_page_url
​string | null · required
from
​integer | null · min: 1 · required
last_page_url
​string | null · required
last_page
​integer · min: 1 · required
​object[] · required

Generated paginator links.

next_page_url
​string | null · required
path
​string | null · required

Base path for paginator generated URLs.

per_page
​integer · min: 0 · required

Number of items shown per page.

prev_page_url
​string | null · required
to
​integer | null · min: 1 · required

Number of the last item in the slice.

total
​integer · min: 0 · required

Total number of items being paginated.

Create an on-call schedule

POST
https://api.spectate.net/v1
/on-call-schedules

The schedule starts empty: nobody is on call until you add a rotation layer. Needs a plan with on-call (403 PLAN_FEATURE_UNAVAILABLE).

Create an on-call schedule › Request Body

A new on-call schedule. Add rotation layers to it afterwards.
CreateOnCallSchedule
name
​string · maxLength: 255 · required

Name, up to 255 characters

Example: Primary
timezone
​string · required

IANA time zone the rotations' dates, handoffs and restrictions are in

Example: Europe/Amsterdam
description
​string | null · maxLength: 1000

What the schedule covers, up to 1000 characters

Create an on-call schedule › Responses

The new schedule.

An on-call schedule: rotation layers and overrides that decide who gets paged when an escalation path's `notify_on_call` step runs.
OnCallSchedule
id
​string · uuid · required

Schedule ID

name
​string · required

Name

Example: Primary
description
​string | null · required

What the schedule covers

timezone
​string · required

IANA time zone the rotations' dates, handoffs and restrictions are in

Example: Europe/Amsterdam
​required
next_handoff_at
​string | null · date-time · required

When the person on call changes next, within 4 weeks

​required
​OnCallRotation[] · required

Rotation layers, top first

​OnCallOverride[] · required

Overrides that haven't ended

​EscalationPathReference[] · required

Escalation paths with a step that pages this schedule

created_at
​string · date-time · required

When the schedule was created

Get an on-call schedule

GET
https://api.spectate.net/v1
/on-call-schedules/{schedule}

Returns the schedule with its rotation layers, upcoming overrides, who is on call now and the escalation paths that page it.

Get an on-call schedule › path Parameters

schedule
​string · uuid · required

Schedule ID.

Get an on-call schedule › Responses

The schedule.

An on-call schedule: rotation layers and overrides that decide who gets paged when an escalation path's `notify_on_call` step runs.
OnCallSchedule
id
​string · uuid · required

Schedule ID

name
​string · required

Name

Example: Primary
description
​string | null · required

What the schedule covers

timezone
​string · required

IANA time zone the rotations' dates, handoffs and restrictions are in

Example: Europe/Amsterdam
​required
next_handoff_at
​string | null · date-time · required

When the person on call changes next, within 4 weeks

​required
​OnCallRotation[] · required

Rotation layers, top first

​OnCallOverride[] · required

Overrides that haven't ended

​EscalationPathReference[] · required

Escalation paths with a step that pages this schedule

created_at
​string · date-time · required

When the schedule was created

Update an on-call schedule

PATCH
https://api.spectate.net/v1
/on-call-schedules/{schedule}

Changes only the fields you send.

Update an on-call schedule › path Parameters

schedule
​string · uuid · required

Schedule ID.

Update an on-call schedule › Request Body

Changes to an on-call schedule; fields you leave out keep their value.
UpdateOnCallSchedule
name
​string · maxLength: 255

Name

Example: Primary
description
​string | null · maxLength: 1000

What the schedule covers

timezone
​string

IANA time zone. Rotations keep their dates and wall-clock handoff times in the new zone

Example: Europe/Amsterdam

Update an on-call schedule › Responses

The updated schedule.

An on-call schedule: rotation layers and overrides that decide who gets paged when an escalation path's `notify_on_call` step runs.
OnCallSchedule
id
​string · uuid · required

Schedule ID

name
​string · required

Name

Example: Primary
description
​string | null · required

What the schedule covers

timezone
​string · required

IANA time zone the rotations' dates, handoffs and restrictions are in

Example: Europe/Amsterdam
​required
next_handoff_at
​string | null · date-time · required

When the person on call changes next, within 4 weeks

​required
​OnCallRotation[] · required

Rotation layers, top first

​OnCallOverride[] · required

Overrides that haven't ended

​EscalationPathReference[] · required

Escalation paths with a step that pages this schedule

created_at
​string · date-time · required

When the schedule was created

Delete an on-call schedule

DELETE
https://api.spectate.net/v1
/on-call-schedules/{schedule}

Deletes its rotations and overrides. Escalation steps that paged it stay, and are skipped until you point them at another schedule.

Delete an on-call schedule › path Parameters

schedule
​string · uuid · required

Schedule ID.

Delete an on-call schedule › Responses

No content

No data returned

Get a schedule's timeline

GET
https://api.spectate.net/v1
/on-call-schedules/{schedule}/timeline

Who is on call between from and to (default: now and 14 days later; at most 62 days): each layer's shifts, the overrides, and the result, which is who actually gets paged.

Get a schedule's timeline › path Parameters

schedule
​string · uuid · required

Schedule ID.

Get a schedule's timeline › query Parameters

from
​string · date-time

Start of the window, ISO 8601. Default now.

to
​string · date-time

End of the window, ISO 8601, at most 62 days after from. Default 14 days after from.

Get a schedule's timeline › Responses

The timeline of the window.

Who is on call over a window: each layer's shifts, the overrides, and the result.
OnCallTimeline
from
​string · date-time · required

Start of the window

to
​string · date-time · required

End of the window

timezone
​string · required

The schedule's time zone

Example: Europe/Amsterdam
​OnCallTimelineLayer[] · required

Each layer's shifts, top layer first

​OnCallShift[] · required

Override shifts

​OnCallShift[] · required

Who actually gets paged when: overrides first, then the highest layer. Gaps are absent

Get who is on call

GET
https://api.spectate.net/v1
/on-call-schedules/{schedule}/now

Who is on call at at (default now). shift is null during a gap.

Get who is on call › path Parameters

schedule
​string · uuid · required

Schedule ID.

Get who is on call › query Parameters

at
​string · date-time

The moment, ISO 8601. Default now.

Get who is on call › Responses

Who is on call at that moment.

Who is on call at a moment.
OnCallNow
​required

Add a rotation layer

POST
https://api.spectate.net/v1
/on-call-schedules/{schedule}/rotations

New layers go below the existing ones unless position is given. Participants must be members of the team (422).

Add a rotation layer › path Parameters

schedule
​string · uuid · required

Schedule ID.

Add a rotation layer › Request Body

A new rotation layer of a schedule.
CreateOnCallRotation
name
​string · maxLength: 255 · required

Name, up to 255 characters

Example: Weekly primary
shift_unit
​OnCallShiftUnit · enum · required

The unit of the shift length

hours
Absolute hours: shifts keep their length across DST changes.
days
Calendar days in the schedule's time zone: the handoff stays at the same wall-clock time.
weeks
Calendar weeks in the schedule's time zone.
Enum values:
hours
days
weeks
shift_length
​integer · min: 1 · max: 720 · required

Shift length in shift_units: up to 720 hours, 90 days or 12 weeks

Example: 1
start_date
​string · date · pattern: ^\d{4}-\d{2}-\d{2}$ · required

The first handoff's date in the schedule's time zone; turns are counted from it

Example: 2026-11-02
handoff_time
​string · required

Handoff time as HH:MM in the schedule's time zone

Example: 09:00
position
​integer · min: 0 · max: 100

Layer order, 0 for the top. Default: below the existing layers

​
participant_ids
​string[] · minItems: 1 · maxItems: 50 · unique

1 to 50 team members taking turns, in order

Add a rotation layer › Responses

The new rotation layer.

A rotation layer: its participants take turns of `shift_length` `shift_unit`s, from `start_date` at `handoff_time`. Where layers overlap, the top layer (`position` 0) wins.
OnCallRotation
id
​string · uuid · required

Rotation ID

name
​string · required

Name

Example: Weekly primary
position
​integer · required

Layer order; 0 is the top layer and wins where layers overlap

shift_unit
​OnCallShiftUnit · enum · required

The unit of the shift length

hours
Absolute hours: shifts keep their length across DST changes.
days
Calendar days in the schedule's time zone: the handoff stays at the same wall-clock time.
weeks
Calendar weeks in the schedule's time zone.
Enum values:
hours
days
weeks
shift_length
​integer · required

Shift length in shift_units

Example: 1
start_date
​string · date · required

The first handoff's date in the schedule's time zone

Example: 2026-11-02
handoff_time
​string · required

Handoff time as HH:MM in the schedule's time zone

Example: 09:00
​required
​MemberReference[] · required

The members taking turns, in order

created_at
​string · date-time · required

When the rotation was created

Update a rotation layer

PATCH
https://api.spectate.net/v1
/on-call-schedules/{schedule}/rotations/{rotation}

Changes only the fields you send; participant_ids replaces the members taking turns.

Update a rotation layer › path Parameters

schedule
​string · uuid · required

Schedule ID.

rotation
​string · uuid · required

Rotation ID.

Update a rotation layer › Request Body

Changes to a rotation layer; fields you leave out keep their value.
UpdateOnCallRotation
name
​string · maxLength: 255

Name

Example: Weekly primary
position
​integer · min: 0 · max: 100

Move the layer to this position, 0 for the top; the others shift

shift_unit
​OnCallShiftUnit · enum

The unit of the shift length

hours
Absolute hours: shifts keep their length across DST changes.
days
Calendar days in the schedule's time zone: the handoff stays at the same wall-clock time.
weeks
Calendar weeks in the schedule's time zone.
Enum values:
hours
days
weeks
shift_length
​integer · min: 1 · max: 720

Shift length in shift_units

start_date
​string · date · pattern: ^\d{4}-\d{2}-\d{2}$

The first handoff's date

handoff_time
​string

Handoff time as HH:MM

Example: 09:00
​
participant_ids
​string[] · minItems: 1 · maxItems: 50 · unique

Members taking turns, in order; replaces the current ones

Update a rotation layer › Responses

The updated rotation layer.

A rotation layer: its participants take turns of `shift_length` `shift_unit`s, from `start_date` at `handoff_time`. Where layers overlap, the top layer (`position` 0) wins.
OnCallRotation
id
​string · uuid · required

Rotation ID

name
​string · required

Name

Example: Weekly primary
position
​integer · required

Layer order; 0 is the top layer and wins where layers overlap

shift_unit
​OnCallShiftUnit · enum · required

The unit of the shift length

hours
Absolute hours: shifts keep their length across DST changes.
days
Calendar days in the schedule's time zone: the handoff stays at the same wall-clock time.
weeks
Calendar weeks in the schedule's time zone.
Enum values:
hours
days
weeks
shift_length
​integer · required

Shift length in shift_units

Example: 1
start_date
​string · date · required

The first handoff's date in the schedule's time zone

Example: 2026-11-02
handoff_time
​string · required

Handoff time as HH:MM in the schedule's time zone

Example: 09:00
​required
​MemberReference[] · required

The members taking turns, in order

created_at
​string · date-time · required

When the rotation was created

Delete a rotation layer

DELETE
https://api.spectate.net/v1
/on-call-schedules/{schedule}/rotations/{rotation}

The layers below move up.

Delete a rotation layer › path Parameters

schedule
​string · uuid · required

Schedule ID.

rotation
​string · uuid · required

Rotation ID.

Delete a rotation layer › Responses

No content

No data returned

Add an override

POST
https://api.spectate.net/v1
/on-call-schedules/{schedule}/overrides

Has a team member cover the schedule from starts_at to ends_at, at most 90 days. Overrides win over every layer; where overrides overlap, the newest wins.

Add an override › path Parameters

schedule
​string · uuid · required

Schedule ID.

Add an override › Request Body

Someone to cover a schedule for a while, at most 90 days.
CreateOnCallOverride
member_id
​string · uuid · required

The member who covers

starts_at
​string · date-time · required

From when, as an ISO 8601 date and time

ends_at
​string · date-time · required

Until when; after starts_at

note
​string | null · maxLength: 500

Why, for the team; up to 500 characters

Example: Covering for Jane's holiday

Add an override › Responses

The new override.

Someone covering a schedule for a while, whatever the rotations say.
OnCallOverride
id
​string · uuid · required

Override ID

​MemberReference · required

Who covers

starts_at
​string · date-time · required

From when

ends_at
​string · date-time · required

Until when

note
​string | null · required

Why, for the team

Example: Covering for Jane's holiday
​required
created_at
​string · date-time · required

When it was added

Delete an override

DELETE
https://api.spectate.net/v1
/on-call-schedules/{schedule}/overrides/{override}

The rotations decide again for its time.

Delete an override › path Parameters

schedule
​string · uuid · required

Schedule ID.

override
​string · uuid · required

Override ID.

Delete an override › Responses

No content

No data returned
AlertsIncidents