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 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.

Compatibility

We won't make breaking changes to existing API services or endpoints, but will expect integrators to upgrade themselves to the latest API endpoints within 3 months of us deprecating the old service.

We will make changes that are considered backwards compatible, which include:

  • Adding new API endpoints and services
  • Adding new properties to responses from existing API endpoints
  • Reordering properties returned from existing API endpoints
  • Adding optional request parameters to existing API endpoints
  • Altering the format or length of IDs
  • Adding new values to enums

It is important that clients are robust to these changes, to ensure reliable integrations.

As an example, if you are generating a client using an openapi-generator, ensure the generated client is configured to support unknown enum values, often configured via the enumUnknownDefaultCase parameter.

When breaking changes are unavoidable, we'll create a new service version on a separate path, and run them in parallel.

For example:

For any questions, email support@incident.io.

Actions V1

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 V1

List all actions for an organisation.

Request
query Parameters
incident_id
string

Find actions related to this incident

Example: incident_id=01FCNDV6P870EA6S7TK1DSYDG0
is_follow_up
boolean

Filter to actions marked as being follow up actions

Example: is_follow_up=true
incident_mode
string

Filter to actions from incidents of the given mode. If not set, only actions from real incidents are returned

Enum: "real" "test" "tutorial" Examples:
incident_mode=real
Responses
200

OK response.

get/v1/actions
Request samples
Response samples
application/json
{
  • "actions": [
    ]
}

Show Actions V1

Get a single incident action.

Request
path Parameters
id
required
string

Unique identifier for the action

Example: 01FCNDV6P870EA6S7TK1DSYDG0
Responses
200

OK response.

get/v1/actions/{id}
Request samples
Response samples
application/json
{
  • "action": {
    }
}

Custom Field Options V1

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 V1

Show custom field options for a custom field

Request
query Parameters
page_size
integer <int64>
Default: 25

number of records to return

Example: page_size=25
after
string

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

Example: after=01G0J1EXE7AXZ2C93K61WBPYEH
custom_field_id
required
string

The custom field to list options for.

Example: custom_field_id=Nulla officiis deleniti quia.
Responses
200

OK response.

get/v1/custom_field_options
Request samples
Response samples
application/json
{
  • "custom_field_options": [
    ]
}

Create Custom Field Options V1

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: application/json
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
application/json
{
  • "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
  • "sort_key": 10,
  • "value": "Product"
}
Response samples
application/json
{
  • "custom_field_option": {
    }
}

Delete Custom Field Options V1

Delete a custom field option

Request
path Parameters
id
required
string

Unique identifier for the custom field option

Example: 01FCNDV6P870EA6S7TK1DSYDG0
Responses
204

No Content response.

delete/v1/custom_field_options/{id}
Request samples

Show Custom Field Options V1

Get a single custom field option

Request
path Parameters
id
required
string

Unique identifier for the custom field option

Example: 01FCNDV6P870EA6S7TK1DSYDG0
Responses
200

OK response.

get/v1/custom_field_options/{id}
Request samples
Response samples
application/json
{
  • "custom_field_option": {
    }
}

Update Custom Field Options V1

Update a custom field option

Request
path Parameters
id
required
string

Unique identifier for the custom field option

Example: 01FCNDV6P870EA6S7TK1DSYDG0
Request Body schema: application/json
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
application/json
{
  • "sort_key": 10,
  • "value": "Product"
}
Response samples
application/json
{
  • "custom_field_option": {
    }
}

Custom Fields V1

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 V1

List all custom fields for an organisation.

Responses
200

OK response.

get/v1/custom_fields
Request samples
Response samples
application/json
{
  • "custom_fields": [
    ]
}

Create Custom Fields V1

Create a new custom field

Request
Request Body schema: application/json
description
required
string

Description of the custom field

field_type
required
string

Type of custom field

Enum: "single_select" "multi_select" "text" "link" "numeric" "timestamp"
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.

show_in_announcement_post
boolean

Whether a custom field should be shown in the list of fields as part of the announcement post when set.

Responses
201

Created response.

post/v1/custom_fields
Request samples
application/json
{
  • "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,
  • "show_in_announcement_post": true
}
Response samples
application/json
{
  • "custom_field": {
    }
}

Delete Custom Fields V1

Delete a custom field

Request
path Parameters
id
required
string

Unique identifier for the custom field

Example: 01FCNDV6P870EA6S7TK1DSYDG0
Responses
204

No Content response.

delete/v1/custom_fields/{id}
Request samples

Show Custom Fields V1

Get a single custom field.

Request
path Parameters
id
required
string

Unique identifier for the custom field

Example: 01FCNDV6P870EA6S7TK1DSYDG0
Responses
200

OK response.

get/v1/custom_fields/{id}
Request samples
Response samples
application/json
{
  • "custom_field": {
    }
}

Update Custom Fields V1

Update the details of a custom field

Request
path Parameters
id
required
string

Unique identifier for the custom field

Example: 01FCNDV6P870EA6S7TK1DSYDG0
Request Body schema: application/json
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.

show_in_announcement_post
boolean

Whether a custom field should be shown in the list of fields as part of the announcement post when set.

Responses
200

OK response.

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

Incident Attachments V1

Create, list and delete incident attachments.

Incident Attachments allows you to connect resources from external systems into incidents. Examples include: PagerDuty incidents and GitHub pull requests.

List Incident Attachments V1

List all incident attachements for an external resouce

Request
query Parameters
incident_id
string

Incident that this attachment is against

Example: incident_id=01G0J1EXE7AXZ2C93K61WBPYEH
external_id
required
string

ID of the resource in the external system

Example: external_id=123
resource_type
required
string

E.g. PagerDuty: the external system that holds the resource

Enum: "pager_duty_incident" "github_pull_request" "sentry_issue" "zendesk_ticket" Examples:
resource_type=pager_duty_incident
Responses
200

OK response.

get/v1/incident_attachments
Request samples
Response samples
application/json
{
  • "incident_attachments": [
    ]
}

Create Incident Attachments V1

Attaches an external resource to an incident

Request
Request Body schema: application/json
incident_id
required
string
required
object
Responses
201

Created response.

post/v1/incident_attachments
Request samples
application/json
{
  • "incident_id": "Alias ut velit et accusamus.",
  • "resource": {
    }
}
Response samples
application/json
{
  • "incident_attachment": {
    }
}

Delete Incident Attachments V1

Unattaches an external resouce from an incident

Request
path Parameters
id
required
string

Unique identifier of this incident membership

Example: 01FCNDV6P870EA6S7TK1DSYD5H
Responses
204

No Content response.

delete/v1/incident_attachments/{id}
Request samples

Incident Roles V1

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 V1

List all incident roles for an organisation.

Responses
200

OK response.

get/v1/incident_roles
Request samples
Response samples
application/json
{
  • "incident_roles": [
    ]
}

Create Incident Roles V1

Create a new incident role

Request
Request Body schema: application/json
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
application/json
{
  • "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
application/json
{
  • "incident_role": {
    }
}

Delete Incident Roles V1

Removes an existing role

Request
path Parameters
id
required
string

Unique identifier for the role

Example: 01FCNDV6P870EA6S7TK1DSYDG0
Responses
204

No Content response.

delete/v1/incident_roles/{id}
Request samples

Show Incident Roles V1

Get a single incident role.

Request
path Parameters
id
required
string

Unique identifier for the role

Example: 01FCNDV6P870EA6S7TK1DSYDG0
Responses
200

OK response.

get/v1/incident_roles/{id}
Request samples
Response samples
application/json
{
  • "incident_role": {
    }
}

Update Incident Roles V1

Update an existing incident role

Request
path Parameters
id
required
string

Unique identifier for the role

Example: 01FCNDV6P870EA6S7TK1DSYDG0
Request Body schema: application/json
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
application/json
{
  • "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
application/json
{
  • "incident_role": {
    }
}

Incident Types V1

View incident types.

With incident types enabled, you can tailor your process to the situation you're responding to with different custom fields and roles for each incident type.

List Incident Types V1

List all incident types for an organisation.

Responses
200

OK response.

get/v1/incident_types
Request samples
Response samples
application/json
{
  • "incident_types": [
    ]
}

Show Incident Types V1

Get a single incident type.

Request
path Parameters
id
required
string

Unique identifier for this Incident Type

Example: 01FCNDV6P870EA6S7TK1DSYDG0
Responses
200

OK response.

get/v1/incident_types/{id}
Request samples
Response samples
application/json
{
  • "incident_type": {
    }
}

Incidents V1

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 V1Deprecated

List all incidents for an organisation.

Request
query Parameters
page_size
integer <int64>
Default: 25

number of records to return

Example: page_size=25
after
string

An incident's ID. This endpoint will return a list of incidents after this ID in relation to the API response order.

Example: after=01FDAG4SAP5TYPT98WGR2N7W91
status
Array of strings

Filter for incidents in these statuses

Examples:
status=declined
Responses
200

OK response.

get/v1/incidents
Request samples
Response samples
application/json
{
  • "incidents": [
    ],
  • "pagination_meta": {
    }
}

Create Incidents V1Deprecated

Create a new incident.

Request
Request Body schema: application/json
Array of objects (CustomFieldEntryPayloadV1)

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 (IncidentRoleAssignmentPayloadV1)

Assign incident roles to these people

incident_type_id
string

Incident type to create this incident as

mode
string

Whether the incident is real or test

Enum: "real" "test"
name
string

Explanation of the incident

severity_id
required
string

Severity to create incident as

source_message_channel_id
string

Channel ID of the source message, if this incident was created from one

source_message_timestamp
string

Timestamp of the source message, if this incident was created from one

status
string

Current status of the incident

Enum: "triage" "investigating" "fixing" "monitoring" "closed" "declined"
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
application/json
{
  • "custom_field_entries": [
    ],
  • "idempotency_key": "alert-uuid",
  • "incident_role_assignments": [
    ],
  • "incident_type_id": "01FH5TZRWMNAFB0DZ23FD1TV96",
  • "mode": "real",
  • "name": "Our database is sad",
  • "severity_id": "01FH5TZRWMNAFB0DZ23FD1TV96",
  • "source_message_channel_id": "C02AW36C1M5",
  • "source_message_timestamp": "1653650280.526509",
  • "status": "triage",
  • "summary": "Our database is really really sad, and we don't know why yet.",
  • "visibility": "public"
}
Response samples
application/json
{
  • "incident": {
    }
}

Show Incidents V1Deprecated

Get a single incident.

Request
path Parameters
id
required
string

Unique identifier for the incident

Example: 01FDAG4SAP5TYPT98WGR2N7W91
Responses
200

OK response.

get/v1/incidents/{id}
Request samples
Response samples
application/json
{
  • "incident": {
    }
}

Incidents V2

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 V2

List all incidents for an organisation.

This endpoint supports a number of filters, which can help find incidents matching certain criteria.

Filters are provided as query parameters, but due to the dynamic nature of what you can query by (different accounts have different custom fields, statuses, etc) they are more complex than most.

To help, here are some exemplar curl requests with a human description of what they search for.

Note that:

  • Filters may be used together, and the result will be incidents that match all filters.
  • IDs are normally in UUID format, but have been replaced with shorter strings to improve readability.
  • All query parameters must be URI encoded.

By status

With status of id=ABC, find all incidents that are set to that status:

    curl --get 'https://api.incident.io/v2/incidents' \
        --data 'status[one_of]=ABC'

Or all incidents that are not set to status with id=ABC:

    curl --get 'https://api.incident.io/v2/incidents' \
        --data 'status[not_in]=ABC'

By severity

With severity of id=ABC, find all incidents that are set to that severity:

    curl --get 'https://api.incident.io/v2/incidents' \
        --data 'severity[one_of]=ABC'

Or all incidents where severity rank is greater-than-or-equal-to the rank of severity id=ABC:

    curl --get 'https://api.incident.io/v2/incidents' \
        --data 'severity[gte]=ABC'

Or all incidents where severity rank is less-than-or-equal-to the rank of severity id=ABC:

    curl --get 'https://api.incident.io/v2/incidents' \
        --data 'severity[lte]=ABC'

By incident type

With incident type of id=ABC, find all incidents that are of that type:

    curl --get 'https://api.incident.io/v2/incidents' \
        --data 'incident_type[one_of]=ABC'

Or all incidents not of that type:

    curl --get 'https://api.incident.io/v2/incidents' \
        --data 'incident_type[not_in]=ABC'

By incident role

Roles and custom fields have another nested layer in the query parameter, to account for operations against any of the roles or custom fields created in the account.

With incident role id=ABC, find all incidents where that role is unset:

    curl --get 'https://api.incident.io/v2/incidents' \
        --data 'incident_role[ABC][is_blank]=true'

Or where the role has been set:

    curl --get 'https://api.incident.io/v2/incidents' \
        --data 'incident_role[ABC][is_blank]=false'

By option custom fields

With an option custom field id=ABC, all incidents that have field ABC set to the custom field option of id=XYZ:

    curl \
        --get 'https://api.incident.io/v2/incidents' \
        --data 'custom_field[ABC][one_of]=XYZ'

Or all incidents that do not have custom field id=ABC set to option id=XYZ:

    curl \
        --get 'https://api.incident.io/v2/incidents' \
        --data 'custom_field[ABC][not_in]=XYZ'
Request
query Parameters
page_size
integer <int64>
Default: 25

number of records to return

Example: page_size=25
after
string

An incident's ID. This endpoint will return a list of incidents after this ID in relation to the API response order.

Example: after=01FDAG4SAP5TYPT98WGR2N7W91
object

Filter on incident status. The accepted operators are 'one_of', or 'not_in'.

Example: one_of=01GBSQF3FHF7FWZQNWGHAVQ804
object

Filter on incident severity. The accepted operators are 'one_of', 'not_in', 'gte', 'lte'.

Example: one_of=01GBSQF3FHF7FWZQNWGHAVQ804
object

Filter on incident type. The accepted operator is 'one_of'.

Example: one_of=01GBSQF3FHF7FWZQNWGHAVQ804
object

Filter on an incident role. Role ID should be sent, followed by the operator and values. The accepted operators are 'one_of', 'is_blank'.

Example: 01GBSQF3FHF7FWZQNWGHAVQ804=[object Object]
object

Filter on an incident custom field. Custom field ID should be sent, followed by the operator and values. Accepted operator will depend on the custom field type.

Example: 01GBSQF3FHF7FWZQNWGHAVQ804=[object Object]
Responses
200

OK response.

get/v2/incidents
Request samples
Response samples
application/json
{
  • "incidents": [
    ],
  • "pagination_meta": {
    }
}

Create Incidents V2

Create a new incident.

Request
Request Body schema: application/json
Array of objects (CustomFieldEntryPayloadV1)

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 (IncidentRoleAssignmentPayloadV1)

Assign incident roles to these people

incident_status_id
string

Incident status to assign to the incident

Array of objects (IncidentTimestampValuePayloadV2)

Assign the incident's timestamps to these values

incident_type_id
string

Incident type to create this incident as

mode
string

Whether the incident is real, a test, or a tutorial

Enum: "standard" "retrospective" "test" "tutorial"
name
string

Explanation of the incident

severity_id
required
string

Severity to create incident as

source_message_channel_id
string

Channel ID of the source message, if this incident was created from one

source_message_timestamp
string

Timestamp of the source message, if this incident was created from one

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/v2/incidents
Request samples
application/json
{
  • "custom_field_entries": [
    ],
  • "idempotency_key": "alert-uuid",
  • "incident_role_assignments": [
    ],
  • "incident_status_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
  • "incident_timestamp_values": [
    ],
  • "incident_type_id": "01FH5TZRWMNAFB0DZ23FD1TV96",
  • "mode": "standard",
  • "name": "Our database is sad",
  • "severity_id": "01FH5TZRWMNAFB0DZ23FD1TV96",
  • "source_message_channel_id": "C02AW36C1M5",
  • "source_message_timestamp": "1653650280.526509",
  • "summary": "Our database is really really sad, and we don't know why yet.",
  • "visibility": "public"
}
Response samples
application/json
{
  • "incident": {