Acknowledge / Update Incident Status

POST /api/im/incidents/:id/status

Moves an incident between the "open" statuses: triggered, acknowledged, investigating, identified, monitoring. Any of the four non-triggered statuses is a valid target regardless of the incident's current one (not just the "next" status in sequence). This is also how you acknowledge an incident: set status to acknowledged.

This endpoint can never reach resolved (use Resolve Incident) and never merged.

Authentication

Same as List Incidents: any IM-eligible role (admin, editor, responder), or an organization-wide API token. Incident Management must be enabled for the organization.

Request Body

Example (cURL)

Acknowledge an incident:

curl -X POST "$BASE_URL/api/im/incidents/42/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "acknowledged" }'

Response

200 OK: the updated incident row (same shape as List Incidents' items).

{
  "id": 42,
  "organizationId": 1,
  "teamId": 3,
  "title": "Database connection pool exhausted",
  "customerId": null,
  "primarySourceId": 7,
  "severity": "sev1",
  "severityManual": false,
  "status": "acknowledged",
  "mergedIntoId": null,
  "escalationPolicyId": 5,
  "currentTier": null,
  "escalationEpoch": 1,
  "acknowledgedBy": "u_abc123",
  "acknowledgedAt": "2026-07-17T09:20:00.000Z",
  "snoozedUntil": null,
  "autoResolve": true,
  "resolvedBy": null,
  "resolveNote": null,
  "createdBy": null,
  "sourceKind": "alert",
  "triggeredAt": "2026-07-17T09:12:00.000Z",
  "resolvedAt": null
}

Transitioning to acknowledged additionally cancels any pending escalation jobs for the incident's current escalation cycle and re-arms the ack-timeout reminder.

Common errors

• 401 Unauthorized when not authenticated
• 403 Forbidden (imAccessDenied) when using a customer-scoped token, or a session without an IM-eligible role
• 403 Forbidden (imNotEnabled) when Incident Management is not enabled for the organization
• 400 Bad Request (invalidRequestBody) when :id is not a positive integer, or status is missing or not one of the four valid targets
• 404 Not Found (imIncidentNotFound) when the incident does not exist, or belongs to another organization
• 422 Unprocessable Entity (imIncidentInvalidStatusTransition) when status is not a legal target from the incident's current status, e.g. the incident is already resolved/merged, or status equals its current status
• 409 Conflict (imIncidentStatusConflict) when the incident's status changed concurrently between the read and the write, safe to retry