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.
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>
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:
401
)authentication_error
)request_id
that can be provided to incident.io support to help
debug questions with your API requestThe 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.
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:
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.
Manage incident actions.
Incidents have two types of actions associated to them:
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 all actions for an organisation.
OK response.
{- "actions": [
- {
- "assignee": {
- "email": "lisa@incident.io",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Lisa Karlin Curtis",
- "role": "viewer",
- "slack_user_id": "U02AYNF2XJM"
}, - "completed_at": "2021-08-17T13:28:57.801578Z",
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Call the fire brigade",
- "external_issue_reference": {
- "issue_name": "INC-123",
- "provider": "asana"
}, - "follow_up": true,
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "incident_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "status": "outstanding",
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
]
}
{- "action": {
- "assignee": {
- "email": "lisa@incident.io",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Lisa Karlin Curtis",
- "role": "viewer",
- "slack_user_id": "U02AYNF2XJM"
}, - "completed_at": "2021-08-17T13:28:57.801578Z",
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Call the fire brigade",
- "external_issue_reference": {
- "issue_name": "INC-123",
- "provider": "asana"
}, - "follow_up": true,
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "incident_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "status": "outstanding",
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
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.
Show custom field options for a custom field
OK response.
{- "custom_field_options": [
- {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}
]
}
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.
Created response.
{- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}
{- "custom_field_option": {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}
}
{- "custom_field_option": {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}
}
Update a custom field option
OK response.
{- "sort_key": 10,
- "value": "Product"
}
{- "custom_field_option": {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}
}
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:
We may add more custom field types in the future - we'd love to hear any other types you'd like to use!
{- "custom_fields": [
- {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Which team is impacted by this issue",
- "field_type": "single_select",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Affected Team",
- "options": [
- {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}
], - "required": "never",
- "show_before_closure": true,
- "show_before_creation": true,
- "show_before_update": true,
- "show_in_announcement_post": true,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
]
}
Create a new custom field
Created response.
{- "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_before_update": true,
- "show_in_announcement_post": true
}
{- "custom_field": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Which team is impacted by this issue",
- "field_type": "single_select",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Affected Team",
- "options": [
- {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}
], - "required": "never",
- "show_before_closure": true,
- "show_before_creation": true,
- "show_before_update": true,
- "show_in_announcement_post": true,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
{- "custom_field": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Which team is impacted by this issue",
- "field_type": "single_select",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Affected Team",
- "options": [
- {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}
], - "required": "never",
- "show_before_closure": true,
- "show_before_creation": true,
- "show_before_update": true,
- "show_in_announcement_post": true,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
Update the details of a custom field
OK response.
{- "description": "Which team is impacted by this issue",
- "name": "Affected Team",
- "required": "never",
- "show_before_closure": true,
- "show_before_creation": true,
- "show_before_update": true,
- "show_in_announcement_post": true
}
{- "custom_field": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Which team is impacted by this issue",
- "field_type": "single_select",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Affected Team",
- "options": [
- {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}
], - "required": "never",
- "show_before_closure": true,
- "show_before_creation": true,
- "show_before_update": true,
- "show_in_announcement_post": true,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
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 all incident attachements for an external resouce
OK response.
{- "incident_attachments": [
- {
- "id": "01FCNDV6P870EA6S7TK1DSYD5H",
- "incident_id": "01FCNDV6P870EA6S7TK1DSYD5H",
- "resource": {
- "external_id": "123",
- "resource_type": "pager_duty_incident",
- "title": "The database has gone down"
}
}
]
}
Attaches an external resource to an incident
Created response.
{- "incident_id": "01FDAG4SAP5TYPT98WGR2N7W91",
- "resource": {
- "external_id": "123",
- "resource_type": "pager_duty_incident"
}
}
{- "incident_attachment": {
- "id": "01FCNDV6P870EA6S7TK1DSYD5H",
- "incident_id": "01FCNDV6P870EA6S7TK1DSYD5H",
- "resource": {
- "external_id": "123",
- "resource_type": "pager_duty_incident",
- "title": "The database has gone down"
}
}
}
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.
{- "incident_roles": [
- {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "The person currently coordinating the incident",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "instructions": "Take point on the incident; Make sure people are clear on responsibilities",
- "name": "Incident Lead",
- "required": true,
- "role_type": "lead",
- "shortform": "lead",
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
]
}
Create a new incident role
Created response.
{- "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"
}
{- "incident_role": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "The person currently coordinating the incident",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "instructions": "Take point on the incident; Make sure people are clear on responsibilities",
- "name": "Incident Lead",
- "required": true,
- "role_type": "lead",
- "shortform": "lead",
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
{- "incident_role": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "The person currently coordinating the incident",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "instructions": "Take point on the incident; Make sure people are clear on responsibilities",
- "name": "Incident Lead",
- "required": true,
- "role_type": "lead",
- "shortform": "lead",
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
Update an existing incident role
OK response.
{- "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"
}
{- "incident_role": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "The person currently coordinating the incident",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "instructions": "Take point on the incident; Make sure people are clear on responsibilities",
- "name": "Incident Lead",
- "required": true,
- "role_type": "lead",
- "shortform": "lead",
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
Manage incident statuses.
Each incident has a status, picked from one of the statuses configured in your organisations settings.
Statuses help communicate where an incident is in its lifecycle. You can use statuses when filtering incidents in the dashboard, and in workflows and announcement rules.
{- "incident_statuses": [
- {
- "category": "triage",
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Impact has been **fully mitigated**, and we're ready to learn from this incident.",
- "id": "01FCNDV6P870EA6S7TK1DSYD5H",
- "name": "Closed",
- "rank": 4,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
]
}
Create a new incident status
Created response.
{- "category": "live",
- "description": "Impact has been **fully mitigated**, and we're ready to learn from this incident.",
- "name": "Closed"
}
{- "incident_status": {
- "category": "triage",
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Impact has been **fully mitigated**, and we're ready to learn from this incident.",
- "id": "01FCNDV6P870EA6S7TK1DSYD5H",
- "name": "Closed",
- "rank": 4,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
{- "incident_status": {
- "category": "triage",
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Impact has been **fully mitigated**, and we're ready to learn from this incident.",
- "id": "01FCNDV6P870EA6S7TK1DSYD5H",
- "name": "Closed",
- "rank": 4,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
{- "description": "Impact has been **fully mitigated**, and we're ready to learn from this incident.",
- "name": "Closed"
}
{- "incident_status": {
- "category": "triage",
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Impact has been **fully mitigated**, and we're ready to learn from this incident.",
- "id": "01FCNDV6P870EA6S7TK1DSYD5H",
- "name": "Closed",
- "rank": 4,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
View incident timestamps.
Each incident has a number of timestamps; some being defaults that we set on each incident for you, and other being configured for your organisation within settings.
Timestamps help to communicate when a given action was taken for a specific incident, for example when it was reported, closed or fixed.
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.
{- "incident_types": [
- {
- "create_in_triage": "always",
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Customer facing production outages",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "is_default": false,
- "name": "Production Outage",
- "private_incidents_only": false,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
]
}
{- "incident_type": {
- "create_in_triage": "always",
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Customer facing production outages",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "is_default": false,
- "name": "Production Outage",
- "private_incidents_only": false,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
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 all incidents for an organisation.
OK response.
{- "incidents": [
- {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "creator": {
- "api_key": {
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "My test API key"
}, - "user": {
- "email": "lisa@incident.io",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Lisa Karlin Curtis",
- "role": "viewer",
- "slack_user_id": "U02AYNF2XJM"
}
}, - "custom_field_entries": [
- {
- "custom_field": {
- "description": "Which team is impacted by this issue",
- "field_type": "single_select",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Affected Team",
- "options": [
- {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}
]
}, - "values": [
- {
- "value_numeric": "123.456",
- "value_option": {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}, - "value_text": "This is my text field, I hope you like it"
}
]
}
], - "id": "01FDAG4SAP5TYPT98WGR2N7W91",
- "incident_role_assignments": [
- {
- "assignee": {
- "email": "lisa@incident.io",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Lisa Karlin Curtis",
- "role": "viewer",
- "slack_user_id": "U02AYNF2XJM"
}, - "role": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "The person currently coordinating the incident",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "instructions": "Take point on the incident; Make sure people are clear on responsibilities",
- "name": "Incident Lead",
- "required": true,
- "role_type": "lead",
- "shortform": "lead",
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
], - "incident_type": {
- "create_in_triage": "always",
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Customer facing production outages",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "is_default": false,
- "name": "Production Outage",
- "private_incidents_only": false,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}, - "mode": "real",
- "name": "Our database is sad",
- "reference": "INC-123",
- "severity": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Issues with **low impact**.",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Minor",
- "rank": 1,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}, - "slack_channel_id": "C02AW36C1M5",
- "slack_channel_name": "inc-165-green-parrot",
- "status": "triage",
- "summary": "Our database is really really sad, and we don't know why yet.",
- "timestamps": [
- {
- "last_occurred_at": "2021-08-17T13:28:57.801578Z",
- "name": "last_activity"
}
], - "updated_at": "2021-08-17T13:28:57.801578Z",
- "visibility": "public"
}
], - "pagination_meta": {
- "after": "01FCNDV6P870EA6S7TK1DSYDG0",
- "page_size": 25,
- "total_record_count": 238
}
}
Create a new incident.
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 |
name | string Explanation of the incident |
severity_id | 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 |
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. |
OK response.
{- "custom_field_entries": [
- {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "values": [
- {
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "value_numeric": "123.456",
- "value_option_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "value_text": "This is my text field, I hope you like it",
- "value_timestamp": ""
}
]
}
], - "idempotency_key": "alert-uuid",
- "incident_role_assignments": [
- {
- "assignee": {
- "email": "bob@example.com",
- "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
- "slack_user_id": "USER123"
}, - "incident_role_id": "01FH5TZRWMNAFB0DZ23FD1TV96"
}
], - "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"
}
{- "incident": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "creator": {
- "api_key": {
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "My test API key"
}, - "user": {
- "email": "lisa@incident.io",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Lisa Karlin Curtis",
- "role": "viewer",
- "slack_user_id": "U02AYNF2XJM"
}
}, - "custom_field_entries": [
- {
- "custom_field": {
- "description": "Which team is impacted by this issue",
- "field_type": "single_select",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Affected Team",
- "options": [
- {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}
]
}, - "values": [
- {
- "value_numeric": "123.456",
- "value_option": {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}, - "value_text": "This is my text field, I hope you like it"
}
]
}
], - "id": "01FDAG4SAP5TYPT98WGR2N7W91",
- "incident_role_assignments": [
- {
- "assignee": {
- "email": "lisa@incident.io",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Lisa Karlin Curtis",
- "role": "viewer",
- "slack_user_id": "U02AYNF2XJM"
}, - "role": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "The person currently coordinating the incident",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "instructions": "Take point on the incident; Make sure people are clear on responsibilities",
- "name": "Incident Lead",
- "required": true,
- "role_type": "lead",
- "shortform": "lead",
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
], - "incident_type": {
- "create_in_triage": "always",
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Customer facing production outages",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "is_default": false,
- "name": "Production Outage",
- "private_incidents_only": false,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}, - "mode": "real",
- "name": "Our database is sad",
- "reference": "INC-123",
- "severity": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Issues with **low impact**.",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Minor",
- "rank": 1,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}, - "slack_channel_id": "C02AW36C1M5",
- "slack_channel_name": "inc-165-green-parrot",
- "status": "triage",
- "summary": "Our database is really really sad, and we don't know why yet.",
- "timestamps": [
- {
- "last_occurred_at": "2021-08-17T13:28:57.801578Z",
- "name": "last_activity"
}
], - "updated_at": "2021-08-17T13:28:57.801578Z",
- "visibility": "public"
}
}
{- "incident": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "creator": {
- "api_key": {
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "My test API key"
}, - "user": {
- "email": "lisa@incident.io",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Lisa Karlin Curtis",
- "role": "viewer",
- "slack_user_id": "U02AYNF2XJM"
}
}, - "custom_field_entries": [
- {
- "custom_field": {
- "description": "Which team is impacted by this issue",
- "field_type": "single_select",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Affected Team",
- "options": [
- {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}
]
}, - "values": [
- {
- "value_numeric": "123.456",
- "value_option": {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}, - "value_text": "This is my text field, I hope you like it"
}
]
}
], - "id": "01FDAG4SAP5TYPT98WGR2N7W91",
- "incident_role_assignments": [
- {
- "assignee": {
- "email": "lisa@incident.io",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Lisa Karlin Curtis",
- "role": "viewer",
- "slack_user_id": "U02AYNF2XJM"
}, - "role": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "The person currently coordinating the incident",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "instructions": "Take point on the incident; Make sure people are clear on responsibilities",
- "name": "Incident Lead",
- "required": true,
- "role_type": "lead",
- "shortform": "lead",
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
], - "incident_type": {
- "create_in_triage": "always",
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Customer facing production outages",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "is_default": false,
- "name": "Production Outage",
- "private_incidents_only": false,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}, - "mode": "real",
- "name": "Our database is sad",
- "reference": "INC-123",
- "severity": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Issues with **low impact**.",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Minor",
- "rank": 1,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}, - "slack_channel_id": "C02AW36C1M5",
- "slack_channel_name": "inc-165-green-parrot",
- "status": "triage",
- "summary": "Our database is really really sad, and we don't know why yet.",
- "timestamps": [
- {
- "last_occurred_at": "2021-08-17T13:28:57.801578Z",
- "name": "last_activity"
}
], - "updated_at": "2021-08-17T13:28:57.801578Z",
- "visibility": "public"
}
}
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 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:
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'
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'
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'
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'
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'
OK response.
{- "incidents": [
- {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "creator": {
- "api_key": {
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "My test API key"
}, - "user": {
- "email": "lisa@incident.io",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Lisa Karlin Curtis",
- "role": "viewer",
- "slack_user_id": "U02AYNF2XJM"
}
}, - "custom_field_entries": [
- {
- "custom_field": {
- "description": "Which team is impacted by this issue",
- "field_type": "single_select",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Affected Team",
- "options": [
- {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}
]
}, - "values": [
- {
- "value_numeric": "123.456",
- "value_option": {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}, - "value_text": "This is my text field, I hope you like it"
}
]
}
], - "external_issue_reference": {
- "issue_name": "INC-123",
- "provider": "asana"
}, - "id": "01FDAG4SAP5TYPT98WGR2N7W91",
- "incident_role_assignments": [
- {
- "assignee": {
- "email": "lisa@incident.io",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Lisa Karlin Curtis",
- "role": "viewer",
- "slack_user_id": "U02AYNF2XJM"
}, - "role": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "The person currently coordinating the incident",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "instructions": "Take point on the incident; Make sure people are clear on responsibilities",
- "name": "Incident Lead",
- "required": true,
- "role_type": "lead",
- "shortform": "lead",
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
], - "incident_status": {
- "category": "triage",
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Impact has been **fully mitigated**, and we're ready to learn from this incident.",
- "id": "01FCNDV6P870EA6S7TK1DSYD5H",
- "name": "Closed",
- "rank": 4,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}, - "incident_timestamp_values": [
- {
- "incident_timestamp": {
- "id": "01FCNDV6P870EA6S7TK1DSYD5H",
- "name": "Impact started",
- "rank": 1
}, - "value": {
- "value": "2021-08-17T13:28:57.801578Z"
}
}
], - "incident_type": {
- "create_in_triage": "always",
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Customer facing production outages",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "is_default": false,
- "name": "Production Outage",
- "private_incidents_only": false,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}, - "mode": "standard",
- "name": "Our database is sad",
- "reference": "INC-123",
- "severity": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Issues with **low impact**.",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Minor",
- "rank": 1,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}, - "slack_channel_id": "C02AW36C1M5",
- "slack_channel_name": "inc-165-green-parrot",
- "summary": "Our database is really really sad, and we don't know why yet.",
- "updated_at": "2021-08-17T13:28:57.801578Z",
- "visibility": "public"
}
], - "pagination_meta": {
- "after": "01FCNDV6P870EA6S7TK1DSYDG0",
- "page_size": 25,
- "total_record_count": 238
}
}
Create a new incident.
Note that if the incident mode is set to "retrospective" then the new incident will not be announced in Slack.
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 (IncidentRoleAssignmentPayloadV2) 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, a tutorial, or importing as a retrospective incident |
name | string Explanation of the incident |
object (RetrospectiveIncidentOptionsV2) | |
severity_id | string Severity to create incident as |
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. |
OK response.
{- "custom_field_entries": [
- {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "values": [
- {
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "value_numeric": "123.456",
- "value_option_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "value_text": "This is my text field, I hope you like it",
- "value_timestamp": ""
}
]
}
], - "idempotency_key": "alert-uuid",
- "incident_role_assignments": [
- {
- "assignee": {
- "email": "bob@example.com",
- "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
- "slack_user_id": "USER123"
}, - "incident_role_id": "01FH5TZRWMNAFB0DZ23FD1TV96"
}
], - "incident_status_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
- "incident_timestamp_values": [
- {
- "incident_timestamp_id": "01FCNDV6P870EA6S7TK1DSYD5H",
- "value": "2021-08-17T13:28:57.801578Z"
}
], - "incident_type_id": "01FH5TZRWMNAFB0DZ23FD1TV96",
- "mode": "standard",
- "name": "Our database is sad",
- "retrospective_incident_options": {
- "slack_channel_id": "abc123"
}, - "severity_id": "01FH5TZRWMNAFB0DZ23FD1TV96",
- "summary": "Our database is really really sad, and we don't know why yet.",
- "visibility": "public"
}
{- "incident": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "creator": {
- "api_key": {
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "My test API key"
}, - "user": {
- "email": "lisa@incident.io",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Lisa Karlin Curtis",
- "role": "viewer",
- "slack_user_id": "U02AYNF2XJM"
}
}, - "custom_field_entries": [
- {
- "custom_field": {
- "description": "Which team is impacted by this issue",
- "field_type": "single_select",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Affected Team",
- "options": [
- {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}
]
}, - "values": [
- {
- "value_numeric": "123.456",
- "value_option": {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}, - "value_text": "This is my text field, I hope you like it"
}
]
}
], - "external_issue_reference": {
- "issue_name": "INC-123",
- "provider": "asana"
}, - "id": "01FDAG4SAP5TYPT98WGR2N7W91",
- "incident_role_assignments": [
- {
- "assignee": {
- "email": "lisa@incident.io",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Lisa Karlin Curtis",
- "role": "viewer",
- "slack_user_id": "U02AYNF2XJM"
}, - "role": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "The person currently coordinating the incident",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "instructions": "Take point on the incident; Make sure people are clear on responsibilities",
- "name": "Incident Lead",
- "required": true,
- "role_type": "lead",
- "shortform": "lead",
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
], - "incident_status": {
- "category": "triage",
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Impact has been **fully mitigated**, and we're ready to learn from this incident.",
- "id": "01FCNDV6P870EA6S7TK1DSYD5H",
- "name": "Closed",
- "rank": 4,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}, - "incident_timestamp_values": [
- {
- "incident_timestamp": {
- "id": "01FCNDV6P870EA6S7TK1DSYD5H",
- "name": "Impact started",
- "rank": 1
}, - "value": {
- "value": "2021-08-17T13:28:57.801578Z"
}
}
], - "incident_type": {
- "create_in_triage": "always",
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Customer facing production outages",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "is_default": false,
- "name": "Production Outage",
- "private_incidents_only": false,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}, - "mode": "standard",
- "name": "Our database is sad",
- "reference": "INC-123",
- "severity": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Issues with **low impact**.",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Minor",
- "rank": 1,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}, - "slack_channel_id": "C02AW36C1M5",
- "slack_channel_name": "inc-165-green-parrot",
- "summary": "Our database is really really sad, and we don't know why yet.",
- "updated_at": "2021-08-17T13:28:57.801578Z",
- "visibility": "public"
}
}
{- "incident": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "creator": {
- "api_key": {
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "My test API key"
}, - "user": {
- "email": "lisa@incident.io",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Lisa Karlin Curtis",
- "role": "viewer",
- "slack_user_id": "U02AYNF2XJM"
}
}, - "custom_field_entries": [
- {
- "custom_field": {
- "description": "Which team is impacted by this issue",
- "field_type": "single_select",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Affected Team",
- "options": [
- {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}
]
}, - "values": [
- {
- "value_numeric": "123.456",
- "value_option": {
- "custom_field_id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "sort_key": 10,
- "value": "Product"
}, - "value_text": "This is my text field, I hope you like it"
}
]
}
], - "external_issue_reference": {
- "issue_name": "INC-123",
- "provider": "asana"
}, - "id": "01FDAG4SAP5TYPT98WGR2N7W91",
- "incident_role_assignments": [
- {
- "assignee": {
- "email": "lisa@incident.io",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Lisa Karlin Curtis",
- "role": "viewer",
- "slack_user_id": "U02AYNF2XJM"
}, - "role": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "The person currently coordinating the incident",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "instructions": "Take point on the incident; Make sure people are clear on responsibilities",
- "name": "Incident Lead",
- "required": true,
- "role_type": "lead",
- "shortform": "lead",
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
], - "incident_status": {
- "category": "triage",
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Impact has been **fully mitigated**, and we're ready to learn from this incident.",
- "id": "01FCNDV6P870EA6S7TK1DSYD5H",
- "name": "Closed",
- "rank": 4,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}, - "incident_timestamp_values": [
- {
- "incident_timestamp": {
- "id": "01FCNDV6P870EA6S7TK1DSYD5H",
- "name": "Impact started",
- "rank": 1
}, - "value": {
- "value": "2021-08-17T13:28:57.801578Z"
}
}
], - "incident_type": {
- "create_in_triage": "always",
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Customer facing production outages",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "is_default": false,
- "name": "Production Outage",
- "private_incidents_only": false,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}, - "mode": "standard",
- "name": "Our database is sad",
- "reference": "INC-123",
- "severity": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Issues with **low impact**.",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Minor",
- "rank": 1,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}, - "slack_channel_id": "C02AW36C1M5",
- "slack_channel_name": "inc-165-green-parrot",
- "summary": "Our database is really really sad, and we don't know why yet.",
- "updated_at": "2021-08-17T13:28:57.801578Z",
- "visibility": "public"
}
}
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.
{- "severities": [
- {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Issues with **low impact**.",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Minor",
- "rank": 1,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
]
}
{- "description": "Issues with **low impact**.",
- "name": "Minor",
- "rank": 1
}
{- "severity": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Issues with **low impact**.",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Minor",
- "rank": 1,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
{- "severity": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Issues with **low impact**.",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Minor",
- "rank": 1,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
Update an existing severity
OK response.
{- "description": "Issues with **low impact**.",
- "name": "Minor",
- "rank": 1
}
{- "severity": {
- "created_at": "2021-08-17T13:28:57.801578Z",
- "description": "Issues with **low impact**.",
- "id": "01FCNDV6P870EA6S7TK1DSYDG0",
- "name": "Minor",
- "rank": 1,
- "updated_at": "2021-08-17T13:28:57.801578Z"
}
}
Miscelaneous utility endpoints.
Collection of utility functions that can help build integrations against this API.