API Monitor-Gruppen

Basis-URL: https://api.okstatus.eu/api/v1/monitor-groups — jede Anfrage braucht einen Header Authorization: Bearer oks_live_..., siehe Authentifizierung.

Eine Gruppe ist ein Ordner der Seite Monitors. Zwei Regeln erklären die folgenden Endpunkte:

• Ein Monitor gehört höchstens zu einer Gruppe. Wer ihn in eine Gruppe legt, nimmt ihn aus der bisherigen heraus.
• Eine Gruppe kann Alarmkanäle tragen. Ein Monitor, der der Gruppe beitritt, bekommt sie zugeordnet; Monitors, die schon in der Gruppe sind, bleiben unberührt, wenn sich die Kanäle der Gruppe ändern.

Gruppen auflisten

GET /api/v1/monitor-groups

Liefert alle Gruppen in der Reihenfolge des Dashboards, mit den IDs ihrer Monitors.

{
  "data": [
    {
      "id": "7b1e…",
      "name": "Zahlung",
      "description": "Der gesamte Bestellweg",
      "color": "aurora",
      "tags": ["prod"],
      "alertChannelIds": ["3f6e…"],
      "monitorIds": ["a41c…", "c9d2…"],
      "paused": false,
      "muted": false
    }
  ]
}

paused und muted zeigen, ob die Gruppe als Ganzes im Dashboard pausiert oder stummgeschaltet wurde; hier sind sie nur lesbar. Um Monitors über die API zu pausieren, senden Sie ein PATCH an jeden Monitor.

Eine Gruppe anlegen

POST /api/v1/monitor-groups
Content-Type: application/json

Feld	Typ	Pflicht	Beschreibung
name	string	✅	Name der Gruppe (1–255 Zeichen)
description	string		Freitext, der unter dem Namen steht
color	string		Eine Farbe der Dashboard-Palette, über ihren Schlüssel — so, wie er für eine bestehende Gruppe zurückkommt
tags	string[]		Bis zu 10 Tags für die Gruppe selbst (sie werden nicht auf ihre Monitors kopiert)
alertChannelIds	string[]		Kanäle, die jedem Monitor zugeordnet werden, der der Gruppe beitritt
monitorIds	string[]		Die Monitors der Gruppe

Antwortet mit 201 und { "data": Gruppe }. Ist eine der monitorIds kein Monitor Ihrer Organisation, scheitert die Anfrage mit 404 NOT_FOUND, und es wird keine Gruppe angelegt.

Eine Gruppe lesen / ändern / löschen

GET    /api/v1/monitor-groups/:id
PATCH  /api/v1/monitor-groups/:id
DELETE /api/v1/monitor-groups/:id

PATCH akzeptiert dieselben Felder wie das Anlegen, alle optional. monitorIds ist die vollständige Zusammensetzung: Monitors, die in der Liste fehlen, verlassen die Gruppe, und [] leert sie.

curl -X PATCH https://api.okstatus.eu/api/v1/monitor-groups/$GROUP_ID \
  -H "Authorization: Bearer $OKSTATUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "monitorIds": ["a41c…", "c9d2…", "e07f…"] }'

DELETE entfernt nur die Gruppe — ihre Monitors bleiben erhalten und stehen wieder in der Liste ohne Gruppe. Die Antwort ist { "data": { "deleted": true } }.

Fehler

404 NOT_FOUND, wenn die Gruppe oder ein in monitorIds genannter Monitor in Ihrer Organisation nicht existiert. Gemeinsames Fehlerformat und Ratenbegrenzung: siehe Authentifizierung.