Create Incident

Manually creates an Incident Management incident for a team; escalation arms moments after creation, with the same paging behavior as an alert-sourced incident.

POST /api/im/incidents

Creates an incident by hand, outside the alert-ingest pipeline, e.g. for something a human noticed before any monitoring tool did. A manually-created incident is not a lesser incident: escalation tier 1 is armed moments after creation, exactly as it would be for an incident created from an ingested alert. But that arming happens asynchronously after this response is returned, so this response itself reflects the incident row as it was committed, before escalation starts (see currentTier below).

Authentication

Requires the same base IM access as every endpoint in this API (an IM-eligible admin, editor, or responder role, or an organization-wide API token; Incident Management must be enabled for the organization). Creating an incident additionally requires the write bar for the target team: your role must be admin (organization-level), or you must be a team admin (an im_team_member of that team with imRole: 'admin'). An organization-wide API token satisfies the organization-admin bar, since it authenticates as a synthetic admin role.

Request Body

Field	Type	Required	Description
`teamId`	number	Yes	The team that owns the incident. Must belong to your organization.
`title`	string	Yes	Incident title, up to 10,000 characters.
`severity`	string	Yes	One of `sev1`, `sev2`, `sev3`, `sev4`. Set explicitly: a manual incident has no alert stream to derive severity from, so it is always `severityManual: true`.
`customerId`	number	No	Scopes the incident to a customer. Must belong to your organization if given.
`escalationPolicyId`	number	No	Escalation policy to use. Must belong to your organization if given. Omitted (or `null`) resolves to the team's default policy (`im_escalation_policy` with `isDefault: true`), or `null` if the team has none. It never silently falls through to "no policy" when the team has one configured.

Example (cURL)

curl -X POST "$BASE_URL/api/im/incidents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": 3,
    "title": "Database connection pool exhausted",
    "severity": "sev1"
  }'

Response

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

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

sourceKind is manual and primarySourceId is null: a manually-created incident has no backing alert source. Arming the initial escalation and any outbound-integration fan-out happen best-effort after the incident row is committed: the incident is guaranteed to exist even if paging or an outbound integration fails, but a failure there is logged server-side, not surfaced in this response. Because escalation arms after this response is returned, currentTier is always null in the create response. Poll List Incidents or Get Incident to see the tier once escalation has started.

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
403 Forbidden (imTeamWriteDenied) when your role is not admin and you are not a team admin of teamId
400 Bad Request (invalidRequestBody) when teamId is missing or not a positive integer, title is missing or exceeds 10,000 characters, severity is not one of sev1 to sev4, or customerId/escalationPolicyId is present but not a positive integer
422 Unprocessable Entity (invalidTeamId) when teamId does not belong to your organization
422 Unprocessable Entity (invalidCustomerId) when customerId is given but does not belong to your organization
422 Unprocessable Entity (imRoutingInvalidPolicyId) when escalationPolicyId is given but does not belong to your organization