Incident.io
Setup Instructions
1. Create API Key
Go to https://app.incident.io/settings/api-keys and create an API key with the following permissions:
- “View data, like public incidents and organisation settings”
- “Create incidents”
- “Edit incidents”
- “View all incident data, including private incidents”
Copy the generated API key.
2. Configure Connection
Go to https://ui.{deployment}.firetigerapi.com/settings/connections and create a new HTTP connection with:
Base URL:
https://api.incident.io
Allowed Routes:
GET /v2/incidents
POST /v2/incidents
GET /v2/incidents/{id}
POST /v2/incidents/{id}/actions/edit
GET /v1/severities
GET /v1/severities/{id}
GET /v1/incident_statuses
GET /v1/incident_statuses/{id}
Headers:
Authorization: Bearer <your-api-key>
Content-Type: application/json
Replace <your-api-key> with the API key you copied from step 1.
3. Add Description
In the Description field, paste the content from the markdown block below:
The incident.io Incidents API v2 provides endpoints to create, read, list, and edit incidents. Incidents are a core resource in incident.io, on which many other resources (actions, etc.) are created.
## Available Operations
### 1. List Incidents
**Purpose:** Retrieve a paginated list of all incidents for an organization with advanced filtering capabilities.
**Query Parameters:**
- `page_size` (integer, optional): Number of records to return (default: 25, max: 500)
- `after` (string, optional): Incident ID for pagination - returns incidents after this ID
- `status` (object, optional): Filter by incident status ID
- Operators: `one_of`, `not_in`
- Example: `status[one_of]=01GBSQF3FHF7FWZQNWGHAVQ804`
- `status_category` (object, optional): Filter by status category
- Operators: `one_of`, `not_in`
- Values: `triage`, `declined`, `merged`, `canceled`, `live`, `learning`, `closed`
- Example: `status_category[one_of]=live`
- `created_at` (object, optional): Filter by creation timestamp
- Operators: `gte` (greater than or equal), `lte` (less than or equal), `date_range`
- Format: ISO date (YYYY-MM-DD)
- Example: `created_at[gte]=2024-05-01`
- Date range example: `created_at[date_range]=2024-12-02~2024-12-08`
- `updated_at` (object, optional): Filter by last update timestamp
- Operators: `gte`, `lte`, `date_range`
- Format: ISO date (YYYY-MM-DD)
- Example: `updated_at[lte]=2024-12-31`
- `severity` (object, optional): Filter by severity ID or rank
- Operators: `one_of`, `not_in`, `gte`, `lte`
- Example: `severity[gte]=01GBSQF3FHF7FWZQNWGHAVQ804`
- `incident_type` (object, optional): Filter by incident type ID
- Operators: `one_of`, `not_in`
- Example: `incident_type[one_of]=01GBSQF3FHF7FWZQNWGHAVQ804`
- `incident_role` (object, optional): Filter by incident role assignment status
- Operators: `one_of`, `is_blank`
- Format: `incident_role[ROLE_ID][operator]=value`
- Example: `incident_role[01GBSQF3FHF7FWZQNWGHAVQ804][is_set]=true`
- `custom_field` (object, optional): Filter by custom field values
- Operators vary by field type
- Format: `custom_field[FIELD_ID][operator]=value`
- Example: `custom_field[01GBSQF3FHF7FWZQNWGHAVQ804][one_of]=XYZ`
- `mode` (object, optional): Filter by incident mode
- Operator: `one_of`
- Values: `standard`, `retrospective`, `test`, `tutorial`
- Default: `{"one_of": ["standard", "retrospective"]}` (excludes test and tutorial)
- Example: `mode[one_of]=retrospective`
**Important Notes:**
- All query parameters must be URI encoded
- Multiple filters can be combined (incidents must match ALL filters)
- Maximum page size is 250
- By default, test and tutorial incidents are excluded unless explicitly requested via `mode` filter
**Response:**
```json
{
"incidents": [
{
"id": "01FDAG4SAP5TYPT98WGR2N7W91",
"reference": "INC-123",
"name": "Our database is sad",
"summary": "Our database is really really sad, and we don't know why yet.",
"status": {...},
"severity": {...},
"incident_type": {...},
"mode": "standard",
"visibility": "public",
"created_at": "2021-08-17T13:28:57.801578Z",
"updated_at": "2021-08-17T13:28:57.801578Z",
"slack_channel_id": "C02AW36C1M5",
"slack_channel_name": "inc-165-green-parrot",
"permalink": "https://app.incident.io/incidents/123"
}
],
"pagination_meta": {
"after": "01FCNDV6P870EA6S7TK1DSYDG0",
"page_size": 25,
"total_record_count": 238
}
}
```
**Example Request:**
```json
{
"method": "GET",
"path": "/v2/incidents",
"query_params": {
"status_category[one_of]": "live",
"page_size": "25"
}
}
```
---
### 2. Create Incident
**Purpose:** Create a new incident. When mode is set to "retrospective", the incident will not be announced in Slack.
**Request Body Fields:**
Required fields:
- `idempotency_key` (string, required): Unique string to prevent duplicate incident creation
- `visibility` (string, required): Incident visibility - `public` (open to all in Slack workspace) or `private` (invite-only)
Optional fields:
- `name` (string): Short explanation/title of the incident
- `summary` (string): Detailed description of the incident
- `severity_id` (string): ID of the severity level to assign
- `incident_type_id` (string): ID of the incident type
- `incident_status_id` (string): ID of the status to assign
- `mode` (string): Incident mode - `standard`, `retrospective`, `test`, or `tutorial`
- `slack_team_id` (string): Slack Team ID to create the incident in
- `slack_channel_name_override` (string): Custom name for the Slack channel
- `custom_field_entries` (array): Array of custom field values
- Each entry contains:
- `custom_field_id` (string): ID of the custom field
- `values` (array): Array of value objects with appropriate value type fields
- `incident_role_assignments` (array): Array of role assignments
- Each assignment contains:
- `incident_role_id` (string): ID of the role
- `assignee` (object): Can specify by `id`, `email`, or `slack_user_id`
- `incident_timestamp_values` (array): Array of timestamp values
- Each value contains:
- `incident_timestamp_id` (string): ID of the timestamp field
- `value` (string): ISO 8601 timestamp
- `retrospective_incident_options` (object): Options for retrospective incidents
- `slack_channel_id` (string): Existing Slack channel ID
- `postmortem_document_url` (string): URL to postmortem document
- `external_id` (integer): External reference ID
**Response:**
```json
{
"incident": {
"id": "01FDAG4SAP5TYPT98WGR2N7W91",
"reference": "INC-123",
"name": "Our database is sad",
"summary": "Our database is really really sad, and we don't know why yet.",
"mode": "standard",
"visibility": "public",
"created_at": "2021-08-17T13:28:57.801578Z",
"updated_at": "2021-08-17T13:28:57.801578Z",
"permalink": "https://app.incident.io/incidents/123",
...
}
}
```
**Example Request:**
```json
{
"method": "POST",
"path": "/v2/incidents",
"body": "{\"idempotency_key\": \"alert-uuid-12345\", \"name\": \"Database connection pool exhausted\", \"summary\": \"Production database connection pool has reached capacity\", \"severity_id\": \"01FH5TZRWMNAFB0DZ23FD1TV96\", \"incident_type_id\": \"01FH5TZRWMNAFB0DZ23FD1TV96\", \"mode\": \"standard\", \"visibility\": \"public\"}"
}
```
---
### 3. Get Incident (Show)
**Purpose:** Retrieve a single incident by its ID or reference number.
**Path Parameters:**
- `id` (string, required): The incident's full ID (e.g., `01FDAG4SAP5TYPT98WGR2N7W91`) OR the numeric part of its reference (e.g., `123` for incident `INC-123`)
**Response:**
```json
{
"incident": {
"id": "01FDAG4SAP5TYPT98WGR2N7W91",
"reference": "INC-123",
"name": "Our database is sad",
"summary": "Our database is really really sad, and we don't know why yet.",
"call_url": "https://zoom.us/foo",
"created_at": "2021-08-17T13:28:57.801578Z",
"updated_at": "2021-08-17T13:28:57.801578Z",
"creator": {...},
"custom_field_entries": [...],
"incident_role_assignments": [...],
"incident_status": {...},
"incident_timestamp_values": [...],
"incident_type": {...},
"severity": {...},
"mode": "standard",
"visibility": "public",
"slack_channel_id": "C02AW36C1M5",
"slack_channel_name": "inc-165-green-parrot",
"slack_team_id": "T02A1FSLE8J",
"permalink": "https://app.incident.io/incidents/123",
"postmortem_document_url": "https://docs.google.com/my_doc_id",
"has_debrief": false,
"workload_minutes_total": 60.7,
"workload_minutes_working": 20,
"workload_minutes_sleeping": 0,
"workload_minutes_late": 40.7
}
}
```
**Example Requests:**
```json
{
"method": "GET",
"path": "/v2/incidents/01FDAG4SAP5TYPT98WGR2N7W91"
}
```
```json
{
"method": "GET",
"path": "/v2/incidents/123"
}
```
---
### 4. Edit Incident
**Purpose:** Edit properties of an existing incident such as severity, status, custom fields, role assignments, etc. Only provided fields will be updated (omitted fields are ignored).
**Path Parameters:**
- `id` (string, required): The unique identifier of the incident to edit
**Request Body Fields:**
Required fields:
- `incident` (object, required): Object containing fields to update
- `notify_incident_channel` (boolean, required): Whether to send Slack notifications about the update (won't work if channel is archived)
The `incident` object can contain any of these optional fields:
- `name` (string): Updated incident name
- `summary` (string): Updated incident summary
- `severity_id` (string): New severity ID
- `incident_status_id` (string): New status ID
- `call_url` (string): Video call URL for the incident
- `slack_channel_name_override` (string): Override Slack channel name
- `custom_field_entries` (array): Update custom field values (same structure as create)
- `incident_role_assignments` (array): Update role assignments (same structure as create)
- `incident_timestamp_values` (array): Update timestamp values (same structure as create)
**Response:**
```json
{
"incident": {
"id": "01FDAG4SAP5TYPT98WGR2N7W91",
"reference": "INC-123",
"name": "Our database is sad",
"summary": "Our database is really really sad, and we don't know why yet.",
...
}
}
```
**Example Request:**
```json
{
"method": "POST",
"path": "/v2/incidents/01FDAG4SAP5TYPT98WGR2N7W91/actions/edit",
"body": "{\"incident\": {\"severity_id\": \"01G0J1EXE7AXZ2C93K61WBPYEH\", \"summary\": \"Database connection pool exhausted - identified root cause in connection timeout config\"}, \"notify_incident_channel\": true}"
}
```
---
### 5. List Severities
**Purpose:** Retrieve all incident severities configured for the organization. Severities are required when creating incidents and help categorize incidents by urgency/impact.
**Response:**
```json
{
"severities": [
{
"id": "01FCNDV6P870EA6S7TK1DSYDG0",
"name": "Minor",
"description": "Issues with **low impact**.",
"rank": 1,
"created_at": "2021-08-17T13:28:57.801578Z",
"updated_at": "2021-08-17T13:28:57.801578Z"
}
]
}
```
**Example Request:**
```json
{
"method": "GET",
"path": "/v1/severities"
}
```
---
### 6. Get Severity
**Purpose:** Retrieve a single severity by its ID.
**Path Parameters:**
- `id` (string, required): Unique identifier of the severity
**Response:**
```json
{
"severity": {
"id": "01FCNDV6P870EA6S7TK1DSYDG0",
"name": "Minor",
"description": "Issues with **low impact**.",
"rank": 1,
"created_at": "2021-08-17T13:28:57.801578Z",
"updated_at": "2021-08-17T13:28:57.801578Z"
}
}
```
**Example Request:**
```json
{
"method": "GET",
"path": "/v1/severities/01FCNDV6P870EA6S7TK1DSYDG0"
}
```
---
### 7. List Incident Statuses
**Purpose:** Retrieve all incident statuses configured for the organization. Statuses are required when creating or editing incidents and help communicate where an incident is in its lifecycle.
**Response:**
```json
{
"incident_statuses": [
{
"id": "01FCNDV6P870EA6S7TK1DSYD5H",
"name": "Closed",
"description": "Impact has been **fully mitigated**, and we're ready to learn from this incident.",
"category": "triage",
"rank": 4,
"created_at": "2021-08-17T13:28:57.801578Z",
"updated_at": "2021-08-17T13:28:57.801578Z"
}
]
}
```
**Important Notes:**
- Status categories include: `triage`, `declined`, `merged`, `canceled`, `live`, `learning`, `closed`
- Lower rank numbers appear first in lists
- The `triage` and `declined` statuses are special and cannot be modified
**Example Request:**
```json
{
"method": "GET",
"path": "/v1/incident_statuses"
}
```
---
### 8. Get Incident Status
**Purpose:** Retrieve a single incident status by its ID.
**Path Parameters:**
- `id` (string, required): Unique identifier of the incident status
**Response:**
```json
{
"incident_status": {
"id": "01FCNDV6P870EA6S7TK1DSYD5H",
"name": "Closed",
"description": "Impact has been **fully mitigated**, and we're ready to learn from this incident.",
"category": "triage",
"rank": 4,
"created_at": "2021-08-17T13:28:57.801578Z",
"updated_at": "2021-08-17T13:28:57.801578Z"
}
}
```
**Example Request:**
```json
{
"method": "GET",
"path": "/v1/incident_statuses/01FCNDV6P870EA6S7TK1DSYD5H"
}
```
---
## Best Practices
1. **Idempotency:** Always use unique `idempotency_key` values when creating incidents to prevent duplicates
2. **Avoid Automation Spam:** Be careful with automated incident creation - duplicate incidents can be distracting and impact reporting
3. **Pagination:** When listing incidents, use the `after` parameter with the last incident ID from `pagination_meta` to fetch the next page
4. **Filtering:** Combine multiple filters to narrow down incidents efficiently
5. **Partial Updates:** When editing, only include fields you want to change - omitted fields remain unchanged
6. **Reference Shortcuts:** You can use just the numeric part of an incident reference (e.g., `123` instead of full ID) when getting or editing incidents
7. **Retrospective Mode:** Use `mode: "retrospective"` when importing historical incidents to avoid Slack notifications
8. **URI Encoding:** Always URI encode query parameters, especially when using special characters or operators
9. **Severities and Statuses:** Always list available severities and statuses first before creating/editing incidents to ensure you're using valid IDs