Alpha018/alpha-skills

API NextDNS

Visão Geral

O NextDNS expõe uma API REST para tudo que é configurável em seu painel: alternâncias de segurança/privacidade/controle parental por perfil, listas de negação/permissão, configurações de registro, análises e logs brutos de consultas DNS. Não existe SDK oficial — tudo é HTTPS + JSON puro, portanto é naturalmente território de curl/script/ cliente HTTP, independentemente da linguagem ou ferramenta que o chamador estiver usando.

• URL Base: https://api.nextdns.io
• Autenticação: cabeçalho X-Api-Key: <chave> (chave em https://my.nextdns.io/account)
• Todos os recursos são escopados sob um perfil: /profiles/:profile/...
• Sucesso: {"data": ..., "meta": {...}}. Erros: {"errors": [{"code", "detail", "source"}]}

O que você pode construir com esta API

Tudo que o painel do NextDNS pode fazer é acessível aqui, o que abre algumas categorias recorrentes de tarefas:

• Provisionamento/configuração como código — criar um perfil e aplicar sua configuração completa de segurança/privacidade/controle parental a partir de um arquivo JSON/YAML, para que um perfil DNS possa ser versionado e reproduzido em vez de configurado manualmente.
• Gerenciamento em lote de listas — sincronizar uma lista de negação ou permissão a partir de uma fonte externa (uma lista de bloqueio mantida, um CSV, uma exportação de outro sistema) usando os endpoints PUT (substituição completa) ou POST/PATCH/DELETE por entrada.
• Alternâncias programadas/condicionais — alterar configurações em um cronograma ou gatilho, por exemplo, ativar categorias mais rigorosas de parentalControl durante certos horários, ou alternar flags settings.web3/security.* com base em eventos externos.
• Monitoramento e alertas — consultar analytics/* (status, principais domínios/dispositivos bloqueados, motivos) para construir painéis ou alertas, por exemplo, notificar quando o volume de consultas bloqueadas aumentar ou um novo dispositivo começar a gerar tráfego. As variantes de série temporal ;series tornam isso amigável para gráficos.
• Visualização e exportação de registros — usar /logs/stream (SSE) para um acompanhamento ao vivo de consultas em um terminal ou pipeline de logs, ou /logs/download para baixar uma exportação completa para análise/arquivamento offline.
• Auditoria/verificações de conformidade — periodicamente obter a configuração completa de um perfil via GET e compará-la com uma linha de base esperada para detectar desvios (por exemplo, uma alternativa de segurança que alguém desativou no painel).
• Frotas de múltiplos perfis — as mesmas operações para vários IDs :profile, para quem gerencia NextDNS para várias redes/residências/sites a partir de um único lugar.

Quando usar

• Ler ou escrever entradas de listas de negação/permissão, alternâncias de segurança/privacidade, serviços/categorias de controle parental ou configurações globais do perfil.
• Obter análises (principais domínios, dispositivos, protocolos, motivos de bloqueio, geografia) ou logs de consulta brutos/transmitidos, incluindo detalhamentos de série temporal.
• Construir ou depurar qualquer script/automação que se comunique com api.nextdns.io — curl, uma ferramenta de gerenciamento de configuração, uma tarefa cron, um painel, um chatbot/CLI.
• Verificar se a referência fornecida nesta skill ainda está precisa em relação à documentação ativa antes de depender dela para algo importante.

Referência rápida

Área	Caminho base	Operações principais
Perfil	/profiles/:profile	GET, PATCH (parcial), DELETE; POST /profiles para criar
Segurança	/profiles/:profile/security	alternâncias + lista tlds
Privacidade	/profiles/:profile/privacy	blocklists, natives, alternâncias
Controle Parental	/profiles/:profile/parentalControl	services, categories (suportam PUT substituição completa), alternâncias de pesquisa segura
Lista de Negação / Permissão	/profiles/:profile/denylist | /allowlist	GET/PUT/POST/PATCH/DELETE, entradas {id, active}
Configurações	/profiles/:profile/settings	logs, blockPage, performance, web3
Análises	/profiles/:profile/analytics/<dim>	status, domains, reasons, ips, devices, protocols, queryTypes, ipVersions, dnssec, encryption, destinations; anexe ;series para buckets de tempo
Logs	/profiles/:profile/logs	list, /stream (SSE), /download, DELETE para limpar

Tabelas de parâmetros completas, todos os esquemas JSON e cada resposta de exemplo estão em references/api-reference.md — leia-o antes de escrever qualquer chamada não trivial (qualquer coisa além de um único GET) para acertar nomes de campos, enumerações e valores padrão na primeira tentativa, em vez de adivinhar e fazer tentativas contra a API ativa.

Um arquivo references/openapi.yaml legível por máquina (OpenAPI 3.0, com exemplos de resposta copiados de api-reference.md) espelha os mesmos endpoints — use-o se estiver gerando um cliente, alimentando-o em uma ferramenta de geração de código ou quiser uma superfície de diff estruturada. Para uma versão navegável por humanos, abra references/openapi.html (uma página Redoc estática pré-renderizada a partir da especificação — agrupada por tag, pesquisável, com os exemplos embutidos) em vez de ler o YAML bruto.

Padrões comuns

Exemplo com curl (listar lista de negação):

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

Adicionar um domínio à lista de negação:

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

Alternar uma configuração de segurança:

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

Prefira PATCH em um sub-recurso com escopo (por exemplo, /security, /settings/logs) em vez de PATCH em todo o perfil quando apenas uma área estiver mudando — é mais difícil sobrescrever acidentalmente campos não relacionados.

Para paginação (analytics/*, logs), extraia meta.pagination.cursor da resposta e passe-o de volta como ?cursor=... na próxima solicitação; um cursor null/ausente significa a última página. Regras completas de formato de data e série temporal (;series, interval, alignment, timezone) estão em references/api-reference.md#time-series.

Mantendo a referência atualizada

Não existe um arquivo OpenAPI upstream para comparar — a documentação do NextDNS em https://nextdns.github.io/api/ é HTML escrito à mão. Se for solicitado a verificar se há atualizações na API, ou antes de depender desta skill para algo de alto risco, obtenha essa página e compare-a com references/api-reference.md e references/openapi.yaml; atualize ambos juntos se algo tiver mudado (novas dimensões de análise e novas alternâncias de configuração/segurança/privacidade são os campos que mudaram historicamente). Consulte a seção "Mantendo isso atualizado" no final de references/api-reference.md para o procedimento completo.

Após editar references/openapi.yaml, execute scripts/render-docs.sh — ele verifica a sintaxe da especificação (identifica erros de YAML/esquema antes que cheguem ao leitor) e regenera references/openapi.html a partir dela. Faça commit do HTML regenerado junto com a edição do YAML para que os dois nunca se desalinhem.