The Incident Management plugin's API
All under /api/v1/x/incidents/, 404 while the plugin is off; reading needs incidents:read, changing
incidents:write, the settings incidents:admin (admins). You see an incident when you can see one of its affected
units. Guide: incidents.
| Endpoint | What |
|---|---|
GET ?status=&priority=&categoryId=&serviceId=&breached=true&commander=&unitId=&orgId=&q=&sort=&page=&pageSize= | Incidents, a page at a time: { incidents, total, page, pageSize } (pageSize up to 200; without it, the first 500). status: open, done or one status. priority: one or several (p1,p2). commander: me, none or a person's id. unitId: affecting the unit or one below it. serviceId: on the service or one of its offerings. sort: urgency (the default: open first, most urgent first, then resolved and closed, most recent first), started (newest first), target (resolve target soonest) or updated. |
GET export?format=&columns= (the same filters) | The list as a file: csv, xlsx or pdf, the columns named (the list's shown columns) or all; up to 10,000, logged with its filters, rows and checksums (exports). |
GET glance? (the same filters) | At a glance, within the filters: { total, missed, noCommander, critical, mine, onHold } (past a target, without a commander, P1 or P2, led by you, on hold). |
GET count | Open incidents you can see, and how many are P1 or P2 ({ open, critical }). |
GET options?orgId= | The organization's categories, resolution codes, whether resolving needs one, the causes a review picks from, the matrix and targets, and statusPage: whether it has a status page (the Status Page plugin on, and a portal with one). |
GET report?days=&orgId=&tz= | For the last days (default 30): declared and resolved per day, per priority (with targets missed) and per category, resolved per cause (causes: { cause, resolved, urgent }, urgent P1–P2; cause: null not set), the median time from detected to resolved, how many are open, and the five that took longest. |
GET people?unitIds=a,b | Who can be the commander: staff who can see every one of the units. |
POST | Declare: unitIds (one organization), title, optional summary, impact and urgency (high, medium, low; the priority follows the matrix) or priority (p1–p4), commanderId (default: you; null: nobody, and it starts as new), categoryId, startedAt, detectedAt (ISO times), caseRef (links it), public and publicTitle (public: on the status pages, with the Status Page plugin). |
GET <id> | The incident with its targets (respondDueAt, resolveDueAt, respondedAt, breaches, paused), resolution, closesAt, linked cases (those you can see, and whether each would get an update), its timeline (newest first) and review. |
PATCH <id> | Change status (new, investigating, identified, monitoring, on_hold with holdReason: supplier, customer, change, other; resolved with resolutionCode and resolutionNote when the settings ask; closed from resolved, and final), impact, urgency or priority, commanderId, categoryId, unitIds (units you can't see stay), title, summary, startedAt, detectedAt, public, publicTitle, with an optional note. A closed incident only takes notes (409 closed). |
POST <id>/notes | { body }: a note on the internal timeline (Markdown). |
PUT <id>/review | { review, cause, customerSummary }, each optional: the post-incident review (Markdown), the cause (one of the organization's causes; null clears it; 400 unknown_cause) and a draft summary for customers, once resolved or closed (400 not_resolved). The incident has cause, customerSummary, customerSummaryHtml, customerSummaryAt and customerSummarySentAt. |
POST <id>/links, DELETE <id>/links/<ref> | Link or unlink a case you can see, in the incident's organization. |
POST <id>/links/bulk | { refs }: link many; cases you can't see or in another organization are skipped ({ linked, already, skipped }). |
GET <id>/customer-update | Who an update would reach: { recipients, skipped: [{ ref, reason }], statusPage: { portals, subscribers } | null } (statusPage: the status pages a public incident shows on, with the Status Page plugin). |
POST <id>/customer-update | { body, final, resolveCases, statusPage, summary }: a reply on every linked case you may reply to, through the desk's reply (signature, timeline, events), and on a public incident the status pages that show it and their subscribers (with the Status Page plugin on; statusPage: false leaves them out). Tokens also need cases:reply. summary: true sends the summary for customers (once resolved) and keeps the text as the incident's summary. Answers { sent, skipped, failed, statusPage, subscribers, incident }. |
GET cases/<ref> | The incidents linked to a case. |
DELETE <id> | Delete an incident (admins). |
GET settings/<orgId>, PATCH settings/<orgId> | The settings (admins): closeAfterDays, waitReminderDays, waitResolveDays, matrix, targets (per priority { respond, resolve, businessHours } in minutes), businessHoursId, requireResolution, resolutionCodes, causes (what reviews pick from), notifyPriorities, notifyUserIds; the GET also lists the business hours and organizations to pick from. |
POST settings/<orgId>/categories, PATCH …/categories/<id>, DELETE …/categories/<id> | Categories (admins): { name, parentId } (one level of subcategories); rename or move (index); delete (with its subcategories; incidents keep none). |
Every five minutes the plugin (ctx.every):
- closes resolved incidents after the organization's days;
- reminds about and then resolves incidents waiting on the customer;
- notices missed targets.
The settings' priorities email the affected units' agents when declared or raised to (notifyStaff); linking a case
and resolving put an entry on the linked cases' timelines (incident_linked, incident_resolved).
MCP tools
| Scope | Tools |
|---|---|
incidents:read | list_incidents, get_incident, incident_options, incidents_report. get_incident includes the review's facts (times, minutes to detect, take and resolve, reach, missed targets). |
incidents:write | declare_incident; update_incident (status with hold reason or resolution, impact, urgency, priority, commander, category by name, title, summary, units, times, public, note); link_case_to_incident (also unlinks); send_incident_update (also needs cases:reply; summary for the summary for customers); write_incident_review (the text, the cause and a draft summary for customers) |
incidents:admin (admins) | change_incident_settings |
Webhook events
| Event | With |
|---|---|
incidents.declared | |
incidents.status_changed | from, to. |
incidents.priority_changed, incidents.commander_changed | |
incidents.resolved | The resolution. |
incidents.closed | auto when by the settings. |
incidents.target_breached | targets: respond, resolve. |
incidents.cases_linked | linked. |
incidents.customer_update_sent | sent, skipped, failed, summary, status_page. |
incidents.deleted |
Audited: declaring, status and priority changes, updates sent (how many, not the text), deleting, settings and categories.