incident.io

incident.io

This connector works with incident.io through its public REST API (https://api.incident.io): incidents with their updates and timeline, the configuration they use (severities, statuses, roles, types, custom fields, timestamps), actions and follow-ups, alerts and alert sources, on-call schedules and escalations, users, teams and the catalog. It can declare and edit incidents, post updates, manage actions and follow-ups, resolve alerts and page people.

Setup (2 minutes)

1. In incident.io open Settings, API keys (https://app.incident.io/settings/api-keys) and click Add new. Only an admin (or a role allowed to manage API keys) can do this.
2. Name the key and tick what it may do. For reading, at least view data (viewer), plus catalog, schedules and on-call viewing; private incidents need their own permission. For writing: create incidents, edit incidents, manage actions and follow-ups, create escalations, and so on. A tool the key lacks a permission for answers 403.
3. Copy the key (it is shown once) into INCIDENT_IO_API_KEY and run incident_io_get_identity: it shows the key's name and roles.

Workflow

• What is going on: incident_io_list_incidents with status_category: ["live"] (Active in the app) or ["triage"], then incident_io_get_incident, incident_io_list_incident_updates and incident_io_list_incident_timeline_items. Advanced filters on custom fields or roles go in extra_filters.
• Look up ids first: incident_io_list_severities, incident_io_list_incident_statuses, incident_io_list_incident_roles, incident_io_list_incident_types, incident_io_list_custom_fields, incident_io_get_custom_field, incident_io_list_custom_field_options, incident_io_list_incident_timestamps, incident_io_list_users, incident_io_get_user.
• Declare and run an incident: incident_io_create_incident (needs an idempotency_key and visibility; use mode test for a try), then incident_io_create_incident_update for each update (it can change status and severity), and incident_io_edit_incident for other changes such as roles, custom fields, summary or closing it.
• Tasks: incident_io_list_actions, incident_io_get_action, incident_io_create_action, incident_io_update_action. After the incident: incident_io_list_follow_ups, incident_io_get_follow_up, incident_io_create_follow_up, incident_io_update_follow_up.
• Alerts: incident_io_list_alerts (status firing), incident_io_get_alert, incident_io_list_incident_alerts, incident_io_resolve_alert; sources: incident_io_list_alert_sources, incident_io_get_alert_source.
• On-call: incident_io_list_schedules, incident_io_get_schedule, incident_io_list_schedule_entries for who is on call in a window; incident_io_list_escalation_paths, incident_io_list_escalations; page someone with incident_io_create_escalation.
• Organisation and catalog: incident_io_list_teams, incident_io_list_catalog_types, incident_io_get_catalog_type, incident_io_list_catalog_entries (search with identifier), incident_io_get_catalog_entry.

Before writing: a new standard incident opens a channel and alerts people, an update is shared with responders and subscribers, and an escalation pages people on call. Confirm with the user first. Reuse the same idempotency_key when retrying a create, so a retry does not create a second incident, update or page.

Reading the answers: ids are ULIDs (26 characters, e.g. 01FCNDV6P870EA6S7TK1DSYDG0); the human reference is reference (INC-123). Times are ISO 8601 in UTC. Status categories in the API: triage, live (Active), learning (Post-incident), paused, closed, declined, canceled, merged. Severity rank: higher is more severe. Custom field option lists and alert source secret tokens are left out of the answers.

Paging: lists return pagination_meta with after; call again with after set to it until it is missing. page_size is 25 by default, up to 250 for most lists (alerts and catalog entries send 25 unless you pass another). incident_io_list_schedule_entries pages by putting pagination_meta.after into entry_window_start.

Errors: 401 means a wrong or deleted key, 403 a key without the needed permission (incident_io_get_identity shows its roles), 404 an unknown id, 422 a validation error whose errors name the field (e.g. a status transition that is not allowed), 429 the rate limit (1200 requests a minute per key).