REST-API Dokumentation: Monitore per API steuern

Authentifizierung

Erzeugen Sie im Dashboard einen API-Token. Er beginnt mit uc_ und ist nur beim Erzeugen sichtbar; gespeichert wird nur ein Hash. Senden Sie ihn bei jeder Anfrage im Header Authorization: Bearer uc_…. Behandeln Sie ihn wie ein Passwort und nutzen Sie ihn nicht in Browser-Code.

curl -s https://www.uptimeshield.de/api/v1/summary \
  -H "Authorization: Bearer uc_IHR_TOKEN"

Antwort (Beispielwerte):

{
  "monitors": 7,
  "by_status": { "up": 5, "down": 1, "paused": 1 },
  "limit": 25
}

Endpunkte

Monitore anlegen, lesen und ändern

Zum Anlegen genügen type (http, keyword, api, ssl, dns, tcp, heartbeat), name, url (Ziel) und interval (Minuten). Der Monitor wird sofort einmal geprüft. Die Antwort enthält unter anderem id, status, interval_minutes, uptime (24h, 7d, 30d, 90d), response_time_24h_ms, certificate_days_left und bei Heartbeat-Monitoren die ping_url.

curl -s -X POST https://www.uptimeshield.de/api/v1/monitors \
  -H "Authorization: Bearer uc_IHR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"http","name":"Startseite","url":"https://www.example.com/","interval":5}'

curl -s https://www.uptimeshield.de/api/v1/monitors \
  -H "Authorization: Bearer uc_IHR_TOKEN"

curl -s -X PATCH https://www.uptimeshield.de/api/v1/monitors/42 \
  -H "Authorization: Bearer uc_IHR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Startseite (Produktion)","interval":10}'

Pausieren, fortsetzen, sofort prüfen

curl -s -X POST https://www.uptimeshield.de/api/v1/monitors/42/pause \
  -H "Authorization: Bearer uc_IHR_TOKEN"

curl -s -X POST https://www.uptimeshield.de/api/v1/monitors/42/resume \
  -H "Authorization: Bearer uc_IHR_TOKEN"

curl -s -X POST https://www.uptimeshield.de/api/v1/monitors/42/check \
  -H "Authorization: Bearer uc_IHR_TOKEN"

Prüfungen, Störungen und Uptime

checks liefert pro Prüfung Zeit, Ergebnis (ok), http_code, Antwortzeit (response_ms, ttfb_ms) und Fehlermeldung. limit ist bei Prüfungen auf 500 und bei Störungen auf 200 begrenzt (Standard 50).

curl -s "https://www.uptimeshield.de/api/v1/monitors/42/checks?limit=20" \
  -H "Authorization: Bearer uc_IHR_TOKEN"

curl -s "https://www.uptimeshield.de/api/v1/monitors/42/incidents?limit=10" \
  -H "Authorization: Bearer uc_IHR_TOKEN"

curl -s https://www.uptimeshield.de/api/v1/monitors/42/uptime \
  -H "Authorization: Bearer uc_IHR_TOKEN"

Berichte

Berichte stehen Tarifen mit Berichtsfunktion zur Verfügung (Pro und Max). Mit group_id begrenzen Sie den Bericht auf eine Kundengruppe.

curl -s "https://www.uptimeshield.de/api/v1/reports?range=prev_month" \
  -H "Authorization: Bearer uc_IHR_TOKEN"

Fehlerformat und Statuscodes

{
  "error": {
    "status": 404,
    "message": "Monitor nicht gefunden."
  }
}

• 401: Token fehlt, ist ungültig oder widerrufen (oder der Tarif enthält keinen API-Zugriff).
• 403: Funktion im Tarif nicht enthalten, etwa Berichte.
• 404: Monitor oder Ressource nicht gefunden.
• 422: Ungültige Eingabe, etwa nicht erlaubtes Ziel oder Tariflimit erreicht.
• 429: Rate Limit erreicht; warten Sie die Zeit aus Retry-After ab.

Heartbeat-Ping (ohne Authentifizierung)

Heartbeat-Monitore melden sich über /ping/{token}/. Die URL enthält den Token und braucht keinen Authorization-Header; erlaubt sind GET, POST und HEAD. Mehr dazu: Cronjobs mit Heartbeat überwachen.

# Am Ende eines Cronjobs
curl -fsS -m 10 --retry 3 https://www.uptimeshield.de/ping/IHR_PING_TOKEN/ > /dev/null

Weitere Umgebungen:

# Node.js (18+)
await fetch('https://www.uptimeshield.de/ping/IHR_PING_TOKEN/', { method: 'POST', signal: AbortSignal.timeout(10000) });

# Python
import urllib.request
urllib.request.urlopen('https://www.uptimeshield.de/ping/IHR_PING_TOKEN/', timeout=10)

# GitHub Actions (Schritt am Ende des Jobs)
- name: Heartbeat
  if: success()
  run: curl -fsS -m 10 --retry 3 https://www.uptimeshield.de/ping/IHR_PING_TOKEN/

# WordPress (functions.php)
wp_remote_get('https://www.uptimeshield.de/ping/IHR_PING_TOKEN/', ['timeout' => 10]);

Im Dashboard zeigt jeder Heartbeat-Monitor diese Beispiele mit eingesetzter Ping-URL, jeweils mit Kopier-Schaltfläche.