---
title: "Dienste"
description: "Dienste Ihrer Organisation auflisten, anlegen, ändern und löschen (Dienst- und Asset-Inventar mit Kritikalität und verantwortlichem Team), und wie Vorfälle ihnen zugeordnet werden."
---

`GET /api/im/services` · `POST /api/im/services` · `GET /api/im/services/:id` · `PATCH /api/im/services/:id` · `DELETE /api/im/services/:id`

Ein **Dienst** ist etwas, das Ihre Organisation betreibt und das ein Vorfall treffen kann, etwa „Webshop“, „Kundenportal“ oder „Mail“. Jeder Dienst hat eine **Kritikalität** (`critical`, `high`, `medium`, `low`), optional ein verantwortliches [Team](/de/api/incident-management/teams) und die Monitore, aus denen er besteht. Das ist das Dienst- und Asset-Inventar, das NIS-2 verlangt (Durchführungsverordnung (EU) 2024/2690, Anhang 12 und 5.2).

Jeder Vorfall trägt `serviceId` (`null` = kein Dienst). Gesetzt wird es auf zwei Wegen:

- **Automatisch**, wenn die eingebaute Monitoring-Brücke einen Vorfall öffnet und dessen Monitor **genau einem** Dienst Ihrer Organisation gehört. Ein Monitor in zwei Diensten ist mehrdeutig und lässt `serviceId` leer; Alerts aus anderen Quellen (Webhooks, E-Mail, API) werden nie automatisch zugeordnet.
- **Von Hand** mit [Dienst eines Vorfalls setzen](/de/api/incident-management/incident-service).

`:id` nimmt die numerische `id` oder die `publicId`.

## Authentifizierung

Lesen darf jede IM-berechtigte Rolle (`admin`, `editor`, `responder`) und jedes organisationsweite API-Token, siehe [Authentifizierung](/de/api/incident-management#authentifizierung). **Anlegen, Ändern und Löschen** verlangen die Rolle `admin` der Organisation; ein API-Token läuft mit der Rolle der Person, die es angelegt hat. Andere Rollen erhalten `403` `imServiceWriteDenied`.

## Das Dienst-Objekt

| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `id` | integer | Interne ID. |
| `publicId` | string (UUID) | Öffentliche ID. |
| `organizationId` | integer | Besitzende Organisation. |
| `name` | string | 1 bis 200 Zeichen, je Organisation eindeutig ohne Rücksicht auf Groß/Klein. |
| `description` | string \| null | Höchstens 2000 Zeichen. |
| `criticality` | string | `critical`, `high`, `medium` oder `low`. |
| `ownerTeamId` | integer \| null | Verantwortliches Team; wird `null`, wenn das Team gelöscht wird. |
| `monitors` | object[] | `{ monitorType, monitorId, monitorName }`, nach Namen sortiert. Ein gelöschter Monitor erscheint nicht mehr. |
| `createdAt` / `updatedAt` | string (ISO 8601) | |

`monitorType` ist eines von `website` (auch Heartbeat- und Browser-Monitore), `dns`, `icmp`, `smtp`, `ssh`, `tcp`, `ftp`, `imap_pop`. Jede Art hat eigene IDs, ein Monitor ist deshalb immer das Paar `monitorType` + `monitorId`.

## Dienste auflisten

`GET /api/im/services`

| Parameter | Typ | Standard | Beschreibung |
|-----------|-----|----------|--------------|
| `page` | integer | `1` | Seitennummer. |
| `perPage` | integer | `50` | Seitengröße, höchstens `200`. |

```bash
curl "$BASE_URL/api/im/services" \
  -H "Authorization: Bearer $TOKEN"
```

`200 OK`, nach Namen sortiert:

```json
{
  "items": [
    {
      "id": 4,
      "publicId": "0d7c6a0e-6f43-4d3b-9b1e-2a8f1d1c5e77",
      "organizationId": 1,
      "name": "Webshop",
      "description": "Shop und Kasse",
      "criticality": "critical",
      "ownerTeamId": 3,
      "monitors": [
        { "monitorType": "website", "monitorId": 46, "monitorName": "shop.example.com" },
        { "monitorType": "dns", "monitorId": 9, "monitorName": "example.com DNS" }
      ],
      "createdAt": "2026-10-25T08:00:00.000Z",
      "updatedAt": "2026-10-25T08:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "perPage": 50
}
```

## Einen Dienst abrufen

`GET /api/im/services/:id` liefert einen Dienst in derselben Form.

## Dienst anlegen

`POST /api/im/services`

| Feld | Typ | Pflicht | Beschreibung |
|------|-----|---------|--------------|
| `name` | string | Ja | 1 bis 200 Zeichen, je Organisation eindeutig ohne Rücksicht auf Groß/Klein (`409 imServiceNameTaken`). |
| `description` | string \| null | Nein | Höchstens 2000 Zeichen. |
| `criticality` | string | Nein | `critical`, `high`, `medium` (Standard) oder `low`. |
| `ownerTeamId` | integer \| null | Nein | Ein Team Ihrer Organisation (`404 imTeamNotFound`). |
| `monitors` | object[] | Nein | `{ monitorType, monitorId }`, höchstens 500. Jeder Monitor muss Ihrer Organisation gehören (`404 imServiceMonitorNotFound`, `data.monitors` nennt die übrigen). |

Unbekannte Felder werden mit `400 invalidRequestBody` abgewiesen.

```bash
curl -X POST "$BASE_URL/api/im/services" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Webshop",
    "criticality": "critical",
    "ownerTeamId": 3,
    "monitors": [{ "monitorType": "website", "monitorId": 46 }]
  }'
```

`201 Created` mit dem Dienst.

## Dienst ändern

`PATCH /api/im/services/:id`

Merge-Patch: nur die zu ändernden Felder senden (dieselben Felder und Regeln wie beim Anlegen). `null` leert `description` oder `ownerTeamId`. `monitors` ersetzt die ganze Menge; `[]` entfernt alle Monitore. Antwort `200 OK` mit dem Dienst.

```bash
curl -X PATCH "$BASE_URL/api/im/services/4" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "criticality": "high" }'
```

## Dienst löschen

`DELETE /api/im/services/:id` antwortet `204 No Content`. Die Monitor-Zuordnungen gehen mit; Vorfälle bleiben und verlieren nur den Bezug (`serviceId` wird `null`).

Jedes Anlegen, Ändern und Löschen landet mit den geänderten Feldern im Audit-Protokoll der Organisation.

## Häufige Fehler

- `401 Unauthorized` ohne Anmeldung
- `403 Forbidden` (`imAccessDenied`, `imNotEnabled`) ohne IM-Zugang oder wenn Incident Management nicht aktiviert ist
- `403 Forbidden` (`imServiceWriteDenied`) wenn jemand ohne Admin-Rolle anlegt, ändert oder löscht
- `400 Bad Request` (`invalidRequestBody`) bei unbekannten Feldern oder falschen Typen; (`invalidIdentifier`) wenn `:id` weder ID noch UUID ist
- `404 Not Found` (`imServiceNotFound`) wenn es den Dienst nicht gibt oder er einer anderen Organisation gehört
- `404 Not Found` (`imTeamNotFound`, `imServiceMonitorNotFound`) für ein Team oder einen Monitor außerhalb Ihrer Organisation
- `409 Conflict` (`imServiceNameTaken`) wenn der Name schon vergeben ist