Create 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 of the team is armed moments after creation, exactly as for an incident created from an ingested alert. That arming happens after this response is returned, so the response reflects the incident row as it was committed, before escalation starts (see currentTier below).

AuthenticationCopy Anchor Link

Any IM-eligible role (admin, editor, responder) or an organization-wide API token, see Authentication. Incident Management must be enabled for the organization.

Creating an incident additionally requires the write bar for the target team: an organization admin, or a team admin of that team (team member with imRole: "admin"). An organization-wide API token passes as an organization admin.

Request BodyCopy Anchor Link

Example (cURL)Copy Anchor Link

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"
  }'

ResponseCopy Anchor Link

200 OK: the newly created incident row (same shape as the items of List Incidents, without the enrichment fields).

{
  "id": 42,
  "organizationId": 1,
  "teamId": 3,
  "title": "Database connection pool exhausted",
  "customerId": null,
  "primarySourceId": null,
  "severity": "sev1",
  "severityManual": true,
  "status": "triggered",
  "mergedIntoId": null,
  "escalationPolicyId": null,
  "currentTier": null,
  "escalationEpoch": 0,
  "escalationCycle": 0,
  "acknowledgedBy": null,
  "acknowledgedAt": null,
  "snoozedUntil": null,
  "autoResolve": true,
  "resolvedBy": null,
  "resolveNote": null,
  "statuspageUpdate": null,
  "createdBy": null,
  "sourceKind": "manual",
  "isTest": false,
  "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. createdBy is the creating user's ID for a browser session and null for an API token. 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 such a failure is logged server-side, not surfaced in this response. Because escalation arms after this response is returned, currentTier is always null here. Use Get Incident to see the tier once escalation has started.

Common errorsCopy Anchor Link

• 401 Unauthorized when not authenticated
• 403 Forbidden (customerScopedTokenForbidden) when using a customer-scoped token
• 403 Forbidden (imAccessDenied) when the session user has no IM-eligible role
• 403 Forbidden (imNotEnabled) when Incident Management is not enabled for the organization
• 403 Forbidden (imTeamWriteDenied) when you are neither an organization admin nor a team admin of teamId
• 400 Bad Request (invalidRequestBody) when teamId is missing or not a positive integer, title is missing, blank or longer than 10,000 characters, severity is not one of sev1 to sev4, or customerId 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