Alpha018/alpha-skills

NextDNS API

Übersicht

NextDNS stellt eine REST-API für alle konfigurierbaren Optionen seines Dashboards bereit: Profil-spezifische Sicherheits-/Privatsphäre-/Kindersicherungs-Schalter, Sperr-/Freigabelisten, Protokollierungseinstellungen, Analysen und rohe DNS-Abfragelogs. Es gibt kein offizielles SDK – alles basiert auf HTTPS + JSON, sodass dies natürlicherweise mit curl, Skripten oder HTTP-Clients in der jeweiligen Sprache oder dem Tool des Aufrufers genutzt wird.

• Basis-URL: https://api.nextdns.io
• Authentifizierung: Header X-Api-Key: <key> (Schlüssel unter https://my.nextdns.io/account)
• Alle Ressourcen sind auf ein Profil begrenzt: /profiles/:profile/...
• Erfolg: {"data": ..., "meta": {...}}. Fehler: {"errors": [{"code", "detail", "source"}]}

Was Sie mit dieser API erstellen können

Alles, was das NextDNS-Dashboard kann, ist hier erreichbar, was mehrere wiederkehrende Aufgabenkategorien eröffnet:

• Provisionierung/Konfiguration-als-Code – Erstellen eines Profils und Übertragen seiner vollständigen Sicherheits-/Privatsphäre-/Kindersicherungs-/Einstellungen-Konfiguration aus einer JSON/YAML-Datei, sodass ein DNS-Profil versioniert und reproduziert werden kann, anstatt von Hand zusammengeklickt zu werden.
• Bulk-Listenverwaltung – Synchronisieren einer Sperr- oder Freigabeliste aus einer externen Quelle (eine gepflegte Blocklist, eine CSV, ein Export eines anderen Systems) über die PUT-Endpunkte für vollständigen Ersatz oder die POST/PATCH/DELETE-Endpunkte pro Eintrag.
• Geplante/bedingte Umschaltungen – Einstellungen nach Zeitplan oder Auslöser umschalten, z.B. strengere parentalControl-Kategorien während bestimmter Stunden aktivieren oder settings.web3/security.*-Flags basierend auf externen Ereignissen umschalten.
• Überwachung und Benachrichtigungen – analytics/* (Status, Top-blockierte Domains/ Geräte, Gründe) abfragen, um Dashboards oder Benachrichtigungen zu erstellen, z.B. benachrichtigen, wenn das Volumen blockierter Abfragen ansteigt oder ein neues Gerät Traffic erzeugt. Die ;series-Zeitreihenvarianten machen dies diagrammfreundlich.
• Log-Tailing und Export – /logs/stream (SSE) für einen Live-Abfrage-Tail im Terminal oder in einer Log-Pipeline, oder /logs/download, um einen vollständigen Export für die Offline-Analyse/Archivierung zu ziehen.
• Audit-/Compliance-Prüfungen – Periodisch die vollständige Konfiguration eines Profils abrufen (GET) und mit einer erwarteten Basislinie vergleichen, um Abweichungen zu erkennen (z.B. einen Sicherheitsschalter, den jemand im Dashboard ausgeschaltet hat).
• Multi-Profil-Flotten – Dieselben Operationen für viele :profile-IDs, für alle, die NextDNS für mehrere Netzwerke/Haushalte/Standorte von einem Ort aus verwalten.

Wann verwenden

• Lesen oder Schreiben von Sperr-/Freigabelisteneinträgen, Sicherheits-/Privatsphäre-Schaltern, Kindersicherungsdiensten/-kategorien oder profilweiten Einstellungen.
• Abrufen von Analysen (Top-Domains, Geräte, Protokolle, Blockiergründe, Geo) oder rohen/gestreamten Abfragelogs, einschließlich Zeitreihenaufschlüsselungen.
• Erstellen oder Debuggen von Skripten/Automatisierungen, die mit api.nextdns.io kommunizieren – curl, ein Konfigurationsmanagement-Tool, ein Cron-Job, ein Dashboard, ein Chat-/CLI-Bot.
• Überprüfen, ob die im Skill gebündelte Referenz noch korrekt mit den aktuellen Live-Dokumenten übereinstimmt, bevor Sie sich für etwas Wichtiges darauf verlassen.

Kurzreferenz

Bereich	Basispfad	Wichtige Operationen
Profil	/profiles/:profile	GET, PATCH (partiell), DELETE; POST /profiles zum Erstellen
Sicherheit	/profiles/:profile/security	Schalter + tlds-Liste
Privatsphäre	/profiles/:profile/privacy	blocklists, natives, Schalter
Kindersicherung	/profiles/:profile/parentalControl	services, categories (unterstützen PUT vollständiger Ersatz), Safe-Search-Schalter
Sperrliste / Freigabeliste	/profiles/:profile/denylist | /allowlist	GET/PUT/POST/PATCH/DELETE, Einträge {id, active}
Einstellungen	/profiles/:profile/settings	logs, blockPage, performance, web3
Analysen	/profiles/:profile/analytics/<dim>	Status, Domains, Gründe, IPs, Geräte, Protokolle, Abfragetypen, IP-Versionen, DNSSEC, Verschlüsselung, Ziele; ;series für Zeitabschnitte anhängen
Logs	/profiles/:profile/logs	Liste, /stream (SSE), /download, DELETE zum Löschen

Vollständige Parametertabellen, jedes JSON-Schema und jede Beispielantwort finden Sie in references/api-reference.md – lesen Sie diese, bevor Sie einen nicht-trivialen Aufruf (alles über einen einzelnen GET hinaus) schreiben, damit Feldnamen, Enums und Standardwerte beim ersten Versuch stimmen, anstatt zu raten und gegen die Live-API hin- und herzurunden.

Eine maschinenlesbare references/openapi.yaml (OpenAPI 3.0, mit Antwortbeispielen aus api-reference.md) bildet dieselben Endpunkte ab – verwenden Sie sie, wenn Sie einen Client generieren, sie einem Code-Generator zuführen oder eine strukturierte Vergleichsfläche benötigen. Für eine menschenlesbare Version öffnen Sie references/openapi.html (eine statische Redoc-Seite, die aus der Spezifikation generiert wurde – nach Tags gruppiert, durchsuchbar, mit den Beispielen inline) anstatt das rohe YAML zu lesen.

Häufige Muster

curl-Beispiel (Sperrliste auflisten):

curl -sH "X-Api-Key: $NEXTDNS_API_KEY" \
  "https://api.nextdns.io/profiles/$PROFILE_ID/denylist"

Eine Domain zur Sperrliste hinzufügen:

curl -sH "X-Api-Key: $NEXTDNS_API_KEY" -H "Content-Type: application/json" \
  -X POST "https://api.nextdns.io/profiles/$PROFILE_ID/denylist" \
  -d '{"id": "badsite.com", "active": true}'

Einen Sicherheitsschalter umschalten:

curl -sH "X-Api-Key: $NEXTDNS_API_KEY" -H "Content-Type: application/json" \
  -X PATCH "https://api.nextdns.io/profiles/$PROFILE_ID/security" \
  -d '{"cryptojacking": true}'

Bevorzugen Sie PATCH auf einer eingeschränkten Sub-Ressource (z.B. /security, /settings/logs) gegenüber PATCH auf dem gesamten Profil, wenn nur ein Bereich geändert wird – es ist schwieriger, versehentlich nicht zusammenhängende Felder zu überschreiben.

Für Paginierung (analytics/*, logs): Entnehmen Sie meta.pagination.cursor aus der Antwort und übergeben Sie ihn als ?cursor=... bei der nächsten Anfrage; ein null/fehlender Cursor bedeutet die letzte Seite. Vollständige Datumsformat- und Zeitreihenregeln (;series, interval, alignment, timezone) finden Sie in references/api-reference.md#time-series.

Aktualität der Referenz halten

Es gibt keine upstream OpenAPI-Datei, mit der abgeglichen werden kann – NextDNS' Dokumentation unter https://nextdns.github.io/api/ ist handgeschriebenes HTML. Wenn Sie aufgefordert werden, nach API-Updates zu suchen, oder bevor Sie sich für etwas Wichtiges auf diesen Skill verlassen, rufen Sie diese Seite ab und vergleichen Sie sie mit references/api-reference.md und references/openapi.yaml; aktualisieren Sie beide gleichzeitig, falls etwas abweicht (neue Analyse-Dimensionen und neue Einstellungen/Sicherheits-/Privatsphäre-Schalter sind die Felder, die sich in der Vergangenheit geändert haben). Siehe den Abschnitt "Aktualität bewahren" am Ende von references/api-reference.md für das vollständige Verfahren.

Nachdem Sie references/openapi.yaml bearbeitet haben, führen Sie scripts/render-docs.sh aus – es prüft die Spezifikation (fängt YAML/Schema-Fehler ab, bevor sie den Leser erreichen) und generiert references/openapi.html daraus neu. Comitten Sie die neu generierte HTML-Datei zusammen mit der YAML-Änderung, sodass beide nie auseinanderdriften.