Routing-Regeln

GET /api/im/routing · POST /api/im/routing · GET /api/im/routing/:id · PATCH /api/im/routing/:id · DELETE /api/im/routing/:id

Eine Routing-Regel entscheidet, zu welchem Team ein neuer Incident gehört. Wenn ein Alert einen Incident öffnet, werden die Regeln deiner Organisation nach priority durchlaufen (niedrigste zuerst, bei Gleichstand nach id). Die erste Regel, deren match zutrifft, gewinnt: Der Incident geht an das teamId dieser Regel, und severityOverride (falls gesetzt) ersetzt die Severity des Alerts. Trifft keine Regel zu, geht der Incident an das Team der Alert-Quelle, die den Alert empfangen hat.

AuthentifizierungAnkerlink kopieren

Erfordert den Basiszugriff auf Incident Management, den jeder Endpunkt dieser API braucht (eine IM-berechtigte Rolle admin, editor oder responder, oder ein organisationsweites API-Token; Incident Management muss für die Organisation aktiviert sein). Lesen darf jede IM-berechtigte Rolle. Anlegen, Ändern und Löschen erfordern zusätzlich die Schreibhürde: Deine Rolle muss admin sein, oder du musst Team-Admin des Teams der Regel sein. Ein organisationsweites API-Token läuft mit der Rolle der Person, die es erstellt hat; ein Token, das ein Organisations-Admin erstellt hat, erfüllt diese Hürde also. Eine Team-Admin-Mitgliedschaft gilt für ein Token nie.

Das match-ObjektAnkerlink kopieren

Ein leeres Objekt {} (oder ein weggelassenes match) trifft auf jeden Alert zu; damit baust du eine Auffangregel mit hoher priority-Zahl. Jede ID in source_ids, customer_ids und monitor_ids muss zu deiner Organisation gehören, sonst schlägt die Anfrage mit 422 fehl.

Routing-Regeln auflistenAnkerlink kopieren

GET /api/im/routing

Liefert alle Regeln deiner Organisation in Auswertungsreihenfolge (priority aufsteigend, dann id aufsteigend).

Beispiel (cURL)Ankerlink kopieren

curl -X GET "$BASE_URL/api/im/routing" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Antwort (Response)Ankerlink kopieren

200 OK

[
  {
    "id": 4,
    "organizationId": 1,
    "priority": 10,
    "match": { "source_ids": [7], "severity": ["sev1", "sev2"] },
    "teamId": 3,
    "escalationPolicyId": null,
    "severityOverride": "sev1",
    "createdAt": "2026-09-14T08:00:00.000Z",
    "updatedAt": "2026-09-14T08:00:00.000Z"
  },
  {
    "id": 5,
    "organizationId": 1,
    "priority": 100,
    "match": {},
    "teamId": 2,
    "escalationPolicyId": null,
    "severityOverride": null,
    "createdAt": "2026-09-14T08:05:00.000Z",
    "updatedAt": "2026-09-14T08:05:00.000Z"
  }
]

Routing-Regel abrufenAnkerlink kopieren

GET /api/im/routing/:id

Liefert eine Regel, in derselben Form wie ein Listeneintrag.

Routing-Regel anlegenAnkerlink kopieren

POST /api/im/routing

Request BodyAnkerlink kopieren

Beispiel (cURL)Ankerlink kopieren

curl -X POST "$BASE_URL/api/im/routing" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": 3,
    "priority": 10,
    "match": { "source_ids": [7], "severity": ["sev1", "sev2"] },
    "severityOverride": "sev1"
  }'

Antwort (Response)Ankerlink kopieren

200 OK: die angelegte Regel (gleiche Form wie ein Listeneintrag).

Routing-Regel ändernAnkerlink kopieren

PATCH /api/im/routing/:id

Teilweise Aktualisierung. Schick nur die Felder, die du ändern willst: priority, match, teamId, severityOverride, escalationPolicyId (gleiche Validierung wie beim Anlegen). Andere Felder werden ignoriert. Ein neues match ersetzt das gespeicherte vollständig. Du brauchst die Schreibhürde für das aktuelle Team der Regel und, wenn du teamId änderst, auch für das neue Team (das zur selben Organisation gehören muss).

curl -X PATCH "$BASE_URL/api/im/routing/4" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "priority": 5 }'

200 OK: die aktualisierte Regel.

Routing-Regel löschenAnkerlink kopieren

DELETE /api/im/routing/:id

curl -X DELETE "$BASE_URL/api/im/routing/4" \
  -H "Authorization: Bearer $TOKEN"

200 OK

{ "success": true }

Häufige FehlerAnkerlink kopieren

• 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 du die Schreibhürde für das Team der Regel (oder das neue Team) nicht erfüllst
• 400 Bad Request (invalidRequestBody) wenn :id keine positive Ganzzahl ist, teamId fehlt oder ungültig ist, priority keine nicht-negative Ganzzahl ist, severityOverride keine gültige Severity ist, escalationPolicyId keine positive Ganzzahl ist, oder match fehlerhaft ist (falsche Typen, zu viele Einträge)
• 404 Not Found (imRoutingRuleNotFound) wenn die Regel nicht existiert oder zu einer anderen Organisation gehört
• 422 Unprocessable Entity (invalidTeamId) wenn teamId nicht zu deiner Organisation gehört
• 422 Unprocessable Entity (imRoutingInvalidMatchReference) wenn eine ID in match zu einer anderen Organisation gehört oder nicht existiert. data.field nennt das Feld (source_ids, customer_ids oder monitor_ids), data.foreignIds listet die abgelehnten IDs