Docs
API referenceinc_1, inc_2, and inc_3. Use those values in {incident_id} paths. Existing UUID incident links remain accepted for compatibility.
Every incident response includes source, which says exactly where the incident came from. source.kind is the same value as sourceType (monitor, heartbeat, integration, finding, or manual):
suspectDeployment with the deployment id, service, version, deployedAt, and gapSeconds. The field is null when no recent deployment is available.
Incident operations
Open and change an incident
Opening, changing, and deleting an incident requiresincidents:write. To open an incident, send a
title and one of the project’s severity keys (see Severity levels). The
response is the incident, with status code 201:
severity, status, and assignedTo (a user ID, or
null to remove the assignee). The status can move to any of investigating, identified,
monitoring, and resolved: forward, back, resolve, or reopen. Each status change adds a timeline
event that notification routes receive. A reopened incident needs a new acknowledgement.
422. A scheduled maintenance record returns 409:
change it with the maintenance window operations.
Severity levels
Each project has its own severity levels. Level 1 is the most severe. The keys stay the same (sev-1, sev-2, …); the labels follow the naming style: SEV-1 (sev) or P1 (p).
Reads require
incidents:read, and changes require incidents:write. Removing the last level
returns 422. In the CLI, use squasher incidents severity list|add|naming-style|remove.
Maintenance windows
A maintenance window tells customers about planned work. A window linked to a status page shows on that page until it ends. Maintenance windows need Team or above; on other plans, a change returns403.
The body has
title, message (the notice on the status page), startsAt and endsAt (ISO 8601),
status (scheduled, active, or completed), and statusPageId (a status page in the project,
or null to show the window on no page). When you create a window, omitted times are now and the
status is scheduled. Reads require status_pages:read, and changes require status_pages:write.
Response comments and mentions
The Response tab keeps comments internal to the incident’s project; they are not public status-page updates. Write Markdown, including links and lists. Select a teammate from the mention picker rather than relying on typed display text: a selected mention is stored as@[Display Name](mention:USER_ID), with that user’s stable ID in mentionedUserIds. The displayed name is only a label; IDs identify recipients. Mention links are rendered as text, not as navigable mention: URLs.
In the dashboard, the response thread shows each comment with its author and rendered Markdown. On desktop, press Cmd+Enter or Ctrl+Enter to post. Hover over a comment timestamp, focus it and press Enter or Space, or tap it on a touch device to see UTC ISO, local time, epoch seconds, and epoch milliseconds. Each format has its own copy button.
For API clients, create a comment with incidents:write and a user-authenticated actor (for example, OAuth):
body must be non-empty after trimming and contain at most 4,000 characters. mentionedUserIds is optional and accepts at most 32 distinct user IDs. Every selected recipient must belong to the incident’s organization; IDs outside it are rejected, and a label in body alone does not identify or notify a recipient. The author must belong to that organization. Reads require incidents:read within the project. Only the author can delete their comment. Comments are returned as { "data": [...] } by the list endpoint; a successful create returns the canonical comment with id, incidentId, body, createdAt, updatedAt, mentionedUserIds, and author (id, nullable name, nullable email, nullable image). API-key reads return null for member email addresses.
The dashboard displays your new comment immediately while the request completes, then reconciles it with the saved response (or removes it on failure). Other responders viewing the Response tab see new comments through a comments-only refresh about every two seconds and on window focus; this is near-live refresh, not a live connection. A comment-loading error does not block the rest of the incident detail.
Valid mentions create an in-app inbox item for each mentioned teammate other than the author. Account email is sent to mentioned teammates when an email address is available; an explicitly configured notification route can also post to its Slack channel. This is not a Slack direct message, and the comment is never published to a status page. See Notifications for comment_mentioned routing.
Service ownership operations
State changes, deletions, and ownership writes are confirmation-required. Link replacement is a full replacement; pass every link set that should remain. Use owner teams for human routing and services for the technical component or app that triggered the incident.
CLI and MCP
Usesquasher incidents ... for terminal workflows. In MCP Code Mode, call search("incidents") and inspect the operation schema before executing. The incident, severity level, and maintenance window operations are all in Code Mode. Hosted MCP may require approval for ack, resolve, delete, and write operations.
Agent handoff
Set a public post-incident review link
PATCH /v1/projects/{project_id}/incidents/{incident_id}/postmortem sets the public review link for a resolved, published incident. It requires status_pages:write.
null to remove the link, including after the linked status page is deleted. The response is { "postmortemUrl": "..." } or { "postmortemUrl": null }. The URL must use HTTP or HTTPS, have no embedded credentials, and contain at most 2,048 characters. An unpublished or unresolved incident returns 409. An incident outside the project returns 404.
client.incidents.updatePostmortem(incidentId, urlOrNull), client.incidents.create, update, and delete, client.incidentSeverity, and client.maintenanceWindows. MCP exposes incidents.updatePostmortem through Code Mode.