Alpha018/alpha-skills

API de NextDNS

Resumen

NextDNS expone una API REST para todo lo configurable en su panel de control: conmutadores de seguridad/privacidad/control parental por perfil, listas de denegación/permitidos, ajustes de registro, analíticas y registros de consultas DNS sin procesar. No existe un SDK oficial — todo es HTTPS + JSON plano, por lo que esto es territorio natural de curl/script/cliente HTTP en cualquier lenguaje o herramienta que esté utilizando el llamante.

• URL base: https://api.nextdns.io
• Autenticación: cabecera X-Api-Key: <clave> (clave en https://my.nextdns.io/account)
• Todos los recursos están limitados a un perfil: /profiles/:profile/...
• Éxito: {"data": ..., "meta": {...}}. Errores: {"errors": [{"code", "detail", "source"}]}

Qué puedes construir con esta API

Todo lo que el panel de control de NextDNS puede hacer es accesible aquí, lo que abre algunas categorías recurrentes de tareas:

• Aprovisionamiento/configuración como código — crea un perfil y envía su configuración completa de seguridad/privacidad/controlParental/ajustes desde un archivo JSON/YAML, de modo que un perfil DNS pueda tener control de versiones y reproducirse en lugar de configurarse manualmente.
• Gestión masiva de listas — sincroniza una lista de denegación o permitidos desde una fuente externa (una lista de bloqueo mantenida, un CSV, la exportación de otro sistema) a través de los endpoints PUT de reemplazo completo o POST/PATCH/DELETE por entrada.
• Conmutaciones programadas/condicionales — activa o desactiva ajustes según un horario o desencadenante, por ejemplo, habilitar categorías de parentalControl más estrictas durante ciertas horas, o alternar indicadores de settings.web3/security.* basados en eventos externos.
• Monitoreo y alertas — consulta analytics/* (estado, dominios/dispositivos bloqueados principales, razones) para construir paneles o alertas, por ejemplo, notificar cuando el volumen de consultas bloqueadas aumenta o un nuevo dispositivo comienza a generar tráfico. Las variantes de series temporales ;series facilitan la representación gráfica.
• Seguimiento y exportación de registros — usa /logs/stream (SSE) para una cola de consultas en vivo en un terminal o canalización de registros, o /logs/download para extraer una exportación completa para análisis/archivado sin conexión.
• Auditorías/verificaciones de cumplimiento — periódicamente haz GET de la configuración completa de un perfil y compárala con una línea base esperada para detectar desviaciones (por ejemplo, un conmutador de seguridad que alguien desactivó en el panel de control).
• Flotas multiperfil — las mismas operaciones contra muchos ID de :profile, para cualquier persona que gestione NextDNS para varias redes/hogares/sitios desde un solo lugar.

Cuándo usar

• Leer o escribir entradas de listas de denegación/permitidos, conmutadores de seguridad/privacidad, servicios/categorías de control parental o ajustes de todo el perfil.
• Extraer analíticas (dominios principales, dispositivos, protocolos, razones de bloqueo, geo) o registros de consultas sin procesar/transmitidos, incluyendo desgloses de series temporales.
• Construir o depurar cualquier script/automatización que hable con api.nextdns.io: curl, una herramienta de gestión de configuración, un trabajo cron, un panel, un bot de chat/CLI.
• Verificar que la referencia incluida en esta habilidad sigue siendo precisa según la documentación en vivo antes de confiar en ella para algo importante.

Referencia rápida

Área	Ruta base	Operaciones clave
Perfil	/profiles/:profile	GET, PATCH (parcial), DELETE; POST /profiles para crear
Seguridad	/profiles/:profile/security	conmutadores + lista de tlds
Privacidad	/profiles/:profile/privacy	blocklists, natives, conmutadores
Control Parental	/profiles/:profile/parentalControl	services, categories (admite PUT de reemplazo completo), conmutadores de búsqueda segura
Lista de denegación / Permitidos	/profiles/:profile/denylist | /allowlist	GET/PUT/POST/PATCH/DELETE, entradas {id, active}
Ajustes	/profiles/:profile/settings	logs, blockPage, performance, web3
Analíticas	/profiles/:profile/analytics/<dimensión>	estado, dominios, razones, ips, dispositivos, protocolos, tiposDe Consulta, ipVersions, dnssec, encryption, destinations; agrega ;series para intervalos de tiempo
Registros	/profiles/:profile/logs	listar, /stream (SSE), /download, DELETE para limpiar

Las tablas de parámetros completas, cada esquema JSON y cada respuesta de ejemplo están en references/api-reference.md — léelo antes de escribir cualquier llamada no trivial (cualquier cosa más allá de un solo GET) para acertar con los nombres de campos, enumeraciones y valores predeterminados en el primer intento, en lugar de adivinar y hacer viajes de ida y vuelta contra la API en vivo.

Un archivo references/openapi.yaml legible por máquina (OpenAPI 3.0, con ejemplos de respuesta extraídos de api-reference.md) refleja los mismos endpoints — úsalo si estás generando un cliente, alimentándolo a una herramienta de generación de código o deseas una superficie de diff estructurada. Para una versión navegable por humanos, abre references/openapi.html (una página Redoc estática prerenderizada a partir de la especificación — agrupada por etiqueta, con búsqueda y los ejemplos en línea) en lugar de leer el YAML sin procesar.

Patrones comunes

Ejemplo con curl (listar lista de denegación):

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

Añadir un dominio a la lista de denegación:

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

Activar un ajuste de seguridad:

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

Prefiere PATCH en un sub-recurso limitado (por ejemplo, /security, /settings/logs) sobre PATCH en todo el perfil cuando solo cambia un área; es más difícil sobrescribir accidentalmente campos no relacionados.

Para paginación (analytics/*, logs), extrae meta.pagination.cursor de la respuesta y pásalo de vuelta como ?cursor=... en la siguiente solicitud; un cursor null/ausente significa la última página. Las reglas completas de formato de fecha y series temporales (;series, interval, alignment, timezone) están en references/api-reference.md#time-series.

Manteniendo la referencia actualizada

No hay un archivo OpenAPI ascendente con el que comparar — la documentación de NextDNS en https://nextdns.github.io/api/ es HTML escrito a mano. Si se te pide verificar actualizaciones de la API, o antes de depender de esta habilidad para algo de alto riesgo, obtén esa página y compárala con references/api-reference.md y references/openapi.yaml; actualiza ambos si algo ha cambiado (las nuevas dimensiones de analíticas y los nuevos conmutadores de ajustes/seguridad/privacidad son los campos que han cambiado históricamente). Consulta la sección "Manteniendo esto actualizado" al final de references/api-reference.md para el procedimiento completo.

Después de editar references/openapi.yaml, ejecuta scripts/render-docs.sh — que verifica la especificación (detecta errores de YAML/esquema antes de que lleguen al lector) y regenera references/openapi.html a partir de ella. Confirma el HTML regenerado junto con la edición YAML para que nunca diverjan.