Incident erstellen

Erstellt manuell einen Incident-Management-Incident für ein Team; die Eskalation wird kurz nach der Erstellung scharf geschaltet, mit demselben Paging-Verhalten wie ein aus einem Alert entstandener Incident.

POST /api/im/incidents

Erstellt einen Incident von Hand, außerhalb der Alert-Ingest-Pipeline, etwa für etwas, das ein Mensch bemerkt hat, bevor es ein Monitoring-Tool tat. Ein manuell erstellter Incident ist kein Incident zweiter Klasse: Eskalationsstufe 1 wird kurz nach der Erstellung scharf geschaltet, genau wie bei einem aus einem eingespeisten Alert entstandenen Incident. Dieses Scharfschalten läuft jedoch asynchron, nachdem diese Antwort bereits zurückgegeben wurde. Diese Antwort spiegelt also die Incident-Zeile so wider, wie sie committet wurde, noch bevor die Eskalation startet (siehe currentTier unten).

Authentifizierung

Erfordert denselben Basis-IM-Zugriff wie jeder Endpunkt dieser API (eine der IM-berechtigten Rollen admin, editor oder responder, oder einen organisationsweiten API-Token; Incident Management muss für die Organisation aktiviert sein). Das Erstellen eines Incidents erfordert zusätzlich die Schreib-Hürde für das Ziel-Team: Deine Rolle muss admin sein (auf Organisationsebene), oder du musst Team-Admin sein (ein im_team_member dieses Teams mit imRole: 'admin'). Ein organisationsweiter API-Token erfüllt die Organisations-Admin-Hürde, da er als synthetische admin-Rolle authentifiziert.

Request Body

Feld	Typ	Erforderlich	Beschreibung
`teamId`	number	Ja	Das Team, dem der Incident gehört. Muss zu deiner Organisation gehören.
`title`	string	Ja	Incident-Titel, bis zu 10.000 Zeichen.
`severity`	string	Ja	Einer von `sev1`, `sev2`, `sev3`, `sev4`. Muss explizit gesetzt werden: ein manueller Incident hat keinen Alert-Stream, aus dem sich der Schweregrad ableiten ließe, daher ist er immer `severityManual: true`.
`customerId`	number	Nein	Ordnet den Incident einem Kunden zu. Muss, falls angegeben, zu deiner Organisation gehören.
`escalationPolicyId`	number	Nein	Zu verwendende Eskalationsrichtlinie. Muss, falls angegeben, zu deiner Organisation gehören. Weggelassen (oder `null`) löst zur Standardrichtlinie des Teams auf (`im_escalation_policy` mit `isDefault: true`), oder zu `null`, falls das Team keine hat. Es fällt nie stillschweigend auf "keine Richtlinie" zurück, wenn das Team eine konfiguriert hat.

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

Antwort (Response)

200 OK: die neu erstellte Incident-Zeile (gleiche Form wie die items von Incidents auflisten).

{
  "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 ist manual und primarySourceId ist null: ein manuell erstellter Incident hat keine zugrunde liegende Alert-Source. Das Scharfschalten der initialen Eskalation und ein eventueller Outbound-Integrations-Fan-out laufen best-effort, nachdem die Incident-Zeile committet wurde: Der Incident existiert garantiert auch dann, wenn Paging oder eine Outbound-Integration fehlschlägt, ein solcher Fehler wird serverseitig geloggt, aber nicht in dieser Antwort sichtbar. Da die Eskalation erst scharf geschaltet wird, nachdem diese Antwort zurückgegeben wurde, ist currentTier in der Create-Antwort immer null. Frage Incidents auflisten oder Incident abrufen ab, um die Stufe zu sehen, sobald die Eskalation gestartet ist.

Häufige Fehler

401 Unauthorized wenn du nicht authentifiziert bist
403 Forbidden (imAccessDenied) bei Verwendung eines kunden-gescopten Tokens, oder wenn deine Session keine IM-berechtigte Rolle hat
403 Forbidden (imNotEnabled) wenn Incident Management für die Organisation nicht aktiviert ist
403 Forbidden (imTeamWriteDenied) wenn deine Rolle nicht admin ist und du kein Team-Admin von teamId bist
400 Bad Request (invalidRequestBody) wenn teamId fehlt oder keine positive Ganzzahl ist, title fehlt oder 10.000 Zeichen überschreitet, severity nicht einer von sev1 bis sev4 ist, oder customerId/escalationPolicyId angegeben, aber keine positive Ganzzahl ist
422 Unprocessable Entity (invalidTeamId) wenn teamId nicht zu deiner Organisation gehört
422 Unprocessable Entity (invalidCustomerId) wenn customerId angegeben ist, aber nicht zu deiner Organisation gehört
422 Unprocessable Entity (imRoutingInvalidPolicyId) wenn escalationPolicyId angegeben ist, aber nicht zu deiner Organisation gehört