incident.io (1.0.0)

Download OpenAPI specification:Download

This is the API reference for incident.io.

It documents available API endpoints, provides examples of how to use it, and instructions around things like authentication and error handling.

The API is hosted at:

And you will need to create an API key via your [incident.io dashboard][app/api-keys] to make requests.

Making requests

Here are the key concepts required to make requests to the incident.io API.

Authentication

For all requests made to the incident.io API, you'll need an API key.

To create an API key, head to the incident dashboard and visit API keys. When you create the key, you'll be able to choose what actions it can take for your account: choose carefully, as those roles can only be set when you first create the key. We'll only show you the token once, so make sure you store it somewhere safe.

Once you have the key, you should make requests to the API that set the Authorization request header using a "Bearer" authentication scheme:

Authorization: Bearer <YOUR_API_KEY>

Errors

We use standard HTTP response codes to indicate the status or failure of API requests.

The API response body will be JSON, and contain more detailed information on the nature of the error.

An example error when a request is made without an API key:

{
  "type": "authentication_error",
  "status": 401,
  "request_id": "8e3cc412-b49d-4957-9073-2c19d2c61804",
  "errors": [
    {
      "code": "missing_authorization_material",
      "message": "No authorization material provided in request"
    }
  ]
}

Note that the error:

  • Contains the HTTP status (401)
  • References the type of error (authentication_error)
  • Includes a request_id that can be provided to incident.io support to help debug questions with your API request
  • Provides a list of individual errors, which go into detail about why the error occurred

The most common error will be a 422 Validation Error, which is returned when the request was rejected due to failing validations.

These errors look like this:

{
  "type": "validation_error",
  "status": 422,
  "request_id": "631766c4-4afd-4803-997c-cd700928fa4b",
  "errors": [
    {
      "code": "is_required",
      "message": "A severity is required to open an incident",
      "source": {
        "field": "severity_id"
      }
    }
  ]
}

This error is caused by not providing a severity identifier, which should be at the severity_id field of the request payload. Errors like these can be mapped to forms, should you be integrating with the API from a user-interface.

Actions

Manage incident actions.

Incidents have two types of actions associated to them:

  • Actions, used during an incident response as ephemeral todo lists
  • Follow-ups, actions which are for after the incident and can be exported to external issue trackers

You can manage actions in the incident Slack channel with /incident actions, or on the incident homepage.

Exporting follow-ups to external issue trackers can be done in the incident homepage.

List Actions

List all actions for an organisation.

Request
query Parameters
incident_id
string

Find actions related to this incident

is_follow_up
boolean

Filter to actions marked as being follow up actions

exclude_test_incidents
boolean

Don't return actions attached to test incidents

Responses
200

OK response.

get/v1/actions
Request samples
curl -i -X GET \
  'https://api.incident.io/v1/actions?incident_id=string&is_follow_up=true&exclude_test_incidents=true'
Response samples
{
  • "actions": [
    ]
}

Show Actions

Get a single incident action.

Request
path Parameters
id
required
string

Unique identifier for the action

Responses
200

OK response.

get/v1/actions/{id}
Request samples
curl -i -X GET \
  'https://api.incident.io/v1/actions/{id}'
Response samples
{
  • "action": {
    }
}

Custom Fields

Manage custom fields.

Custom fields are used to attach metadata to incidents, which you can use when searching for incidents in the dashboard, triggering workflows, building announcement rules or for your own data needs.

Each field has a type:

  • Single-select, single value selected from a predefined list of options (ie. Incident Type)
  • Multi-select, as above but you can pick more than one option (ie. Teams)
  • Text, freeform text field (ie. Customer ID)
  • Link, link URL that is synced to Slack bookmarks on the incident channel (ie. External Status Page)
  • Number, integer or fractional numbers (ie. Customers Affected)

We may add more custom field types in the future - we'd love to hear any other types you'd like to use!

List Custom Fields

List all custom fields for an organisation.

Responses
200

OK response.

get/v1/custom_fields
Request samples
curl -i -X GET \
  https://api.incident.io/v1/custom_fields
Response samples
{
  • "custom_fields": [
    ]
}

Create Custom Fields

Create a new custom field

Request
Request Body schema:
description
required
string

Description of the custom field

field_type
required
string

Type of custom field

Enum: "single_select" "multi_select" "text" "link" "numeric"
name
required
string <= 50 characters

Human readable name for the custom field

required
required
string

When this custom field must be set during the incident lifecycle.

Enum: "never" "before_closure" "always"
show_before_closure
required
boolean

Whether a custom field should be shown in the incident close modal. If this custom field is required before closure, but no value has been set for it, the field will be shown in the closure modal whatever the value of this setting.

show_before_creation
required
boolean

Whether a custom field should be shown in the incident creation modal. This must be true if the field is always required.

Responses
201

Created response.

post/v1/custom_fields
Request samples
{
  • "description": "Which team is impacted by this issue",
  • "field_type": "single_select",
  • "name": "Affected Team",
  • "required": "never",
  • "show_before_closure": true,
  • "show_before_creation": true
}
Response samples
{
  • "custom_field": {
    }
}

Show Custom Fields

Get a single custom field.

Request
path Parameters
id
required
string

Unique identifier for the custom field

Responses
200

OK response.

get/v1/custom_fields/{id}
Request samples
curl -i -X GET \
  'https://api.incident.io/v1/custom_fields/{id}'
Response samples
{
  • "custom_field": {
    }
}

Update Custom Fields

Update the details of a custom field

Request
path Parameters
id
required
string

Unique identifier for the custom field

Request Body schema:
description
required
string

Description of the custom field

name
required
string <= 50 characters

Human readable name for the custom field

required
required
string

When this custom field must be set during the incident lifecycle.

Enum: "never" "before_closure" "always"
show_before_closure
required
boolean

Whether a custom field should be shown in the incident close modal. If this custom field is required before closure, but no value has been set for it, the field will be shown in the closure modal whatever the value of this setting.

show_before_creation
required
boolean

Whether a custom field should be shown in the incident creation modal. This must be true if the field is always required.

Responses
200

OK response.

put/v1/custom_fields/{id}
Request samples
{
  • "description": "Which team is impacted by this issue",
  • "name": "Affected Team",
  • "required": "never",
  • "show_before_closure": true,
  • "show_before_creation": true
}
Response samples
{
  • "custom_field": {
    }
}

Delete Custom Fields

Delete a custom field

Request
path Parameters
id
required
string

Unique identifier for the custom field

Responses
204

No Content response.

delete/v1/custom_fields/{id}
Request samples
curl -i -X DELETE \
  'https://api.incident.io/v1/custom_fields/{id}'

Custom Field Options

Manage custom field options.

Single- and multi-select custom fields have a list of all available options, which have a value, and a sort key. The value must be unique to the custom field. For example, you might have an Incident Type custom field, with options "Data breach", "Performance degradation", "API downtime", etc.

List Custom Field Options

Show custom field options for a custom field

Request
query Parameters
page_size
integer
Default: 25

number of records to return

after
string

A custom field option's ID. This endpoint will return a list of custom field options created after this option.

custom_field_id
required
string

The custom field to list options for.

Responses
200

OK response.

get/v1/custom_field_options
Request samples
curl -i -X GET \
  'https://api.incident.io/v1/custom_field_options?page_size=25&after=string&custom_field_id=string'
Response samples
{
  • "custom_field_options": [
    ]
}

Create Custom Field Options

Create a custom field option. If the sort key is not supplied, it'll default to 1000, so the option appears near the end of the list.

Request
Request Body schema:
custom_field_id
required
string

ID of the custom field this option belongs to

sort_key
integer <int64>
Default: 1000

Sort key used to order the custom field options correctly

value
required
string

Human readable name for the custom field option

Responses
201

Created response.

post/v1/custom_field_options
Request samples
{
  • "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
  • "sort_key": 10,
  • "value": "Product"
}
Response samples
{
  • "custom_field_option": {
    }
}

Show Custom Field Options

Get a single custom field option

Request
path Parameters
id
required
string

Unique identifier for the custom field option

Responses
200

OK response.

get/v1/custom_field_options/{id}
Request samples
curl -i -X GET \
  'https://api.incident.io/v1/custom_field_options/{id}'
Response samples
{
  • "custom_field_option": {
    }
}

Update Custom Field Options

Update a custom field option

Request
path Parameters
id
required
string

Unique identifier for the custom field option

Request Body schema:
sort_key
required
integer <int64>
Default: 1000

Sort key used to order the custom field options correctly

value
required
string

Human readable name for the custom field option

Responses
200

OK response.

put/v1/custom_field_options/{id}
Request samples
{
  • "sort_key": 10,
  • "value": "Product"
}
Response samples
{
  • "custom_field_option": {
    }
}

Delete Custom Field Options

Delete a custom field option

Request
path Parameters
id
required
string

Unique identifier for the custom field option

Responses
204

No Content response.

delete/v1/custom_field_options/{id}
Request samples
curl -i -X DELETE \
  'https://api.incident.io/v1/custom_field_options/{id}'

Severities

Manage incident severities.

Each incident has a severity, picked from one of the severities configured in your organisations settings.

Severities help categorise incidents, and communicate urgency/impact. You can use severities when filtering incidents in the dashboard, and in workflows and announcement rules.

List Severities

List all incident severities for an organisation.

Responses
200

OK response.

get/v1/severities
Request samples
curl -i -X GET \
  https://api.incident.io/v1/severities
Response samples
{
  • "severities": [
    ]
}

Create Severities

Create a new severity

Request
Request Body schema:
description
required
string <= 1000 characters

Description of the severity

name
required
string <= 50 characters

Human readable name of the severity

rank
integer <int64>

Rank to help sort severities (lower numbers are less severe)

Responses
201

Created response.

post/v1/severities
Request samples
{
  • "description": "It's not really that bad, everyone chill",
  • "name": "Minor",
  • "rank": 1
}
Response samples
{
  • "severity": {
    }
}

Show Severities

Get a single incident severity.

Request
path Parameters
id
required
string

Unique identifier of the severity

Responses
200

OK response.

get/v1/severities/{id}
Request samples
curl -i -X GET \
  'https://api.incident.io/v1/severities/{id}'
Response samples
{
  • "severity": {
    }
}

Update Severities

Update an existing severity

Request
path Parameters
id
required
string

Unique identifier of the severity

Request Body schema:
description
required
string <= 1000 characters

Description of the severity

name
required
string <= 50 characters

Human readable name of the severity

rank
integer <int64>

Rank to help sort severities (lower numbers are less severe)

Responses
200

OK response.

put/v1/severities/{id}
Request samples
{
  • "description": "It's not really that bad, everyone chill",
  • "name": "Minor",
  • "rank": 1
}
Response samples
{
  • "severity": {
    }
}

Delete Severities

Delete a severity

Request
path Parameters
id
required
string

Unique identifier of the severity

Responses
202

Accepted response.

delete/v1/severities/{id}
Request samples
curl -i -X DELETE \
  'https://api.incident.io/v1/severities/{id}'

Incident Roles

Manage incident roles.

During an incident, you can assign responders to one of the incident roles that are configured in your organisation settings.

Every organisation will have a special 'lead' role, which signifies the incident lead or commander. This role cannot be deleted, but can be renamed in the incident.io dashboard.

List Incident Roles

List all incident roles for an organisation.

Responses
200

OK response.

get/v1/incident_roles
Request samples
curl -i -X GET \
  https://api.incident.io/v1/incident_roles
Response samples
{
  • "incident_roles": [
    ]
}

Create Incident Roles

Create a new incident role

Request
Request Body schema:
description
required
string non-empty

Describes the purpose of the role

instructions
required
string non-empty

Provided to whoever is nominated for the role

name
required
string non-empty

Human readable name of the incident role

required
required
boolean

Whether incident require this role to be set

shortform
required
string non-empty

Short human readable name for Slack

Responses
201

Created response.

post/v1/incident_roles
Request samples
{
  • "description": "The person currently coordinating the incident",
  • "instructions": "Take point on the incident; Make sure people are clear on responsibilities",
  • "name": "Incident Lead",
  • "required": true,
  • "shortform": "lead"
}
Response samples
{
  • "incident_role": {
    }
}

Show Incident Roles

Get a single incident role.

Request
path Parameters
id
required
string

Unique identifier for the role

Responses
200

OK response.

get/v1/incident_roles/{id}
Request samples
curl -i -X GET \
  'https://api.incident.io/v1/incident_roles/{id}'
Response samples
{
  • "incident_role": {
    }
}

Update Incident Roles

Update an existing incident role

Request
path Parameters
id
required
string

Unique identifier for the role

Request Body schema:
description
required
string non-empty

Describes the purpose of the role

instructions
required
string non-empty

Provided to whoever is nominated for the role

name
required
string non-empty

Human readable name of the incident role

required
required
boolean

Whether incident require this role to be set

shortform
required
string non-empty

Short human readable name for Slack

Responses
200

OK response.

put/v1/incident_roles/{id}
Request samples
{
  • "description": "The person currently coordinating the incident",
  • "instructions": "Take point on the incident; Make sure people are clear on responsibilities",
  • "name": "Incident Lead",
  • "required": true,
  • "shortform": "lead"
}
Response samples
{
  • "incident_role": {
    }
}

Delete Incident Roles

Removes an existing role

Request
path Parameters
id
required
string

Unique identifier for the role

Responses
204

No Content response.

delete/v1/incident_roles/{id}
Request samples
curl -i -X DELETE \
  'https://api.incident.io/v1/incident_roles/{id}'

Incidents

Create and read incidents.

Incidents are a core resource, on which many other resources (actions, etc) are created.

Care should be taken around these endpoints, as automation that creates duplicate incidents can be distracting, and impact reporting.

List Incidents

List all incidents for an organisation.

Request
query Parameters
page_size
integer
Default: 25

number of records to return

after
string

An incident's ID. This endpoint will return a list of incidents created after this incident.

status
Array of strings

Filter for incidents in these statuses

Responses
200

OK response.

get/v1/incidents
Request samples
curl -i -X GET \
  'https://api.incident.io/v1/incidents?page_size=25&after=string&status=string'
Response samples
{
  • "incidents": [
    ],
  • "pagination_meta": {
    }
}

Create Incidents

Create a new incident.

Request
Request Body schema:
Array of objects (CustomFieldEntryPayloadRequestBody)

Set the incident's custom fields to these values

idempotency_key
required
string

Unique string used to de-duplicate incident create requests

Array of objects (IncidentRoleAssignmentPayloadRequestBody)

Assign incident roles to these people

incident_type_id
string
name
string

Explanation of the incident

severity_id
required
string
summary
string

Detailed description of the incident

visibility
required
string

Whether the incident should be open to anyone in your Slack workspace (public), or invite-only (private). For more information on Private Incidents see our help centre.

Enum: "public" "private"
Responses
200

OK response.

post/v1/incidents
Request samples
{
  • "custom_field_entries": [
    ],
  • "idempotency_key": "alert-uuid",
  • "incident_role_assignments": [
    ],
  • "incident_type_id": "Quidem amet.",
  • "name": "Our database is sad",
  • "severity_id": "Aut quis.",
  • "summary": "Our database is really really sad, and we don't know why yet.",
  • "visibility": "public"
}
Response samples
{
  • "incident": {
    }
}

Show Incidents

Get a single incident.

Request
path Parameters
id
required
string

Unique identifier for the incident

Responses
200

OK response.

get/v1/incidents/{id}
Request samples
curl -i -X GET \
  'https://api.incident.io/v1/incidents/{id}'
Response samples
{
  • "incident": {
    }
}

Utilities

Miscelaneous utility endpoints.

Collection of utility functions that can help build integrations against this API.

Identity Utilities

Test if your API key is valid, and which roles it has.

Responses
200

OK response.

get/v1/identity
Request samples
curl -i -X GET \
  https://api.incident.io/v1/identity
Response samples
{
  • "identity": {
    }
}

OpenAPI Utilities

Get the OpenAPI (v2) definition.

Responses
200

OK response.

get/v1/openapi.json
Request samples
curl -i -X GET \
  https://api.incident.io/v1/openapi.json
Response samples
null