Statusseiten per API

Was die API kann

Alles, was du im Dashboard an deiner Statusseite machst, geht auch über die CitexNode-API unter https://api.citexnode.com/api/v1/me/status-pages/…. Jeder Endpunkt mit allen Feldern steht in der API-Dokumentation unter statuspages; allgemeines zur API unter API und Statusseite einbinden.

Für Skripte nimmst du ein persönliches API-Token statt deines Logins.

Token anlegen

Dashboard → Konto → API-Tokens, Neues Token, Namen eintragen und unter Rechte wählen:

Ein Token darf nie bestellen, verlängern, das Paket wechseln, die Seite löschen und nichts an Einstellungen, Domains oder Webhooks ändern. Das geht nur angemeldet im Dashboard; ein Token bekommt dort 403 token_not_allowed.

Die ID deiner Seite

Die Endpunkte brauchen die ID der Seite, nicht ihre Adresse. Die Liste deiner Seiten mit ID:

curl -s https://api.citexnode.com/api/v1/me/status-pages \
  -H "Authorization: Bearer $CITEXNODE_TOKEN"

Beispiel: Vorfall öffnen

Ein Schreib-Token im Kopf Authorization: Bearer, dann:

curl -s -X POST https://api.citexnode.com/api/v1/me/status-pages/SEITEN_ID/incidents \
  -H "Authorization: Bearer $CITEXNODE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title":  { "de": "Langsame Antworten der API", "en": "Slow API responses" },
    "impact": "degraded",
    "status": "investigating",
    "body":   { "de": "Wir sehen erhöhte Antwortzeiten und schauen nach." }
  }'

Das öffnet den Vorfall und benachrichtigt Abonnenten und Webhooks, wie im Dashboard.

Die Werte:

• impact: notice (Hinweis), degraded (Eingeschränkt), partial_outage (Teilausfall), major_outage (Großer Ausfall).
• status: investigating, identified, monitoring, resolved.
• title und body mit de und optional en. Fehlt en, sehen englische Besucher den deutschen Text.
• Optional components: die IDs der betroffenen Komponenten.

Weitere Schritte schreibst du als Update an POST …/incidents/VORFALL_ID/updates mit status und body. Ein Update mit "status": "resolved" schließt den Vorfall.

Komponenten und Prüfarten

Komponenten legst du mit POST …/status-pages/SEITEN_ID/components an und änderst sie mit PATCH …/components/KOMPONENTEN_ID. Die Prüfart steht in check_type: manual, http, tcp, dns, ping, ssl, heartbeat oder citexnode. Was in target gehört, steht unter Komponenten und Prüfungen.

Einstellungen, die nur eine Prüfart kennt, stehen in check_options:

Felder anderer Prüfarten werden ignoriert. interval_seconds reicht vom kürzesten Intervall deines Pakets bis 3600, beim Heartbeat bis 86400.

Eine Heartbeat-Komponente hat kein target. Die Antwort enthält stattdessen heartbeat_url, die geheime URL für deinen Job. Ein PATCH mit "rotate_heartbeat": true erzeugt eine neue; die alte gilt dann sofort nicht mehr.

Beispiel: Heartbeat für ein Backup

Ein nächtliches Backup, das bis zu 30 Minuten länger laufen darf:

curl -s -X POST https://api.citexnode.com/api/v1/me/status-pages/SEITEN_ID/components \
  -H "Authorization: Bearer $CITEXNODE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":             { "de": "Nächtliches Backup", "en": "Nightly backup" },
    "check_type":       "heartbeat",
    "interval_seconds": 86400,
    "check_options":    { "grace_seconds": 1800 }
  }'

Aus der Antwort nimmst du heartbeat_url und rufst sie am Ende des Backups auf, etwa mit curl -fsS -m 10 "$HEARTBEAT_URL". Die URL gehört wie das Token in deine Secrets, nicht ins Repository.

Typische Einsätze

• Dein Deploy-Skript legt vor einem Update eine Wartung an.
• Dein eigenes Monitoring öffnet einen Vorfall, wenn es etwas sieht, das unsere Prüfungen nicht sehen können.
• Ein Skript legt für jeden neuen Server eine Komponente an.