Healthchecks-API: Checks per API v2 anlegen und abfragen

Mit der Healthchecks-API (Teil der API v2 von IPv64.net) legst du Checks per Skript an, änderst, pausierst und löschst sie, fragst Messwerte, Ereignisse und Störungen ab und verwaltest Benachrichtigungskanäle, Wartungsfenster und Nodes. Die Feldnamen sind dieselben wie in der API von Node64, sodass Skripte gegen beide gleich aussehen.

Überblick: Basis-URL, Format und Fehler

Alle Pfade dieser Seite beginnen mit /hc2 und hängen an die Basis-URL der API v2:

https://ipv64.net/api/v2

• Methoden: GET, POST, PATCH und DELETE. Wer nur GET und POST senden kann, schickt POST mit dem Header X-HTTP-Method-Override: PATCH (bzw. DELETE).
• Anfragen als JSON (Content-Type: application/json), höchstens 1 MB. PATCH ändert nur die mitgeschickten Felder.
• Antworten als JSON im Umschlag {"data": …, "meta": {…}}; meta gibt es nur bei Listen mit Seitenangaben. DELETE antwortet mit 204 ohne Inhalt.
• Zeiten im Format ISO 8601 mit Zeitzone, in Antworten immer UTC (z. B. 2026-10-26T08:15:00.000Z).
• Die vollständige Beschreibung als OpenAPI 3.1 (Bereich „Healthchecks 2.0“) gibt es unter ipv64.net/api_v2_docs.

Fehler

Fehler kommen nach RFC 9457 als application/problem+json mit einem festen Fehlercode in code:

{
  "type": "https://ipv64.net/api/v2/errors#limit_reached",
  "title": "Forbidden",
  "status": 403,
  "detail": "Online-Limit erreicht: 10 von 10 Messstellen belegt, benötigt werden 2 weitere. …",
  "code": "limit_reached",
  "errors": ["Online-Limit erreicht: …"]
}

Authentifizierung und Limits

Die API nutzt deine API-Keys aus Account > API (siehe Konto: API-Keys). Den Key schickst du nur im Header – nie in der URL:

curl "https://ipv64.net/api/v2/hc2/account" -H "Authorization: Bearer DEIN_API_KEY"
curl "https://ipv64.net/api/v2/hc2/account" -H "X-API-Key: DEIN_API_KEY"

Limits

• Allgemein: je Konto bis 300 Anfragen auf einmal, danach 10 pro Sekunde; je IP-Adresse 600 auf einmal, danach 20 pro Sekunde. Fehlgeschlagene Anmeldungen: 20, danach 12 pro Minute je IP. Die Header RateLimit-Limit und RateLimit-Remaining zeigen den Stand; bei 429 nennt Retry-After die Wartezeit in Sekunden.
• Testnachrichten: eine pro 30 Sekunden je Kanal.
• Bestätigungscodes: 5 Codes pro Stunde, 10 Eingabeversuche pro Stunde – gemeinsam mit dem Portal.
• Versand über einen IPv64-Kanal (/send): 30 auf einmal, danach 30 pro Stunde, höchstens 200 pro Tag; SMS zusätzlich nach dem Tageslimit deiner Kontoklasse.
• Die Grenzen der Kontoklasse für Healthchecks (Online-Messstellen, Online-Messungen pro Tag, Standorte je Check) gelten auch per API, siehe Limits.

Konto und Einstellungen

GET /hc2/account

Kontoklasse, Limits und Verbrauch:

{"data": {
  "plan": "Supporter",
  "online_measuring_points": {"used": 6, "limit": 10},
  "locations_per_check": 2,
  "checks_per_day": {"used": 2817, "limit": 8192},
  "sms_per_day": 50,
  "locations": [{"code": "fsn", "name": "Falkenstein"}, {"code": "nbg", "name": "Nürnberg"}],
  "nodes": {"total": 1, "online": 1},
  "checks": 12
}}

limit: null heißt unbegrenzt; bei sms_per_day steht dafür 0.

GET und PATCH /hc2/settings

Ruhezeiten und Sammelmeldung des Kontos (siehe Benachrichtigungen). Erlaubte Schlüssel:

curl -X PATCH "https://ipv64.net/api/v2/hc2/settings" -H "Authorization: Bearer DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notify.quiet_enabled": true, "notify.quiet_from": "23:00", "notify.quiet_to": "06:30"}'

Checks verwalten

Felder eines Checks

Die Antwort enthält zusätzlich token, node_id, node_name, nodes (mit Namen), revision, created_at, updated_at und state mit state, since, last_check_at, last_status, last_latency_ms, last_reason, last_message, down_since und last_push_at. Push-Checks haben dazu ein Objekt push (siehe Push-URL). Der Zustand ist einer von up, down, degraded, flapping, stabilizing, dependent, pending und paused; „nicht überwacht“ und „Kontingent aufgebraucht“ erkennst du an pending mit last_reason unchecked bzw. quota_exhausted.

Parameter je Typ (params)

json_rules ist eine Liste aus Objekten {"path": "status", "op": "eq", "value": "ok"} mit den Vergleichen eq, ne, lt, le, gt, ge, contains, not_contains, regex, exists, not_exists – oder die Textform wie im Formular. Grenzen und Bedeutung aller Werte stehen unter Check-Typen.

Beispiele

HTTPS-Check von beiden Standorten anlegen:

curl -X POST "https://ipv64.net/api/v2/hc2/checks" -H "Authorization: Bearer DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "http", "name": "Webseite", "target": "https://example.com/",
       "interval_seconds": 60, "locations": ["nbg", "fsn"],
       "params": {"accept_status": "200-299", "cert_min_days": 14}}'

Push-Check für ein nächtliches Backup:

curl -X POST "https://ipv64.net/api/v2/hc2/checks" -H "Authorization: Bearer DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "push", "name": "Backup NAS", "params": {"period_seconds": 86400, "grace_seconds": 3600}}'

Gestörte Checks auflisten, einen Check pausieren:

curl "https://ipv64.net/api/v2/hc2/checks?state=down" -H "Authorization: Bearer DEIN_API_KEY"
curl -X POST "https://ipv64.net/api/v2/hc2/checks/DEIN_CHECK_TOKEN/pause" -H "Authorization: Bearer DEIN_API_KEY"

Fehler beim Anlegen: 422 invalid_healthcheck (ungültige Eingabe), 422 private_target (privates Ziel online), 403 limit_reached (Messstellen-Limit).

Ausführungsort ändern (Umhängen)

Ändert ein PATCH execution, die Nodes oder die Standorte, speichert die API alle anderen Felder, lässt den Ausführungsort aber unverändert und antwortet mit 409 move_requires_test. Den Wechsel machst du mit einem Testlauf – oder du schickst "force_move": true mit, dann wird ohne Test umgestellt.

curl -X POST "https://ipv64.net/api/v2/hc2/checks/DEIN_CHECK_TOKEN/move" -H "Authorization: Bearer DEIN_API_KEY" \
  -H "Content-Type: application/json" -d '{"execution": "both", "nodes": ["DEINE_NODE_ID"], "locations": ["nbg", "fsn"]}'

{"data": {"id": 4711, "status": "ok", "target": "both", "applied": true,
  "results": [{"source": "ipv64 Nürnberg", "ok": true, "message": "ipv4 up 23.4 ms"}, …]}}

Frage den Testlauf alle 2 Sekunden ab, höchstens 60 Sekunden lang. status ist pending, ok (Wechsel übernommen, applied: true), failed (bleibt wie bisher) oder expired (keine Antwort in 60 Sekunden, dann mit error). Fehler beim Start: 409 unchanged (läuft schon so), 422 move_rejected (z. B. Node offline, Fernverwaltung aus, privates Ziel, Limit, Docker-Check).

Messwerte, Ereignisse, Störungen und Statistik

• Messstellen (source): loc:nbg bzw. loc:fsn für die IPv64-Standorte, node:NODE_ID für eine Node, push für Pushes.
• Einzelmessungen hebt IPv64.net nur kurz auf; für längere Zeiträume nimm /stats.
• Seiten bei Ereignissen: meta enthält limit, has_more und next_before (bzw. next_after, wenn du mit after vorwärts blätterst). Den Wert gibst du bei der nächsten Anfrage als before bzw. after mit.
• silent: true heißt: Zu diesem Ereignis wurde keine Nachricht verschickt.

curl "https://ipv64.net/api/v2/hc2/checks/DEIN_CHECK_TOKEN/stats?range=30d" -H "Authorization: Bearer DEIN_API_KEY"
curl "https://ipv64.net/api/v2/hc2/incidents?open=true" -H "Authorization: Bearer DEIN_API_KEY"

Push-URL für Cronjobs

Pushes laufen nicht über die API v2 und brauchen keinen API-Key. Jeder Push-Check hat in der Antwort ein Objekt push:

# OK melden
curl -fsS -m 10 "https://ipv64.net/health.php?token=DEIN_PUSH_TOKEN"
# Störung melden
curl -fsS -m 10 "https://ipv64.net/health.php?token=DEIN_PUSH_TOKEN&status=down&msg=backup+fehlgeschlagen"

Parameter: status=down oder fail für eine Störung, msg bzw. message für eine Meldung (bis 500 Zeichen). Die Antwort ist OK. Höchstens 60 Pushes pro Minute je Token; Pushes zählen gegen das Tageskontingent. Mehr unter Push-Checks.

Benachrichtigungskanäle

Kanaltypen und ihre config-Schlüssel: ipv64_mail (email), ipv64_sms (number), app (device_key, critical), telegram (bot_token, chat_id, silent), discord (webhook_url, username), slack und teams (webhook_url), matrix (server, token, room), ntfy (server, topic, token, user, password, priority_down, priority_up), gotify (server, app_token, priority), pushover (user_key, app_token, device, priority_down, priority_up), webhook (url, method, headers, body, insecure_tls), smtp (host, port, security, user, password, from, to). Bedeutung und Standardwerte: Kanaltypen. URLs und der SMTP-Host müssen öffentlich sein, SMTP nur über Port 25, 465, 587 oder 2525; sonst 422 invalid_channel mit den Meldungen in errors. Interne Ziele gehen nur über einen Kanal der Node.

curl -X POST "https://ipv64.net/api/v2/hc2/channels" -H "Authorization: Bearer DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "ntfy", "name": "ntfy Handy", "default": true, "config": {"server": "https://ntfy.sh", "topic": "mein-geheimes-topic"}}'

Bei /send wird eine event_id, die in den letzten 24 Stunden schon erfolgreich verschickt wurde, nicht erneut gesendet (Antwort duplicate: true). Die Antwort nennt bei SMS in sms_left, wie viele SMS heute noch gehen (null = unbegrenzt).

Wartungsfenster

Felder: name, start_at und end_at (ISO 8601, Pflicht, Ende nach Beginn), repeat (none, daily, weekly, monthly), repeat_until, tokens (Liste von Check-Tokens, leer = alle Checks) und active (Standard true).

curl -X POST "https://ipv64.net/api/v2/hc2/maintenance" -H "Authorization: Bearer DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Proxmox-Updates", "start_at": "2026-11-01T03:00:00+01:00", "end_at": "2026-11-01T04:00:00+01:00", "repeat": "weekly"}'

Nodes

Befehle nimmt die Node nur an, wenn ihre Fernverwaltung es erlaubt (siehe Fernverwaltung). Mit POST /node64/hello melden sich die Nodes selbst an; das brauchst du in eigenen Skripten nicht.

Fehler gefunden oder etwas fehlt? Schreibt uns im v64.tech-Forum. · Stand: 2026-11-04