Alpha018/alpha-skills

API NextDNS

Présentation

NextDNS expose une API REST pour tout ce qui est configurable dans son tableau de bord : bascules de sécurité/confidentialité/contrôle parental par profil, listes de refus/d'autorisation, paramètres de journalisation, analytiques et journaux bruts de requêtes DNS. Il n'existe pas de SDK officiel — tout est en HTTPS + JSON brut, ce qui en fait un domaine naturel pour curl/script/ client HTTP, quel que soit le langage ou l'outil utilisé par l'appelant.

• URL de base : https://api.nextdns.io
• Authentification : en-tête X-Api-Key : <clé> (clé sur https://my.nextdns.io/account)
• Toutes les ressources sont limitées à un profil : /profiles/:profile/...
• Succès : {"data": ..., "meta": {...}}. Erreurs : {"errors": [{"code", "detail", "source"}]}

Ce que vous pouvez construire avec cette API

Tout ce que le tableau de bord NextDNS peut faire est accessible ici, ce qui ouvre quelques catégories récurrentes de tâches :

• Provisionnement/configuration en tant que code — créer un profil et pousser sa configuration complète de sécurité/confidentialité/contrôle parental/paramètres à partir d'un fichier JSON/YAML, afin qu'un profil DNS puisse être versionné et reproduit plutôt que d'être configuré manuellement.
• Gestion en masse des listes — synchroniser une liste de refus ou d'autorisation à partir d'une source externe (une liste de blocage maintenue, un CSV, une exportation d'un autre système) via les points de terminaison PUT (remplacement complet) ou POST/PATCH/DELETE par entrée.
• Basculements planifiés/conditionnels — inverser des paramètres selon un planning ou un déclencheur, par exemple activer des catégories parentalControl plus strictes à certaines heures, ou basculer les indicateurs settings.web3/security.* en fonction d'événements externes.
• Surveillance et alertes — interroger analytics/* (statut, principaux domaines/appareils bloqués, raisons) pour créer des tableaux de bord ou des alertes, par exemple être notifié en cas de pic de volume de requêtes bloquées ou lorsqu'un nouvel appareil commence à générer du trafic. Les variantes de séries temporelles ;series les rendent adaptées aux graphiques.
• Suivi et exportation des journaux — utiliser /logs/stream (SSE) pour un suivi en direct des requêtes dans un terminal ou un pipeline de journaux, ou /logs/download pour extraire une exportation complète pour une analyse/archivage hors ligne.
• Audit/vérifications de conformité — obtenir périodiquement la configuration complète d'un profil et la comparer à une base de référence attendue pour détecter les écarts (par exemple, une bascule de sécurité désactivée dans le tableau de bord).
• Flottes multi-profils — les mêmes opérations sur de nombreux identifiants :profile, pour toute personne gérant NextDNS pour plusieurs réseaux/foyers/sites depuis un seul endroit.

Quand l'utiliser

• Lecture ou écriture d'entrées de listes de refus/d'autorisation, bascules de sécurité/ confidentialité, services/catégories de contrôle parental, ou paramètres de profil.
• Récupération d'analytiques (principaux domaines, appareils, protocoles, raisons de blocage, géolocalisation) ou de journaux bruts/streamés de requêtes, y compris les ventilations temporelles.
• Création ou débogage de tout script/automatisation qui communique avec api.nextdns.io — curl, un outil de gestion de configuration, une tâche cron, un tableau de bord, un robot de chat/CLI.
• Vérification que la référence incluse dans cette compétence est toujours exacte par rapport à la documentation en direct avant de s'y fier pour quelque chose d'important.

Référence rapide

Zone	Chemin de base	Opérations clés
Profil	/profiles/:profile	GET, PATCH (partiel), DELETE ; POST /profiles pour créer
Sécurité	/profiles/:profile/security	bascules + liste tlds
Confidentialité	/profiles/:profile/privacy	blocklists, natives, bascules
Contrôle parental	/profiles/:profile/parentalControl	services, categories (prend en charge PUT remplacement complet), bascules de recherche sécurisée
Liste de refus / d'autorisation	/profiles/:profile/denylist | /allowlist	GET/PUT/POST/PATCH/DELETE, entrées {id, active}
Paramètres	/profiles/:profile/settings	logs, blockPage, performance, web3
Analytiques	/profiles/:profile/analytics/<dim>	statut, domaines, raisons, ips, appareils, protocoles, typesDeRequête, versionsIp, dnssec, chiffrement, destinations ; ajouter ;series pour des intervalles temporels
Journaux	/profiles/:profile/logs	liste, /stream (SSE), /download, DELETE pour effacer

Les tableaux de paramètres complets, tous les schémas JSON et tous les exemples de réponses se trouvent dans references/api-reference.md — lisez-le avant d'écrire tout appel non trivial (tout ce qui dépasse un simple GET) pour obtenir les noms de champs, les énumérations et les valeurs par défaut correctes du premier coup, plutôt que de deviner et de faire des allers-retours avec l'API en direct.

Un fichier references/openapi.yaml lisible par machine (OpenAPI 3.0, avec des exemples de réponses repris de api-reference.md) reflète les mêmes points de terminaison — utilisez-le si vous générez un client, l'alimentez dans un outil de génération de code, ou souhaitez une surface de comparaison structurée. Pour une version consultable par un humain, ouvrez references/openapi.html (une page Redoc statique pré-rendue à partir de la spécification — regroupée par étiquette, consultable, avec les exemples intégrés) au lieu de lire le YAML brut.

Modèles courants

Exemple curl (lister la liste de refus) :

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

Ajouter un domaine à la liste de refus :

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}'

Basculer un paramètre de sécurité :

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}'

Privilégiez PATCH sur une sous-ressource ciblée (par exemple, /security, /settings/logs) plutôt que PATCH sur l'ensemble du profil lorsqu'une seule zone est modifiée — il est plus difficile d'écraser accidentellement des champs non liés.

Pour la pagination (analytics/*, logs), récupérez meta.pagination.cursor dans la réponse et renvoyez-le comme ?cursor=... dans la requête suivante ; un curseur null/absent signifie la dernière page. Les règles complètes de format de date et de série temporelle (;series, interval, alignment, timezone) se trouvent dans references/api-reference.md#time-series.

Maintenir la référence à jour

Il n'existe pas de fichier OpenAPI amont pour effectuer une comparaison — la documentation de NextDNS à l'adresse https://nextdns.github.io/api/ est du HTML écrit à la main. Si l'on vous demande de vérifier les mises à jour de l'API, ou avant de dépendre de cette compétence pour quelque chose d'important, récupérez cette page et comparez-la avec references/api-reference.md et references/openapi.yaml ; mettez les deux à jour ensemble si quelque chose a dérivé (les nouvelles dimensions analytiques et les nouvelles bascules de paramètres/sécurité/confidentialité sont les champs qui ont historiquement changé). Consultez la section "Maintenir ceci à jour" en bas de references/api-reference.md pour la procédure complète.

Après avoir modifié references/openapi.yaml, exécutez scripts/render-docs.sh — il valide la spécification (détecte les erreurs YAML/schéma avant qu'elles n'atteignent le lecteur) et régénère references/openapi.html à partir de celle-ci. Validez le HTML régénéré avec la modification YAML afin que les deux ne dérivent jamais l'un de l'autre.