---
title: "Create Incident"
description: "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)

```bash
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](./list-incidents)' `items`).

```json
{
  "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](./list-incidents) or [Get Incident](./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