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.
incident:openeröffnet die Störung mit Titel, erstem Text und Schweregrad (minor,majorodercritical, ohne Angabeminor). MitcomponentIdsverknüpfst du betroffene Komponenten. Die Antwort enthält die neue ID indata.id.incident:post-updateergänzt ein Update. MitnewStatussetzt du dabei den Stand:investigating,identifiedodermonitoring.incident:resolveschließt die Störung mit einem letzten Text.
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>"
]
}
}'
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"
}
}'
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.
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.
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
}
}'
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
}
}'
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.
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.
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.
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.
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.
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>"
}
}'