Spectate
Spectate API
Spectate API

Incidents

Download schema

Problems that affect customers, worked on by the team: declare one, post updates as you learn more, assign a commander and a communications lead, resolve it and write the postmortem. Changes show in the incident's Slack channel and timeline, named after the API token that made them. Publish to status pages with publishIncidentStatusPageUpdate.

List incidents

GET
https://api.spectate.net/v1
/incidents

Returns the team's incidents, most recently started first unless you sort.

List incidents › query Parameters

page
​integer

Page number, from 1.

Default: 1
per_page
​integer

Incidents per page, 1 to 100.

Default: 25
filter[status]
​IncidentStatus · enum

Only incidents with this status.

Where an incident stands.

investigating
Declared; the cause isn't known yet.
identified
Acknowledged: the cause is known and someone works on it.
monitoring
A fix is out; watching whether it holds.
resolved
Over.
Enum values:
investigating
identified
monitoring
resolved
filter[severity]
​Severity · enum

Only incidents of this severity.

How urgent an alert or incident is. Escalation paths can branch on it.

critical
Customers are affected right now.
high
Serious, needs attention soon.
medium
Should be looked at.
low
Informational.
Enum values:
critical
high
medium
low
filter[title]
​string

Case-insensitive text in the title.

sort
​string

Sort by started_at, created_at, severity, status or title. Prefix - for descending. Default -started_at.

List incidents › Responses

Paginated set of Incident

current_page
​integer · min: 1 · required
​Incident[] · 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.

Declare an incident

POST
https://api.spectate.net/v1
/incidents

It starts investigating. With Slack connected it's announced there like an incident declared in the dashboard, with its own channel when the Slack settings say so.

Declare an incident › Request Body

A new incident.
CreateIncident
title
​string · maxLength: 255 · required

What's going on, up to 255 characters

Example: Checkout fails for some customers
severity
​Severity · enum · required

How bad it is

critical
Customers are affected right now.
high
Serious, needs attention soon.
medium
Should be looked at.
low
Informational.
Enum values:
critical
high
medium
low
summary
​string | null

More about it, in Markdown

Declare an incident › Responses

The new incident.

An incident: a problem that affects customers, worked on by the team, with updates, roles and eventually a postmortem. Incidents are declared by hand, through the API, from Slack, or by an escalation path's `create_incident` step.
Incident
id
​string · uuid · required

Incident ID

number
​integer | null · required

The team's sequence number: INC-42 is 42. null for some older incidents

Example: 42
reference
​string · required

The human reference

Example: INC-42
title
​string · required

What's going on

Example: Checkout fails for some customers
summary
​string | null · required

More about it, in Markdown

severity
​Severity · enum · required

How bad it is

critical
Customers are affected right now.
high
Serious, needs attention soon.
medium
Should be looked at.
low
Informational.
Enum values:
critical
high
medium
low
status
​IncidentStatus · enum · required

Where it stands

investigating
Declared; the cause isn't known yet.
identified
Acknowledged: the cause is known and someone works on it.
monitoring
A fix is out; watching whether it holds.
resolved
Over.
Enum values:
investigating
identified
monitoring
resolved
started_at
​string · date-time · required

When it started

acknowledged_at
​string | null · date-time · required

When someone acknowledged it

resolved_at
​string | null · date-time · required

When it was resolved

alert_id
​string | null · uuid · required

The alert that opened it, for incidents declared by an escalation path

​IncidentRoleAssignment[] · required

Who has which role

created_at
​string · date-time · required

When it was declared

Get an incident

GET
https://api.spectate.net/v1
/incidents/{incident}

Returns the incident with its roles and the alert that opened it.

Get an incident › path Parameters

incident
​string · uuid · required

Incident ID.

Get an incident › Responses

The incident.

An incident: a problem that affects customers, worked on by the team, with updates, roles and eventually a postmortem. Incidents are declared by hand, through the API, from Slack, or by an escalation path's `create_incident` step.
Incident
id
​string · uuid · required

Incident ID

number
​integer | null · required

The team's sequence number: INC-42 is 42. null for some older incidents

Example: 42
reference
​string · required

The human reference

Example: INC-42
title
​string · required

What's going on

Example: Checkout fails for some customers
summary
​string | null · required

More about it, in Markdown

severity
​Severity · enum · required

How bad it is

critical
Customers are affected right now.
high
Serious, needs attention soon.
medium
Should be looked at.
low
Informational.
Enum values:
critical
high
medium
low
status
​IncidentStatus · enum · required

Where it stands

investigating
Declared; the cause isn't known yet.
identified
Acknowledged: the cause is known and someone works on it.
monitoring
A fix is out; watching whether it holds.
resolved
Over.
Enum values:
investigating
identified
monitoring
resolved
started_at
​string · date-time · required

When it started

acknowledged_at
​string | null · date-time · required

When someone acknowledged it

resolved_at
​string | null · date-time · required

When it was resolved

alert_id
​string | null · uuid · required

The alert that opened it, for incidents declared by an escalation path

​IncidentRoleAssignment[] · required

Who has which role

created_at
​string · date-time · required

When it was declared

Update an incident

PATCH
https://api.spectate.net/v1
/incidents/{incident}

Changes only the fields you send. Status and severity changes are announced like in the dashboard. To share what's known, post an update instead.

Update an incident › path Parameters

incident
​string · uuid · required

Incident ID.

Update an incident › Request Body

Changes to an incident; fields you leave out keep their value. To post what's known, use `createIncidentUpdate`; to close it, `resolveIncident`.
UpdateIncident
title
​string · maxLength: 255

What's going on

Example: Checkout fails for some customers
summary
​string | null

More about it, in Markdown

severity
​Severity · enum

How bad it is. Changing it is announced in the incident's Slack channel

critical
Customers are affected right now.
high
Serious, needs attention soon.
medium
Should be looked at.
low
Informational.
Enum values:
critical
high
medium
low
status
​IncidentStatus · enum

Where it stands, without posting an update

investigating
Declared; the cause isn't known yet.
identified
Acknowledged: the cause is known and someone works on it.
monitoring
A fix is out; watching whether it holds.
resolved
Over.
Enum values:
investigating
identified
monitoring
resolved

Update an incident › Responses

The updated incident.

An incident: a problem that affects customers, worked on by the team, with updates, roles and eventually a postmortem. Incidents are declared by hand, through the API, from Slack, or by an escalation path's `create_incident` step.
Incident
id
​string · uuid · required

Incident ID

number
​integer | null · required

The team's sequence number: INC-42 is 42. null for some older incidents

Example: 42
reference
​string · required

The human reference

Example: INC-42
title
​string · required

What's going on

Example: Checkout fails for some customers
summary
​string | null · required

More about it, in Markdown

severity
​Severity · enum · required

How bad it is

critical
Customers are affected right now.
high
Serious, needs attention soon.
medium
Should be looked at.
low
Informational.
Enum values:
critical
high
medium
low
status
​IncidentStatus · enum · required

Where it stands

investigating
Declared; the cause isn't known yet.
identified
Acknowledged: the cause is known and someone works on it.
monitoring
A fix is out; watching whether it holds.
resolved
Over.
Enum values:
investigating
identified
monitoring
resolved
started_at
​string · date-time · required

When it started

acknowledged_at
​string | null · date-time · required

When someone acknowledged it

resolved_at
​string | null · date-time · required

When it was resolved

alert_id
​string | null · uuid · required

The alert that opened it, for incidents declared by an escalation path

​IncidentRoleAssignment[] · required

Who has which role

created_at
​string · date-time · required

When it was declared

Delete an incident

DELETE
https://api.spectate.net/v1
/incidents/{incident}

Deletes it for good, open or resolved, with its updates, role assignments and postmortem. Nothing else goes with it: the alert that opened it keeps firing or stays resolved, status page incidents published from it stay on their pages, and its Slack channel isn't archived.

Delete an incident › path Parameters

incident
​string · uuid · required

Incident ID.

Delete an incident › Responses

No content

No data returned

Acknowledge an incident

POST
https://api.spectate.net/v1
/incidents/{incident}/acknowledge

Moves it to identified and stops the escalation of the alert that opened it.

Acknowledge an incident › path Parameters

incident
​string · uuid · required

Incident ID.

Acknowledge an incident › Responses

The acknowledged incident.

An incident: a problem that affects customers, worked on by the team, with updates, roles and eventually a postmortem. Incidents are declared by hand, through the API, from Slack, or by an escalation path's `create_incident` step.
Incident
id
​string · uuid · required

Incident ID

number
​integer | null · required

The team's sequence number: INC-42 is 42. null for some older incidents

Example: 42
reference
​string · required

The human reference

Example: INC-42
title
​string · required

What's going on

Example: Checkout fails for some customers
summary
​string | null · required

More about it, in Markdown

severity
​Severity · enum · required

How bad it is

critical
Customers are affected right now.
high
Serious, needs attention soon.
medium
Should be looked at.
low
Informational.
Enum values:
critical
high
medium
low
status
​IncidentStatus · enum · required

Where it stands

investigating
Declared; the cause isn't known yet.
identified
Acknowledged: the cause is known and someone works on it.
monitoring
A fix is out; watching whether it holds.
resolved
Over.
Enum values:
investigating
identified
monitoring
resolved
started_at
​string · date-time · required

When it started

acknowledged_at
​string | null · date-time · required

When someone acknowledged it

resolved_at
​string | null · date-time · required

When it was resolved

alert_id
​string | null · uuid · required

The alert that opened it, for incidents declared by an escalation path

​IncidentRoleAssignment[] · required

Who has which role

created_at
​string · date-time · required

When it was declared

Resolve an incident

POST
https://api.spectate.net/v1
/incidents/{incident}/resolve

Ends it, with an optional closing update. Its status page incidents stay as they are: resolve those with a status page update.

Resolve an incident › path Parameters

incident
​string · uuid · required

Incident ID.

Resolve an incident › Request Body

How an incident ends.
ResolveIncident
message
​string | null

A closing update, in Markdown; leave out for none

Example: Fixed by rolling back release 412.

Resolve an incident › Responses

The resolved incident.

An incident: a problem that affects customers, worked on by the team, with updates, roles and eventually a postmortem. Incidents are declared by hand, through the API, from Slack, or by an escalation path's `create_incident` step.
Incident
id
​string · uuid · required

Incident ID

number
​integer | null · required

The team's sequence number: INC-42 is 42. null for some older incidents

Example: 42
reference
​string · required

The human reference

Example: INC-42
title
​string · required

What's going on

Example: Checkout fails for some customers
summary
​string | null · required

More about it, in Markdown

severity
​Severity · enum · required

How bad it is

critical
Customers are affected right now.
high
Serious, needs attention soon.
medium
Should be looked at.
low
Informational.
Enum values:
critical
high
medium
low
status
​IncidentStatus · enum · required

Where it stands

investigating
Declared; the cause isn't known yet.
identified
Acknowledged: the cause is known and someone works on it.
monitoring
A fix is out; watching whether it holds.
resolved
Over.
Enum values:
investigating
identified
monitoring
resolved
started_at
​string · date-time · required

When it started

acknowledged_at
​string | null · date-time · required

When someone acknowledged it

resolved_at
​string | null · date-time · required

When it was resolved

alert_id
​string | null · uuid · required

The alert that opened it, for incidents declared by an escalation path

​IncidentRoleAssignment[] · required

Who has which role

created_at
​string · date-time · required

When it was declared

List an incident's updates

GET
https://api.spectate.net/v1
/incidents/{incident}/updates

Returns the updates, newest first.

List an incident's updates › path Parameters

incident
​string · uuid · required

Incident ID.

List an incident's updates › query Parameters

page
​integer

Page number, from 1.

Default: 1
per_page
​integer

Updates per page, 1 to 100.

Default: 25

List an incident's updates › Responses

Paginated set of IncidentUpdate

current_page
​integer · min: 1 · required
​IncidentUpdate[] · 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.

Post an incident update

POST
https://api.spectate.net/v1
/incidents/{incident}/updates

Adds what's known now to the timeline, optionally with a new status, and shares it like an update from the dashboard.

Post an incident update › path Parameters

incident
​string · uuid · required

Incident ID.

Post an incident update › Request Body

An update to post to an incident.
CreateIncidentUpdate
body
​string · required

What's known now, in Markdown

Example: Rolled back the deploy; error rates are dropping.
status
​IncidentStatus · enum

Move the incident to this status with the update; leave out to keep it

investigating
Declared; the cause isn't known yet.
identified
Acknowledged: the cause is known and someone works on it.
monitoring
A fix is out; watching whether it holds.
resolved
Over.
Enum values:
investigating
identified
monitoring
resolved

Post an incident update › Responses

The posted update.

An update posted to an incident: what's known now, and its status at that moment.
IncidentUpdate
id
​string · uuid · required

Update ID

status
​IncidentStatus · enum · required

The incident's status with this update

investigating
Declared; the cause isn't known yet.
identified
Acknowledged: the cause is known and someone works on it.
monitoring
A fix is out; watching whether it holds.
resolved
Over.
Enum values:
investigating
identified
monitoring
resolved
body
​string · required

The update, in Markdown

Example: Rolled back the deploy; error rates are dropping.
created_at
​string · date-time · required

When it was posted

Get an incident's timeline

GET
https://api.spectate.net/v1
/incidents/{incident}/timeline

Everything that happened, newest first: declaring, updates, status and severity changes, roles, acknowledging and resolving, with who did it.

Get an incident's timeline › path Parameters

incident
​string · uuid · required

Incident ID.

Get an incident's timeline › query Parameters

page
​integer

Page number, from 1.

Default: 1
per_page
​integer

Entries per page, 1 to 100.

Default: 25

Get an incident's timeline › Responses

Paginated set of IncidentTimelineEntry

current_page
​integer · min: 1 · required
​IncidentTimelineEntry[] · 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.

Assign an incident role

PUT
https://api.spectate.net/v1
/incidents/{incident}/roles/{role}

Gives the role to a member of the team, replacing whoever had it.

Assign an incident role › path Parameters

incident
​string · uuid · required

Incident ID.

role
​IncidentRole · enum · required

The role.

A role in handling an incident; one member each.

commander
Leads the response and makes the calls.
communications_lead
Keeps customers and the company informed, for example through the status page.
Enum values:
commander
communications_lead

Assign an incident role › Request Body

Who gets an incident role.
AssignIncidentRole
member_id
​string · uuid · required

The member who takes the role; they replace whoever had it

Assign an incident role › Responses

The incident with its roles.

An incident: a problem that affects customers, worked on by the team, with updates, roles and eventually a postmortem. Incidents are declared by hand, through the API, from Slack, or by an escalation path's `create_incident` step.
Incident
id
​string · uuid · required

Incident ID

number
​integer | null · required

The team's sequence number: INC-42 is 42. null for some older incidents

Example: 42
reference
​string · required

The human reference

Example: INC-42
title
​string · required

What's going on

Example: Checkout fails for some customers
summary
​string | null · required

More about it, in Markdown

severity
​Severity · enum · required

How bad it is

critical
Customers are affected right now.
high
Serious, needs attention soon.
medium
Should be looked at.
low
Informational.
Enum values:
critical
high
medium
low
status
​IncidentStatus · enum · required

Where it stands

investigating
Declared; the cause isn't known yet.
identified
Acknowledged: the cause is known and someone works on it.
monitoring
A fix is out; watching whether it holds.
resolved
Over.
Enum values:
investigating
identified
monitoring
resolved
started_at
​string · date-time · required

When it started

acknowledged_at
​string | null · date-time · required

When someone acknowledged it

resolved_at
​string | null · date-time · required

When it was resolved

alert_id
​string | null · uuid · required

The alert that opened it, for incidents declared by an escalation path

​IncidentRoleAssignment[] · required

Who has which role

created_at
​string · date-time · required

When it was declared

Remove an incident role

DELETE
https://api.spectate.net/v1
/incidents/{incident}/roles/{role}

Nobody has the role afterwards. Removing a role nobody has changes nothing.

Remove an incident role › path Parameters

incident
​string · uuid · required

Incident ID.

role
​IncidentRole · enum · required

The role.

A role in handling an incident; one member each.

commander
Leads the response and makes the calls.
communications_lead
Keeps customers and the company informed, for example through the status page.
Enum values:
commander
communications_lead

Remove an incident role › Responses

No content

No data returned

Get an incident's postmortem

GET
https://api.spectate.net/v1
/incidents/{incident}/postmortem

postmortem is null until one is written.

Get an incident's postmortem › path Parameters

incident
​string · uuid · required

Incident ID.

Get an incident's postmortem › Responses

The postmortem, if any.

An incident's postmortem, if it has one.
IncidentPostmortemResult
​required

Write an incident's postmortem

PUT
https://api.spectate.net/v1
/incidents/{incident}/postmortem

Creates the postmortem, or replaces its content.

Write an incident's postmortem › path Parameters

incident
​string · uuid · required

Incident ID.

Write an incident's postmortem › Request Body

An incident's postmortem.
SavePostmortem
content
​string · required

The whole postmortem, in Markdown; replaces the current one

published
​boolean

Mark it as published (final), or as a draft again. Leave out to keep its state

Write an incident's postmortem › Responses

The saved postmortem.

An incident's postmortem: what happened, why, and what changes.
IncidentPostmortem
content
​string | null · required

The postmortem, in Markdown

published
​boolean · required

Whether it is marked as published (final). It is not shown on status pages

updated_at
​string · date-time · required

When it last changed

Publish to a status page

POST
https://api.spectate.net/v1
/incidents/{incident}/status-page-updates

Posts an update of this incident on one of the team's status pages, creating the public incident there the first time (201; later updates answer 200). The public incident takes the incident's title. affected_components are the impacts as of published_at (default now); leave the field out to keep them. Confirmed subscribers are emailed unless notify_subscribers is false. Needs both incidents:write and status-pages:write.

Publish to a status page › path Parameters

incident
​string · uuid · required

Incident ID.

Publish to a status page › Request Body

An update of the team's incident to publish on a status page.
PublishStatusPageUpdate
status_page_id
​string · uuid · required

The status page to publish on

status
​IncidentStatus · enum · required

The public incident's status with this update. resolved closes every open impact period

investigating
Declared; the cause isn't known yet.
identified
Acknowledged: the cause is known and someone works on it.
monitoring
A fix is out; watching whether it holds.
resolved
Over.
Enum values:
investigating
identified
monitoring
resolved
body
​string · required

The message visitors read, in Markdown

Example: We found the cause and are rolling out a fix.
impact
​ImpactLevel · enum

The public incident's own impact, used while it affects no components; otherwise it follows the components

none
No impact (for a component: not affected).
degraded_performance
Slower or less reliable than usual.
partial_outage
Down for some visitors or some functions.
major_outage
Down.
Enum values:
none
degraded_performance
partial_outage
major_outage
published_at
​string | null · date-time

When it happened, now or in the past (default now)

The components it affects as of published_at, with their impact; components left out are no longer affected. Leave out to keep the impacts as they are; send [] for none. Components of the status page only

notify_subscribers
​boolean

Email confirmed subscribers about the update (default true). false changes the page without emails

Publish to a status page › Responses

The public incident, updated.

A public incident on a status page: what visitors read, separate from the team's own incident (which can publish to it). Its impact on components is a timeline of periods.
StatusPageIncident
id
​string · uuid · required

Status page incident ID

title
​string · required

Title shown on the page

Example: Elevated API error rates
status
​IncidentStatus · enum · required

Where it stands: the status of its latest update

investigating
Declared; the cause isn't known yet.
identified
Acknowledged: the cause is known and someone works on it.
monitoring
A fix is out; watching whether it holds.
resolved
Over.
Enum values:
investigating
identified
monitoring
resolved
impact
​ImpactLevel · enum · required

The worst ongoing impact of its periods (the peak once resolved), none without one. An incident that affects no components keeps the impact it was given

none
No impact (for a component: not affected).
degraded_performance
Slower or less reliable than usual.
partial_outage
Down for some visitors or some functions.
major_outage
Down.
Enum values:
none
degraded_performance
partial_outage
major_outage
incident_id
​string | null · uuid · required

The team's incident that publishes to it; null for none

automated
​boolean · required

Opened by monitor automation and still managed by it, until someone posts an update or edits its timeline

​StatusPageIncidentUpdate[] · required

Updates, newest first

​StatusPageAffectedComponent[] · required

Components it affects or affected

​StatusPageImpactPeriod[] · required

The impact timeline, oldest first

resolved_at
​string | null · date-time · required

When it was resolved; null while open

created_at
​string · date-time · required

When it was created

​required
On-callStatus pages