API

Abläufe

Incident eröffnen, Wartung planen, Komponentenstatus setzen und Monitor anlegen, Schritt für Schritt mit curl.

Stand:

Störung: eröffnen, aktualisieren, schließen

Eine Störung durchläuft drei Aufrufe. Alle brauchen den Scope incidents mit Schreibrecht.

  1. incident:open eröffnet die Störung mit Titel, erstem Text und Schweregrad (minor, major oder critical, ohne Angabe minor). Mit componentIds verknüpfst du betroffene Komponenten. Die Antwort enthält die neue ID in data.id.
  2. incident:post-update ergänzt ein Update. Mit newStatus setzt du dabei den Stand: investigating, identified oder monitoring.
  3. incident:resolve schließt die Störung mit einem letzten Text.
shellStörung eröffnen
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:incident:open",
  "payload": {
    "title": "Elevated API latency",
    "body": "We are investigating elevated response times.",
    "severity": "major",
    "componentIds": [
      "<component-id>"
    ]
  }
}'
shellUpdate mit neuem Stand posten
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:incident:post-update",
  "payload": {
    "incidentId": "<incident-id>",
    "body": "A slow database query is the cause. A fix is rolling out.",
    "newStatus": "identified"
  }
}'
shellStörung schließen
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:incident:resolve",
  "payload": {
    "incidentId": "<incident-id>",
    "body": "Response times are back to normal."
  }
}'

Wartung: planen, starten, abschließen oder absagen

Wartungen brauchen den Scope maintenance mit Schreibrecht. maintenance:schedule legt das Fenster an, mit Start und Ende als ISO-8601-Zeitstempel. Die Antwort enthält die ID in data.id.

shellWartung planen
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:maintenance:schedule",
  "payload": {
    "title": "Database upgrade",
    "body": "The API is read-only during the upgrade.",
    "scheduledStart": "2026-11-10T02:00:00Z",
    "scheduledEnd": "2026-11-10T03:00:00Z",
    "componentIds": [
      "<component-id>"
    ]
  }
}'

Danach steuerst du die Wartung mit maintenance:start, maintenance:complete oder maintenance:cancel. Alle drei erwarten die id. Die version ist optional: Sendest du sie mit, lies sie aus maintenance:detail mit der id. Ist die Version veraltet, lehnt die API den Aufruf mit 409 und dem Code version_conflict ab.

shellWartung starten
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:maintenance:start",
  "payload": {
    "id": "<maintenance-id>",
    "version": 1
  }
}'
shellWartung abschließen
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:maintenance:complete",
  "payload": {
    "id": "<maintenance-id>",
    "version": 1
  }
}'
shellGeplante Wartung absagen
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:maintenance:cancel",
  "payload": {
    "id": "<maintenance-id>",
    "version": 1
  }
}'

Ungültige Übergänge lehnt die API ab, etwa das Starten einer bereits abgeschlossenen Wartung.

Komponente: anlegen und Status setzen

Komponenten brauchen den Scope components mit Schreibrecht. component:create legt eine Komponente an und liefert ihre ID in data.id. Eine neue Komponente startet mit operational.

shellKomponente anlegen
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:component:create",
  "payload": {
    "name": "API",
    "description": "Public HTTP API"
  }
}'

Den Status änderst du mit component:update. Neben id und den Änderungen in changes braucht der Aufruf die aktuelle version der Komponente. Du bekommst sie von component:detail mit der id. Nach dem Anlegen ist sie 1 und steigt mit jeder Änderung um eins. Mit einer veralteten version lehnt die API die Änderung ab.

shellKomponente auf schweren Ausfall setzen
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:component:update",
  "payload": {
    "id": "<component-id>",
    "version": 1,
    "changes": {
      "status": "major-outage"
    }
  }
}'
operational
Läuft normal.
degraded-performance
Eingeschränkt, zum Beispiel langsam.
partial-outage
Teilweiser Ausfall.
major-outage
Schwerer Ausfall.
under-maintenance
In Wartung.

So kann eine Deploy-Pipeline eine Komponente vor dem Rollout auf under-maintenance und danach wieder auf operational setzen.

Monitor: anlegen und sofort prüfen

Monitore brauchen den Scope monitors mit Schreibrecht. monitor:create legt einen Uptime-Monitor an. kind wählt die Art der Prüfung: http, keyword, ssl-expiry, tcp-port oder heartbeat. Das Intervall in intervalSeconds ist ein Text mit einem dieser Werte: "60", "300", "600" oder "1800". Mit componentId verknüpfst du eine Komponente, die bei einem Ausfall automatisch auf schweren Ausfall wechselt.

shellHTTP-Monitor mit verknüpfter Komponente anlegen
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:monitor:create",
  "payload": {
    "name": "API health",
    "kind": "http",
    "url": "https://api.example.com/health",
    "intervalSeconds": "300",
    "componentId": "<component-id>",
    "enabled": true
  }
}'

monitor:check-now prüft einen Monitor sofort und liefert das Ergebnis in data.up. Der Aufruf speichert nur einen Messpunkt. Komponenten, Störungen und Benachrichtigungen ändert erst die reguläre Prüfung.

shellMonitor sofort prüfen
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:monitor:check-now",
  "payload": {
    "monitorId": "<monitor-id>"
  }
}'

Einen Datensatz lesen: detail

Neben Listen bietet jeder Scope mit Lesezugriff einen :detail-Aufruf, der einen Datensatz anhand seiner id liefert. Er gibt auch die aktuelle version zurück, die Änderungen brauchen.

shellEine Störung lesen
curl -X POST https://status.example.com/api/query \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:query:incident:detail",
  "payload": {
    "id": "<incident-id>"
  }
}'