incident.io Incidents & Follow-ups
What is on fire right now, who is on call, and what did we promise to fix afterwards? Lists and declares incidents in incident.io, posts status updates that move severity or status, and tracks follow-ups and on-call schedule entries.
Connect this API to an AI agent Browse all specs
What you can do with incident.io Incidents & Follow-ups via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /v2/incidents |
listIncidents | List incidents, filtered by status, severity, type or date |
| POST | /v2/incidents |
createIncident | Declare a new incident |
| GET | /v2/incidents/{id} |
getIncident | Get one incident with its roles, severity and custom fields |
| POST | /v2/incidents/{id}/actions/edit |
editIncident | Change an incident's name, summary, severity, status or fields |
| GET | /v2/incident_updates |
listIncidentUpdates | List the status updates posted on incidents |
| POST | /v2/incident_updates |
postIncidentUpdate | Post an update, optionally moving status or severity |
| GET | /v1/severities |
listSeverities | List the severity levels your organisation uses |
| GET | /v1/incident_statuses |
listIncidentStatuses | List incident statuses (triage, active, closed...) |
| GET | /v1/incident_types |
listIncidentTypes | List incident types |
| GET | /v2/incident_roles |
listIncidentRoles | List incident roles such as lead or communications |
| GET | /v3/follow_ups |
listFollowUps | List follow-up actions, optionally for one incident |
| POST | /v3/follow_ups |
createFollowUp | Add a follow-up action to an incident |
| GET | /v2/users |
listUsers | List users or find one by email |
| GET | /v2/schedules |
listSchedules | List on-call schedules |
| GET | /v2/schedule_entries |
listScheduleEntries | See who is on call in a schedule for a time window |
Authentication
incidentioApiKey
Bearer token — sent as Authorization: Bearer <token>
How to get a credential
- In incident.io, open Settings → API keys (your role must allow managing API keys).
- Create a new key and name it (for example
VX Agents). - Choose only the permissions in the table below, then save.
- Copy the key right away; incident.io does not show it again.
Permissions used
| Key permission | Operations |
|---|---|
| View data | listIncidents, getIncident, listIncidentUpdates, listSeverities, listIncidentStatuses, listIncidentTypes, listIncidentRoles, listFollowUps, listUsers |
| View all incident data | optional: adds private incidents to the reads above |
| Create incidents | createIncident |
| Edit incidents | editIncident, postIncidentUpdate, createFollowUp |
| Read schedules | listSchedules, listScheduleEntries |
Common errors
- 401 Unauthorized: key missing, mistyped or deleted.
- 403 Forbidden: the key lacks the permission for that call (see the table).
- 422 Unprocessable Entity: a required field is missing, such as
idempotency_key,visibilityor a validseverity_id. - 429 Too Many Requests: rate limit (about 1,200 requests per minute per key); back off and retry.
Store the key as a VX Agents bearer token credential.
Usage guide
Setup
- Credential: an incident.io API key (bearer) with View data, plus Create incidents / Edit incidents for writes and Read schedules for on-call.
- Look up ids once and reuse them:
listSeverities,listIncidentStatuses,listIncidentTypesandlistIncidentRolesreturn the ids that writes and filters expect.
Run an incident
listIncidentsfor what is open. Filters use bracket syntax, e.g.status_category[one_of]=live,severity[one_of]=<severity id>,created_at[gte]=2026-10-01. Page withpage_size(max 500) andafter(the last id frompagination_meta). Test incidents are hidden unless you filter onmode.getIncidentfor the summary, current status, severity, role assignments and custom fields.listIncidentUpdateswithincident_idfor the timeline of status updates.- Declare:
createIncidentwithidempotency_key(any unique string, so a retry does not open a duplicate),visibility(publicorprivate),name,summary,severity_idand optionallyincident_type_id. Usemode: "test"when trying things out. - Communicate:
postIncidentUpdatewithincident_id,idempotency_key,message, and optionallyto_incident_status_idorto_severity_idto move the incident in the same step. - Change fields:
editIncidentwith{"incident": {"summary": "...", "severity_id": "..."}, "notify_incident_channel": true}. - After the incident:
listFollowUpswithincident_id, thencreateFollowUpwithincident_id,titleand optionallyassignee_id(fromlistUsers, which acceptsemail).
Declaring, editing and posting updates notify responders, Slack or Teams channels and status page subscribers. Show the change to the user and get a yes first.
Who is on call
listSchedules → listScheduleEntries with schedule_id and an entry_window_start / entry_window_end (RFC 3339) to see the current and next shifts.
Good to know
- Ids are ULIDs such as
01FCNDV6P870EA6S7TK1DSYDG0. - Private incidents only appear if the key also has View all incident data.
- Rate limit: 1,200 requests per minute per key. On 429, back off.
- Times are RFC 3339 in UTC.
Source: incident.io API reference (https://docs.incident.io/api-reference/introduction), checked 2026-10-19.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “incident.io Incidents & Follow-ups” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.