---
title: "Routing-Regeln"
description: "Routing-Regeln im Incident Management auflisten, anlegen, ändern und löschen: welchem Team ein neuer Incident zugeordnet wird, optional mit überschriebener Severity."
---

`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](/de/api/incident-management/teams) 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](/de/api/incident-management/alert-sources), die den Alert empfangen hat.

## Authentifizierung

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`-Objekt

| Feld | Typ | Beschreibung |
|-------|------|-------------|
| `source_ids` | integer[] | IDs von Alert-Quellen. Maximal 500 Einträge. |
| `severity` | string[] | Severities des Alerts, jeweils `sev1`, `sev2`, `sev3` oder `sev4`. |
| `customer_ids` | integer[] | Kunden-IDs. Maximal 500 Einträge. |
| `monitor_ids` | integer[] | Monitor-IDs. Maximal 500 Einträge. |
| `tags` | string[] | Nicht-leere Strings. Maximal 200 Einträge. |
| `field_matches` | object | Nur String-Werte. Maximal 50 Schlüssel. |

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.

<Callout type="warn">
Die Routing-Engine wertet heute nur `source_ids` und `severity` aus. Eine Regel, die `customer_ids`, `monitor_ids`, `tags` (nicht leer) oder `field_matches` (auch als `{}`) setzt, wird gespeichert, trifft aber nie auf einen Alert zu. Für Regeln, die wirken sollen, nutze `source_ids` und `severity`.
</Callout>

## Routing-Regeln auflisten

`GET /api/im/routing`

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

### Beispiel (cURL)

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

### Antwort (Response)

`200 OK`

```json
[
  {
    "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 abrufen

`GET /api/im/routing/:id`

Liefert eine Regel, in derselben Form wie ein Listeneintrag.

## Routing-Regel anlegen

`POST /api/im/routing`

### Request Body

| Feld | Typ | Erforderlich | Beschreibung |
|-------|------|----------|-------------|
| `teamId` | integer | Ja | Ziel-Team. Muss zu deiner Organisation gehören. Du brauchst die Schreibhürde für dieses Team. |
| `priority` | integer | Nein | Auswertungsreihenfolge, niedrigere zuerst. Nicht-negative Ganzzahl, Standard `100`. |
| `match` | object | Nein | Siehe [das `match`-Objekt](#das-match-objekt). Standard `{}` (trifft auf alles zu). |
| `severityOverride` | string \| null | Nein | `sev1` bis `sev4`, oder `null` (Standard), um die Severity des Alerts zu behalten. |
| `escalationPolicyId` | integer \| null | Nein | Altfeld. Wird angenommen (positive Ganzzahl oder `null`) und gespeichert, hat aber keine Wirkung. |

### Beispiel (cURL)

```bash
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)

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

## Routing-Regel ändern

`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).

```bash
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öschen

`DELETE /api/im/routing/:id`

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

`200 OK`

```json
{ "success": true }
```

## 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 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