Lokale API

Alles, was die Oberfläche kann, geht auch per JSON-API – direkt in deinem Netz, ohne Cloud. Die Oberfläche nutzt selbst dieselbe API. Du meldest dich mit einem API-Key an und findest die vollständige Referenz als OpenAPI-Beschreibung in jeder Node.

Überblick

In den Beispielen steht node64.lan:8080 für deine Node. Setze am besten einmal deinen Key als Variable:

export N64="http://node64.lan:8080"
export N64_KEY="DEIN_API_KEY"

Referenz in der Node: /api/docs und /api/openapi.json

Jede Node bringt ihre eigene, passende API-Referenz mit:

• /api/docs – Menüpunkt API: alle Endpunkte nach Bereichen (Node, Healthchecks, DynDNS, DNS64, PROXY64, Zertifikate …) und die Verwaltung deiner API-Keys.
• /api/openapi.json – dieselbe Beschreibung als OpenAPI 3.1, zum Beispiel für Postman, Insomnia oder einen Code-Generator.

Beide brauchen eine Anmeldung (Sitzung oder API-Key). So holst du die Beschreibung per Skript:

curl -H "Authorization: Bearer $N64_KEY" -o openapi.json "$N64/api/openapi.json"

API-Key anlegen

1. Öffne den Menüpunkt API (/api/docs) und gehe zum Abschnitt API-Keys.
2. Gib einen Namen ein, der den Zweck beschreibt, etwa backup-skript oder prometheus (1 bis 100 Zeichen), und klicke auf Erzeugen.
3. Kopiere den Key sofort. Er beginnt mit node64_ und wird nur dieses eine Mal angezeigt; Node64 speichert nur einen Hash.

In der Liste siehst du Name, Kurzhinweis, Erstellung und „zuletzt benutzt“. Nicht mehr gebrauchte Keys löschst du dort. Mit einem vorhandenen Key geht das auch per API:

# weiteren Key anlegen – der Key steht nur in dieser Antwort
curl -X POST -H "Authorization: Bearer $N64_KEY" -H "Content-Type: application/json" \
  -d '{"name": "homeassistant"}' "$N64/api/keys"

# Keys auflisten (ohne den Key selbst) und einen löschen
curl -H "Authorization: Bearer $N64_KEY" "$N64/api/keys"
curl -X DELETE -H "Authorization: Bearer $N64_KEY" "$N64/api/keys/3"

Authentifizierung

Schicke den Key bei jeder Anfrage im Kopf Authorization mit:

curl -H "Authorization: Bearer $N64_KEY" "$N64/api/status"

• Der Key gilt nur für Pfade unter /api/. Für KI-Anwendungen gibt es eigene MCP-Schlüssel (mcp64_…) – siehe KI-Schnittstelle (MCP).
• Anfragen mit API-Key brauchen kein CSRF-Token – das ist nur für die Browser-Sitzung nötig.
• Jede Nutzung setzt beim Key „zuletzt benutzt“. Änderungen per API-Key stehen im Audit-Log mit der Herkunft api:<Key-Name>. Mit dem optionalen Kopf X-Agent-Actor setzt du den Namen, der dort als Akteur erscheint.
• Läuft die Oberfläche mit dem selbstsignierten Zertifikat, nimm http:// im Heimnetz, lade das Zertifikat unter Einstellungen herunter und gib es curl mit --cacert mit – oder richte ein richtiges Zertifikat über die Zertifikatsverwaltung ein.

Fehlerformat

Fehler kommen als JSON mit einem Feld error, bei Eingabefehlern oft zusätzlich mit field:

{"error": "authentication required"}
{"error": "...", "field": "interval_seconds"}

Beispiele

Gesundheit, Status und Module

# Gesundheit, ohne Anmeldung: {"status":"ok","version":"…","time":"…"}
curl "$N64/api/health"

# Dashboard-Daten: Node, Module, Zusammenfassung je Modul, Verknüpfung
curl -H "Authorization: Bearer $N64_KEY" "$N64/api/status"

# Module mit Version und Zustand (name, version, enabled, running, last_error …)
curl -H "Authorization: Bearer $N64_KEY" "$N64/api/modules"

# dazu das Änderungsprotokoll je Modul, auf Deutsch
curl -H "Authorization: Bearer $N64_KEY" "$N64/api/modules?changelog=1&lang=de"

# Modul einschalten bzw. ausschalten
curl -X POST -H "Authorization: Bearer $N64_KEY" "$N64/api/modules/dns64/enable"
curl -X POST -H "Authorization: Bearer $N64_KEY" "$N64/api/modules/dns64/disable"

Checks auflisten

# alle Checks
curl -H "Authorization: Bearer $N64_KEY" "$N64/api/checks"

# gefiltert: nach Typ, Tag oder Suchbegriff
curl -H "Authorization: Bearer $N64_KEY" "$N64/api/checks?type=http"
curl -H "Authorization: Bearer $N64_KEY" "$N64/api/checks?tag=nas&q=backup"

# Statistik eines Checks für die letzten 24 Stunden
curl -H "Authorization: Bearer $N64_KEY" "$N64/api/checks/CHECK_TOKEN/stats?range=24h"

Jeder Check hat einen token mit 32 Zeichen, der als Kennung in allen weiteren Aufrufen dient.

Check anlegen

curl -X POST "$N64/api/checks" \
  -H "Authorization: Bearer $N64_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Webseite",
    "type": "http",
    "target": "https://example.com/",
    "interval_seconds": 60,
    "retries": 1,
    "stabilize": 3,
    "params": {"accept_status": "200-299"}
  }'

# sofort messen lassen (Antwort 202)
curl -X POST -H "Authorization: Bearer $N64_KEY" "$N64/api/checks/CHECK_TOKEN/run"

Pflicht sind name, type und – außer bei Push – target. Die Antwort (201) enthält den neuen Check samt token. Alle Felder und Standardwerte stehen in der Referenz /api/docs und unter Healthchecks.

Push-Check und Heartbeat

Bei einem Push-Check meldet sich dein Skript selbst – ideal für Backups und Cronjobs. Bleibt die Meldung länger als Periode plus Kulanz aus, gilt der Check als gestört.

# Push-Check anlegen: einmal am Tag, eine Stunde Kulanz
curl -X POST "$N64/api/checks" \
  -H "Authorization: Bearer $N64_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Nächtliches Backup", "type": "push",
       "params": {"period_seconds": 86400, "grace_seconds": 3600}}'
# die Antwort enthält "push_url"

# Heartbeat – ohne Anmeldung, als GET oder POST
curl -fsS -m 10 "$N64/api/push/CHECK_TOKEN"

# Störung melden, mit kurzer Nachricht (höchstens 200 Zeichen)
curl -fsS -m 10 "$N64/api/push/CHECK_TOKEN?status=down&msg=backup+failed"

# Ausgabe mitschicken (bis 4 KB, wird an der Messung gespeichert)
curl -fsS -m 10 --data-binary @backup.log "$N64/api/push/CHECK_TOKEN"

# typisch im Cronjob
/usr/local/bin/backup.sh \
  && curl -fsS -m 10 "$N64/api/push/CHECK_TOKEN" \
  || curl -fsS -m 10 "$N64/api/push/CHECK_TOKEN?status=down&msg=backup+failed"

• Mindestabstand 1 Sekunde, höchstens 60 Pushes pro Minute je Check.
• Für unbekannte Tokens kommt dieselbe Antwort – die URL verrät also nichts.
• Misst die Node den Check nicht allein, reicht sie den Push über ipv64 an die anderen messenden Nodes weiter. Ohne Verbindung zu ipv64 antwortet sie dann mit 503.

Zertifikat abrufen

Zertifikate aus der zentralen Verwaltung holst du per API auf andere Geräte – etwa per Cronjob auf NAS, Router oder Proxmox.

# Zertifikate auflisten (ohne Schlüssel) – hier steht die "id"
curl -H "Authorization: Bearer $N64_KEY" "$N64/api/certs"

# Zertifikat mit Kette und den privaten Schlüssel als einzelne Dateien
curl -fsS -H "Authorization: Bearer $N64_KEY" -o fullchain.pem \
  "$N64/api/certs/7/bundle?format=fullchain"
curl -fsS -H "Authorization: Bearer $N64_KEY" -o privkey.pem \
  "$N64/api/certs/7/bundle?format=key"

# alles als ZIP: fullchain.pem, cert.pem, chain.pem, privkey.pem
curl -fsS -H "Authorization: Bearer $N64_KEY" -o cert.zip "$N64/api/certs/7/bundle"

• Der Kopf ETag ist der Fingerabdruck des Zertifikats. Schickst du ihn mit If-None-Match zurück, antwortet Node64 mit 304, solange sich nichts geändert hat. X-Cert-Not-After nennt das Ablaufdatum.
• Abrufe mit privatem Schlüssel (key, pem, zip) stehen im Audit-Log.
• Für Windows, NAS und Router gibt es eine PKCS#12-Datei mit Passwort: POST /api/certs/{id}/p12 mit {"password": "…"}.

Statusseite anlegen und Ankündigung schreiben

Statusseiten verwaltest du über /api/status-pages – was sie können, steht unter Statusseiten. Ein Passwort setzt du mit "password" ("-" entfernt es). Ausgegeben wird es nie, nur has_password. "groups" nimmt die API weiter an: Die Einträge bestimmen Auswahl und Reihenfolge – auch die der Gruppen, nach erstem Auftreten –, "label" den Anzeigenamen; die Namen der groups werden ignoriert, angezeigt wird immer nach den Gruppen der Healthchecks. Neue Seiten haben "publish_node": true.

# Seite mit einer Gruppe anlegen – die Antwort enthält die "id"
curl -X POST -H "Authorization: Bearer $N64_KEY" -H "Content-Type: application/json" \
  "$N64/api/status-pages" -d '{
    "title": "Mein Homelab", "slug": "homelab", "enabled": true,
    "layout": "list", "days": 90, "show_uptime": true,
    "groups": [{"name": "Webseiten", "items": [
      {"token": "CHECK_TOKEN", "label": "Blog"}
    ]}]
  }'

# Ankündigung veröffentlichen (Stufe info, warning oder danger)
curl -X POST -H "Authorization: Bearer $N64_KEY" -H "Content-Type: application/json" \
  "$N64/api/status-pages/3/notices" \
  -d '{"title": "Wartung am Router", "level": "info", "text": "Heute ab 22 Uhr kurz offline."}'

# Update anhängen und als erledigt markieren
curl -X PUT -H "Authorization: Bearer $N64_KEY" -H "Content-Type: application/json" \
  "$N64/api/status-pages/3/notices/12" -d '{"text": "Erledigt, alles läuft.", "resolve": true}'

# Logo hochladen (PNG, JPEG, WebP oder SVG bis 256 KiB) bzw. entfernen
curl -X PUT -H "Authorization: Bearer $N64_KEY" -H "Content-Type: image/png" \
  --data-binary @logo.png "$N64/api/status-pages/3/logo"
curl -X DELETE -H "Authorization: Bearer $N64_KEY" "$N64/api/status-pages/3/logo"

Die öffentlichen Pfade der Seite (status.json, Badges, Feed) brauchen keinen API-Key – siehe status.json, Badges und Feed.

Prometheus-Metriken abrufen

Alle Kennzahlen von Node und Modulen im Prometheus-Textformat – mit demselben API-Key. Einrichtung in Prometheus und alle Metriknamen stehen unter Prometheus.

curl -s -H "Authorization: Bearer $N64_KEY" "$N64/api/metrics" | grep '^node64_' | head

Weitere Endpunkte

Die vollständige Liste steht in /api/docs. Eine Auswahl:

Die ipv64.net-API v2 – die Online-Schwester

Neben der lokalen API deiner Node gibt es die API v2 von ipv64.net. Sie ist eine eigene, separate API im Internet und gehört zu deinem ipv64.net-Account.

Node64 selbst nutzt die API v2 mit dem ipv64-API-Key aus den Einstellungen, zum Beispiel für DynDNS und Zertifikate – siehe Mit ipv64.net verknüpfen. Die beiden Keys sind nicht austauschbar.

Hinweise

• CSRF nur im Browser: Mit Browser-Sitzung brauchen POST, PUT und DELETE den Kopf X-CSRF-Token. Mit API-Key entfällt das.
• Begrenzung je IP: Zu viele Anfragen von einer Adresse beantwortet Node64 mit 429 und Retry-After: 10. Für Prometheus reicht ein Abfrageintervall von 15 bis 60 Sekunden.
• Mit ipv64 verknüpft: Alle Nodes eines Accounts bilden ein System. Checks, Wartungsfenster und Kanäle lassen sich von jeder Node aus ändern, auch wenn sie einer anderen Node gehören (owner: other).
• Nicht ins Internet stellen: Die API gehört ins Heimnetz. Für Zugriffe von außen nimm ein VPN oder einen abgesicherten Reverse-Proxy.

Etwas unklar, fehlt etwas oder hast du eine Frage zu Node64? Frag im offiziellen Forum v64.tech.