Öffentliche API

SLAtus bietet zwei Arten von HTTP-Endpunkten:

• Lesende öffentliche Endpunkte für Status-Konsumenten, ohne Authentifizierung.
• Schreibende Endpunkte für Integrationen (Monitoring, CI-Pipelines, Chatbots). Sie benötigen einen Bearer-API-Token.

Die maschinenlesbare Spezifikation ist das OpenAPI-3.1-Dokument unter /openapi.json (Quelle: public/openapi.json). Interaktiv ist sie unter /api-docs zu finden (Swagger UI, ohne Anmeldung, nur auf Englisch). Das Dokument beschreibt /api/status, /api/outage/*, /api/incidents und /api/maintenances. /api/health ist darin nicht enthalten.

Öffentliche Endpunkte

Methode	Pfad	Beschreibung
GET	/api/status	Gesamtstatus, Liste der Komponenten mit Status und 90-Tage-Uptime. 30 Sekunden gecacht.
GET	/api/health	Infrastruktur-Health (Prozess und SELECT 1). Liefert keine Fachdaten, wird nie gecacht. Wird vom Docker-HEALTHCHECK genutzt.
GET	/feed.xml	RSS-Feed der Incidents
GET	/badge.svg	SVG-Statusbadge (Parameter style und label)

/api/status liefert status (operational, maintenance, degraded, partial_outage, major_outage), label, updatedAt und das Array components mit id, name, group, status und uptime90d.

/api/health antwortet mit 200 und {"status":"ok"} oder, wenn die Datenbank nicht erreichbar ist, mit 503 und {"status":"error","error":"database unavailable"}.

Schreibende Endpunkte (Bearer-Token)

Methode	Pfad	Body (wichtigste Felder)	Zweck
POST	/api/outage/start/{serviceId}	severity	Ausfall für einen Service starten
POST	/api/outage/end/{outageId}	end (optional, ISO-Zeit)	Ausfall beenden
POST	/api/outage/service/{serviceId}	start, end, severity	Ausfälle eines Services anlegen, ersetzen oder schließen
POST	/api/incidents	title, impact, message, componentIds, componentStatus, optional status, occurredAt, respondedAt	Incident anlegen
POST	/api/maintenances	title, scheduledStart, scheduledEnd, componentIds, optional description	Wartungsfenster anlegen

Hinweise:

• Zeiten werden als ISO 8601 mit Zeitzone übermittelt, zum Beispiel 2026-09-11T10:00:00Z. Externe Clients kennen die Serverzeitzone nicht.
• Werte für severity: degraded_performance, partial_outage, major_outage. Bei /api/outage/service ist zusätzlich operational erlaubt, um laufende Ausfälle zu schließen, und end darf null sein (Ausfall läuft weiter).
• Werte für impact: none, minor, major, critical.
• POST /api/incidents akzeptiert als Start-Status investigating, identified, monitoring oder resolved.
• Statusänderungen über die API erzeugen dieselben Benachrichtigungen wie Änderungen in der Admin-Oberfläche. Das Anlegen einer Wartung sendet maintenance_scheduled.
• /api/outage/start antwortet mit 409, wenn der Service bereits einen laufenden Ausfall mit demselben Schweregrad hat („Service already has an ongoing outage with this severity.“). Ein anderer Schweregrad wird übernommen. /api/outage/end antwortet mit 409, wenn der Ausfall schon beendet ist („Outage is already ended.“).
• /api/incidents und /api/maintenances prüfen die Token-Beschränkung für jede übergebene Komponente.

Antwortformat

Die schreibenden Routen liefern denselben Aufbau wie Server Actions (lib/api/response.ts):

{ "ok": true, "data": { "id": "…", "status": "partial_outage" } }

{ "ok": false, "error": "This token is not authorized for the requested service." }

Validierungsfehler enthalten fieldErrors statt einer rohen Zod-Issue-Liste. /api/status und /api/health liefern dagegen flache Objekte ohne ok und data.

Statuscodes

Code	Bedeutung
200	Erfolg
400	Ungültige Eingabe. Bei Validierungsfehlern mit fieldErrors, bei ungültigem JSON nur mit error („Invalid JSON body.“).
401	Token fehlt, ist unbekannt, abgelaufen oder widerrufen. Zählt als fehlgeschlagener Versuch.
403	Gültiger Token, aber für den Service nicht berechtigt („This token is not authorized for the requested service.“, bei Incidents und Wartungen „… for one or more of the requested services.“). Zählt nicht als fehlgeschlagener Versuch.
404	Unbekannter Service oder Ausfall
409	Konflikt, siehe Hinweise oben
429	Zu viele fehlgeschlagene Versuche. Der Header Retry-After nennt die Wartezeit.

Beispiel

curl -X POST https://status.example.com/api/incidents \
  -H "Authorization: Bearer $SLATUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "title": "Login-Fehler bei einzelnen Nutzern",
        "impact": "major",
        "message": "Wir untersuchen erhöhte Login-Fehler.",
        "componentIds": ["<component-uuid>"],
        "componentStatus": "partial_outage"
      }'

Tokens werden in der Admin-Oberfläche unter Settings → API, Karte API Access, angelegt und widerrufen (nur Rolle admin). Jeder Token kann auf ausgewählte Services beschränkt werden und ein Ablaufdatum haben.