Incidents

API endpoints for 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": "[e-mail]",
    "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": ["[e-mail]", "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 · 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": "[e-mail]",
      "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"
}

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"

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"

duration_metrics · object[]

Incident duration metrics and their measurements for this incident

Show child attributes

Example:

[
  {
    "duration_metric": {
      "id": "01FCNDV6P870EA6S7TK1DSYD5H",
      "name": "Lasted"
    },
    "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"
}

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"

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