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.

The incident object

created_at

string<date-time>

required

When the incident was created

Example:

"2021-08-17T13:28:57.801578Z"

creator

object

required

Show child attributes

Example:

{
  "alert": {
    "id": "01GW2G3V0S59R238FAHPDS1R66",
    "title": "*errors.withMessage: PG::Error failed to connect"
  },
  "api_key": {
    "id": "01FCNDV6P870EA6S7TK1DSYDG0",
    "name": "My test API key"
  },
  "user": {
    "email": "lisa@incident.io",
    "id": "01FCNDV6P870EA6S7TK1DSYDG0",
    "name": "Lisa Karlin Curtis",
    "role": "owner",
    "slack_user_id": "U02AYNF2XJM"
  },
  "workflow": {
    "id": "01FCNDV6P870EA6S7TK1DSYDG0",
    "name": "My little workflow"
  }
}

custom_field_entries

object[]

required

Custom field entries for this incident

Show child attributes

Example:

[
  {
    "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_catalog_entry": {
          "aliases": ["lawrence@incident.io", "lawrence"],
          "external_id": "761722cd-d1d7-477b-ac7e-90f9e079dc33",
          "id": "01FCNDV6P870EA6S7TK1DSYDG0",
          "name": "Primary On-call"
        },
        "value_link": "https://google.com/",
        "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"
      }
    ]
  }
]

string

required

Unique identifier for the incident

Example:

"01FDAG4SAP5TYPT98WGR2N7W91"

incident_role_assignments

object[]

required

A list of who is assigned to each role for this incident

Show child attributes

Example:

[
  {
    "assignee": {
      "email": "lisa@incident.io",
      "id": "01FCNDV6P870EA6S7TK1DSYDG0",
      "name": "Lisa Karlin Curtis",
      "role": "owner",
      "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": false,
      "role_type": "lead",
      "shortform": "lead",
      "updated_at": "2021-08-17T13:28:57.801578Z"
    }
  }
]

incident_status

object

required

Show child attributes

Example:

{
  "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"
}

last_activity_at

string<date-time>

required

When the incident last recorded 'activity'

Example:

"2021-08-17T13:28:57.801578Z"

mode

enum<string>

required

Whether the incident is real, a test, a tutorial, or importing as a retrospective incident

Available options:

standard,

retrospective,

test,

tutorial

Example:

"standard"

name

string

required

Explanation of the incident

Example:

"Our database is sad"

reference

string

required

Reference to this incident, as displayed across the product

Example:

"INC-123"

slack_channel_id

string

required

ID of the Slack channel in the organisation Slack workspace. Note that the channel is sometimes created asynchronously, so may not be present when the incident is just created.

Example:

"C02AW36C1M5"

slack_team_id

string

required

ID of the Slack team / workspace. This is only required if you are using a Slack Enterprise Grid with multiple teams.

Example:

"T02A1FSLE8J"

team_ids

string[]

required

IDs of the teams that own this incident, resolved from your team settings. Empty when no teams match.

Example:

["01JPQA75EPNEES4479P16P4XAB"]

updated_at

string<date-time>

required

When the incident was last updated

Example:

"2021-08-17T13:28:57.801578Z"

visibility

enum<string>

required

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

Available options:

public,

private

Example:

"public"

call_url

string

The call URL attached to this incident

Example:

"https://zoom.us/foo"

debriefs

object[]

Debriefs scheduled for this incident, ordered by start time. Excludes cancelled calendar events.

Show child attributes

Example:

[
  {
    "end_at": "2021-08-17T14:28:57.801578Z",
    "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
    "start_at": "2021-08-17T13:28:57.801578Z"
  }
]

duration_metrics

object[]

Incident duration metrics and their measurements for this incident

Show child attributes

Example:

[
  {
    "duration_metric": {
      "id": "01FCNDV6P870EA6S7TK1DSYD5H",
      "name": "Lasted"
    },
    "status": "success",
    "value_seconds": 10800
  }
]

external_issue_reference

object

Show child attributes

Example:

{
  "issue_name": "INC-123",
  "issue_permalink": "https://linear.app/incident-io/issue/INC-1609/find-copywriter-to-write-up",
  "provider": "asana"
}

has_debrief

boolean

If this incident has a debrief attached

Example:

false

incident_timestamp_values

object[]

Incident lifecycle events and when they occurred

Show child attributes

Example:

[
  {
    "incident_timestamp": {
      "id": "01FCNDV6P870EA6S7TK1DSYD5H",
      "name": "Impact started",
      "rank": 1
    },
    "value": { "value": "2021-08-17T13:28:57.801578Z" }
  }
]

incident_type

object

Show child attributes

Example:

{
  "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"
}

ms_teams_channel_url

string

URL to link to the Microsoft Teams channel

Example:

"https://teams.microsoft.com/l/channel/19%some-hex%40thread.tacv2/inc-123-title?groupId=some-uuid&tenantId=another-uuid"

permalink

string

A permanent link to the homepage for this incident

Example:

"https://app.incident.io/incidents/123"

postmortem_document_ids

string[]

An array of IDs of postmortem documents for this incident

Example:

["01FCNDV6P870EA6S7TK1DSYD5H"]

postmortem_document_url

string

The URL of the incident post-mortem document

Example:

"https://docs.google.com/my_doc_id"

severity

object

Show child attributes

Example:

{
  "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_name

string

Name of the slack channel

Example:

"inc-165-green-parrot"

slack_channel_url

string

URL to link to the slack channel

Example:

"https://slack.com/app_redirect?team=T1234&channel=C5678"

summary

string

Detailed description of the incident

Example:

"Our database is really really sad, and we don't know why yet."

workload_minutes_late

number<double>

Amount of time spent on the incident in late hours

Example:

40.7

workload_minutes_sleeping

number<double>

Amount of time spent on the incident in sleeping hours

Example:

0

workload_minutes_total

number<double>

Amount of time spent on the incident in total

Example:

60.7

workload_minutes_working

number<double>

Amount of time spent on the incident in working hours

Example:

20

{
  "created_at": "2021-08-17T13:28:57.801578Z",
  "creator": {
    "alert": {
      "id": "01GW2G3V0S59R238FAHPDS1R66",
      "title": "*errors.withMessage: PG::Error failed to connect"
    },
    "api_key": {
      "id": "01FCNDV6P870EA6S7TK1DSYDG0",
      "name": "My test API key"
    },
    "user": {
      "email": "lisa@incident.io",
      "id": "01FCNDV6P870EA6S7TK1DSYDG0",
      "name": "Lisa Karlin Curtis",
      "role": "owner",
      "slack_user_id": "U02AYNF2XJM"
    },
    "workflow": {
      "id": "01FCNDV6P870EA6S7TK1DSYDG0",
      "name": "My little workflow"
    }
  },
  "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_catalog_entry": {
            "aliases": [
              "lawrence@incident.io",
              "lawrence"
            ],
            "external_id": "761722cd-d1d7-477b-ac7e-90f9e079dc33",
            "id": "01FCNDV6P870EA6S7TK1DSYDG0",
            "name": "Primary On-call"
          },
          "value_link": "https://google.com/",
          "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": "owner",
        "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": false,
        "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"
  },
  "last_activity_at": "2021-08-17T13:28:57.801578Z",
  "mode": "standard",
  "name": "Our database is sad",
  "reference": "INC-123",
  "slack_channel_id": "C02AW36C1M5",
  "slack_team_id": "T02A1FSLE8J",
  "team_ids": [
    "01JPQA75EPNEES4479P16P4XAB"
  ],
  "updated_at": "2021-08-17T13:28:57.801578Z",
  "visibility": "public",
  "call_url": "https://zoom.us/foo",
  "debriefs": [
    {
      "end_at": "2021-08-17T14:28:57.801578Z",
      "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
      "start_at": "2021-08-17T13:28:57.801578Z"
    }
  ],
  "duration_metrics": [
    {
      "duration_metric": {
        "id": "01FCNDV6P870EA6S7TK1DSYD5H",
        "name": "Lasted"
      },
      "status": "success",
      "value_seconds": 10800
    }
  ],
  "external_issue_reference": {
    "issue_name": "INC-123",
    "issue_permalink": "https://linear.app/incident-io/issue/INC-1609/find-copywriter-to-write-up",
    "provider": "asana"
  },
  "has_debrief": false,
  "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"
  },
  "ms_teams_channel_url": "https://teams.microsoft.com/l/channel/19%some-hex%40thread.tacv2/inc-123-title?groupId=some-uuid&tenantId=another-uuid",
  "permalink": "https://app.incident.io/incidents/123",
  "postmortem_document_ids": [
    "01FCNDV6P870EA6S7TK1DSYD5H"
  ],
  "postmortem_document_url": "https://docs.google.com/my_doc_id",
  "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_name": "inc-165-green-parrot",
  "slack_channel_url": "https://slack.com/app_redirect?team=T1234&channel=C5678",
  "summary": "Our database is really really sad, and we don't know why yet.",
  "workload_minutes_late": 40.7,
  "workload_minutes_sleeping": 0,
  "workload_minutes_total": 60.7,
  "workload_minutes_working": 20
}

Getting started

Webhooks

Audit logs

Deprecated endpoints

The incident object

​The incident object

The incident object