Incident bestätigen / Status ändern

Zwei Endpunkte ändern den Status eines offenen Incidents:

• Bestätigen ist der idempotente „Ich kümmere mich"-Aufruf. Er wirkt auf jeden offenen Incident, der noch nicht bestätigt wurde, und steht allen mit IM-Zugriff offen, denn eine Bestätigung stoppt immer nur Alarmierungen.
• Status ändern bewegt einen Incident zwischen den offenen Status, einschließlich acknowledged. Das ist dem Team des Incidents vorbehalten.

Keiner der beiden Endpunkte kann resolved erreichen (dafür Incident lösen) oder merged (dafür Incidents zusammenführen).

Was eine Bestätigung stoppt, hängt vom aktuellen Eskalations-Tier des Incidents ab. Standardmäßig stoppt sie die ganze Eskalationskette. Ist dieser Tier so eingestellt, dass die Eskalation erst beim Lösen endet, verstummt mit der Bestätigung die aktuelle Alarmierung, weitere Tiers eskalieren aber weiter, bis der Incident gelöst ist.

AuthentifizierungAnkerlink kopieren

Jede IM-berechtigte Rolle (admin, editor, responder) oder ein organisationsweiter API-Token, siehe Authentifizierung. Incident Management muss für die Organisation aktiviert sein.

BestätigenAnkerlink kopieren

POST /api/im/incidents/:id/ack

Bestätigt einen offenen Incident, der noch keine Bestätigung trägt (acknowledgedAt ist null). Ein triggered-Incident wechselt zu acknowledged. Ein Incident, der ohne Bestätigung auf investigating, identified oder monitoring gesetzt wurde, behält seinen Status, die Bestätigung wird aber vermerkt (acknowledgedBy, acknowledgedAt) und die Eskalation stoppt genau wie bei einem triggered-Incident; status in der Antwort ist dann dieser unveränderte Status. Ein zweiter Aufruf, oder ein Aufruf auf einen resolved- oder merged-Incident, ist kein Fehler: die Antwort enthält alreadyAcknowledged: true und den aktuellen Status. Die Timeline vermerkt die Bestätigung mit source: "api" für einen API-Token und source: "ui" für eine Browser-Session.

Kein Request-Body.

Beispiel (cURL)Ankerlink kopieren

curl -X POST "$BASE_URL/api/im/incidents/42/ack" \
  -H "Authorization: Bearer $TOKEN"

Antwort (Response)Ankerlink kopieren

200 OK, erste Bestätigung:

{
  "acknowledged": true,
  "alreadyAcknowledged": false,
  "status": "acknowledged",
  "acknowledgedBy": "MFcTjWmYq2LpzR8vK1sXo",
  "acknowledgedAt": "2026-07-17T09:20:00.000Z"
}

Beide Antworten enthalten acknowledgedAt (ISO-Zeitstempel, oder null bei einem resolved/merged-Incident, der nie bestätigt wurde). Ein Incident gilt als bestätigt, wenn acknowledgedAt gesetzt ist oder status resolved bzw. merged lautet; leite das nicht aus acknowledgedBy ab, das bei einer Bestätigung per API-Token null ist.

200 OK, der Incident war bereits bestätigt:

{
  "acknowledged": true,
  "alreadyAcknowledged": true,
  "status": "investigating",
  "acknowledgedBy": "MFcTjWmYq2LpzR8vK1sXo",
  "acknowledgedAt": "2026-07-17T09:20:00.000Z"
}

Häufige FehlerAnkerlink kopieren

• 401 Unauthorized wenn du nicht authentifiziert bist
• 403 Forbidden (customerScopedTokenForbidden) bei Verwendung eines kunden-gescopten Tokens
• 403 Forbidden (imAccessDenied) wenn die angemeldete Person keine IM-berechtigte Rolle hat
• 403 Forbidden (imNotEnabled) wenn Incident Management für die Organisation nicht aktiviert ist
• 400 Bad Request (invalidRequestBody) wenn :id keine positive Ganzzahl ist
• 404 Not Found (imIncidentNotFound) wenn der Incident nicht existiert oder zu einer anderen Organisation gehört

Status ändernAnkerlink kopieren

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

Bewegt einen Incident zwischen den offenen Status triggered, acknowledged, investigating, identified und monitoring. Jeder der vier Nicht-triggered-Status ist von jedem offenen Status aus ein gültiges Ziel, nicht nur der „nächste"; triggered selbst ist nie ein Ziel. acknowledged bestätigt den Incident und stoppt die Eskalation wie oben beschrieben. Ein direkter Wechsel von triggered zu investigating, identified oder monitoring vermerkt keine Bestätigung.

Dem Team des Incidents vorbehalten: du musst Mitglied im Team des Incidents (teamId) oder Organisations-Admin sein. Ein organisationsweiter API-Token gilt dabei als Organisations-Admin.

Anfrage (Request Body)Ankerlink kopieren

Beispiel (cURL)Ankerlink kopieren

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

Antwort (Response)Ankerlink kopieren

200 OK: der aktualisierte Incident-Datensatz (gleiche Form wie die items von Incidents auflisten, ohne die Ergänzungsfelder).

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

Häufige FehlerAnkerlink kopieren

• 401 Unauthorized wenn du nicht authentifiziert bist
• 403 Forbidden (customerScopedTokenForbidden) bei Verwendung eines kunden-gescopten Tokens
• 403 Forbidden (imAccessDenied) wenn die angemeldete Person keine IM-berechtigte Rolle hat
• 403 Forbidden (imNotEnabled) wenn Incident Management für die Organisation nicht aktiviert ist
• 403 Forbidden (imTeamMembershipRequired) wenn du weder Mitglied im Team des Incidents noch Organisations-Admin bist
• 400 Bad Request (invalidRequestBody) wenn :id keine positive Ganzzahl ist, oder status fehlt oder kein bekannter Statuswert ist
• 404 Not Found (imIncidentNotFound) wenn der Incident nicht existiert oder zu einer anderen Organisation gehört
• 422 Unprocessable Entity (imIncidentInvalidStatusTransition) wenn status triggered, resolved oder merged ist, der Incident bereits resolved/merged ist, oder status dem aktuellen Status entspricht
• 409 Conflict (imIncidentStatusConflict) wenn sich der Status des Incidents zwischen Lesen und Schreiben gleichzeitig geändert hat, sicher wiederholbar