Spectate
Spectate API
Spectate API

Escalation paths

Download schema

What happens when an alert fires: notify channels, page whoever is on call, declare an incident, wait, or branch on severity, source, labels or working hours, step by step until someone acknowledges the alert. Paths are trees: a branch step ends its list of steps and continues in its then and else steps. The dashboard shows the same paths in its flow editor.

List escalation paths

GET
https://api.spectate.net/v1
/escalation-paths

Returns the team's paths with their steps, the default path first, then by name.

List escalation paths › query Parameters

page
​integer

Page number, from 1.

Default: 1
per_page
​integer

Paths per page, 1 to 100.

Default: 25

List escalation paths › Responses

Paginated set of EscalationPath

current_page
​integer · min: 1 · required
​EscalationPath[] · 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 escalation path

POST
https://api.spectate.net/v1
/escalation-paths

Channels and schedules must belong to the team; a branch ends its list of steps (422 with the step's position, for example steps.1.then.0.channel_id). Paging the person on call is part of the Team plan and up, and so are paths besides the default one (403 PLAN_LIMIT_REACHED).

Create an escalation path › Request Body

A new escalation path.
CreateEscalationPath
name
​string · maxLength: 255 · required

Name, up to 255 characters

Example: On-call engineers
description
​string | null · maxLength: 1000

What the path is for, up to 1000 characters

enabled
​boolean

Whether alerts follow the path. Default true

is_default
​boolean

Make it the team's default path; the current default stops being one. Default false

​

The steps, in order, up to 99 in total. Leave out or [] for a path that does nothing yet

Create an escalation path › Responses

The new escalation path.

An escalation path: what happens when an alert fires, step by step, until someone acknowledges it. Monitors, hosts, domains and alert sources use their own paths, their project's, or the team's default path.
EscalationPath
id
​string · uuid · required

Escalation path ID

name
​string · required

Name

Example: On-call engineers
description
​string | null · required

What the path is for

enabled
​boolean · required

Whether alerts follow the path. Alerts of a disabled path don't escalate

is_default
​boolean · required

Whether this is the team's default path, for resources without paths of their own or of their project. One per team

​WorkingHours · required

The working hours that branch conditions and "until working hours" waits use

​EscalationStep[] · required

The steps, in order; a branch continues in its then and else steps

​EscalationPathWarning[] · required

Problems that keep the path from reaching someone; empty when it can deliver

created_at
​string · date-time · required

When the path was created

Get an escalation path

GET
https://api.spectate.net/v1
/escalation-paths/{path}

Returns the path with its steps as a tree and the problems that keep it from delivering.

Get an escalation path › path Parameters

path
​string · uuid · required

Escalation path ID.

Get an escalation path › Responses

The escalation path.

An escalation path: what happens when an alert fires, step by step, until someone acknowledges it. Monitors, hosts, domains and alert sources use their own paths, their project's, or the team's default path.
EscalationPath
id
​string · uuid · required

Escalation path ID

name
​string · required

Name

Example: On-call engineers
description
​string | null · required

What the path is for

enabled
​boolean · required

Whether alerts follow the path. Alerts of a disabled path don't escalate

is_default
​boolean · required

Whether this is the team's default path, for resources without paths of their own or of their project. One per team

​WorkingHours · required

The working hours that branch conditions and "until working hours" waits use

​EscalationStep[] · required

The steps, in order; a branch continues in its then and else steps

​EscalationPathWarning[] · required

Problems that keep the path from reaching someone; empty when it can deliver

created_at
​string · date-time · required

When the path was created

Update an escalation path

PATCH
https://api.spectate.net/v1
/escalation-paths/{path}

Changes only the fields you send; steps replaces all steps. Alerts that are already escalating keep the steps they started with. Making a path the default takes that from the current default path.

Update an escalation path › path Parameters

path
​string · uuid · required

Escalation path ID.

Update an escalation path › Request Body

Changes to an escalation path; fields you leave out keep their value. `steps` replaces all steps. Alerts already escalating keep the steps they started with.
UpdateEscalationPath
name
​string · maxLength: 255

Name, up to 255 characters

Example: On-call engineers
description
​string | null · maxLength: 1000

What the path is for, up to 1000 characters

enabled
​boolean

Whether alerts follow the path

is_default
​boolean

Make it the team's default path (the current default stops being one), or not

​

All steps, in order, up to 99 in total; replaces the current steps

Update an escalation path › Responses

The updated escalation path.

An escalation path: what happens when an alert fires, step by step, until someone acknowledges it. Monitors, hosts, domains and alert sources use their own paths, their project's, or the team's default path.
EscalationPath
id
​string · uuid · required

Escalation path ID

name
​string · required

Name

Example: On-call engineers
description
​string | null · required

What the path is for

enabled
​boolean · required

Whether alerts follow the path. Alerts of a disabled path don't escalate

is_default
​boolean · required

Whether this is the team's default path, for resources without paths of their own or of their project. One per team

​WorkingHours · required

The working hours that branch conditions and "until working hours" waits use

​EscalationStep[] · required

The steps, in order; a branch continues in its then and else steps

​EscalationPathWarning[] · required

Problems that keep the path from reaching someone; empty when it can deliver

created_at
​string · date-time · required

When the path was created

Delete an escalation path

DELETE
https://api.spectate.net/v1
/escalation-paths/{path}

Monitors, hosts, domains, projects and alert sources that used it fall back to their project's paths or the team's default path. Alerts that are escalating on it stop.

Delete an escalation path › path Parameters

path
​string · uuid · required

Escalation path ID.

Delete an escalation path › Responses

No content

No data returned
ChannelsAlert sources