NextDNS API
概述
NextDNS 通过 REST API 公开了仪表板中所有可配置的功能： 每个配置文件的 安全/隐私/家长控制 开关、阻止/允许 列表、 日志记录设置、分析数据和原始 DNS 查询日志。没有官方 SDK —— 一切都基于纯 HTTPS + JSON，因此自然适用于 curl/脚本/ HTTP 客户端，无论调用者使用哪种语言或工具。
- 基础 URL：
https://api.nextdns.io - 认证：请求头
X-Api-Key: <key>（密钥在 https://my.nextdns.io/account） - 所有资源都在配置文件范围内：
/profiles/:profile/... - 成功响应：
{"data": ..., "meta": {...}}。错误响应：{"errors": [{"code", "detail", "source"}]}
你可以用这个 API 构建什么
NextDNS 仪表板能做的所有事情都可以通过这里实现，这开启了几类常见的任务：
- 配置即代码 —— 创建一个配置文件并将其完整的 安全/隐私/家长控制/设置 配置从 JSON/YAML 文件推送， 使 DNS 配置文件可以版本控制和复现，而不是手动点击配置。
- 批量列表管理 —— 通过
PUT全量替换或逐条POST/PATCH/DELETE端点， 将阻止列表或允许列表与外部来源（维护的块列表、CSV、其他系统的导出）同步。 - 按计划/条件切换 —— 按计划或触发条件翻转设置，例如在特定时段
启用更严格的
parentalControl类别，或根据外部事件切换settings.web3/security.*标志。 - 监控和告警 —— 轮询
analytics/*（状态、被阻止的顶级域名/设备、原因）以构建 仪表板或告警，例如当阻止查询量激增或新设备开始产生流量时发送通知。;series时间序列变体使其对图表生成友好。 - 日志尾随和导出 —— 使用
/logs/stream（SSE）在终端或日志管道中实时跟踪查询， 或/logs/download拉取完整导出以供离线分析/存档。 - 审计/合规检查 —— 定期 GET 配置文件的完整配置并与预期基线对比差异 以捕获漂移（例如有人在仪表板中关闭了某个安全开关）。
- 多配置文件集群 —— 对许多
:profileID 执行相同操作， 适合从一处同时管理多个网络/家庭/站点的 NextDNS。
何时使用
- 读取或写入阻止/允许列表条目、安全/隐私开关、家长控制服务/类别或配置文件范围的设置。
- 拉取分析数据（顶级域名、设备、协议、阻止原因、地理位置）或原始/流式查询日志，包括时间序列细分。
- 构建或调试任何与
api.nextdns.io通信的脚本/自动化工具 —— curl、配置管理工具、cron 任务、仪表板、聊天/CLI 机器人。 - 在对某个重要功能依赖此技能之前，验证此技能捆绑的参考文档与实时文档仍然一致。
快速参考
| 区域 | 基础路径 | 主要操作 |
|---|---|---|
| 配置文件 | /profiles/:profile | GET、PATCH（部分更新）、DELETE；POST /profiles 创建 |
| 安全 | /profiles/:profile/security | 开关 + tlds 列表 |
| 隐私 | /profiles/:profile/privacy | blocklists、natives、开关 |
| 家长控制 | /profiles/:profile/parentalControl | services、categories（支持 PUT 全量替换）、安全搜索开关 |
| 阻止列表 / 允许列表 | /profiles/:profile/denylist | /allowlist | GET/PUT/POST/PATCH/DELETE，条目 {id, active} |
| 设置 | /profiles/:profile/settings | logs、blockPage、performance、web3 |
| 分析 | /profiles/:profile/analytics/<dim> | status、domains、reasons、ips、devices、protocols、queryTypes、ipVersions、dnssec、encryption、destinations；追加 ;series 以获取时间桶 |
| 日志 | /profiles/:profile/logs | 列表、/stream（SSE）、/download、DELETE 清除 |
完整的参数表、每个 JSON 模式以及每个示例响应都在 references/api-reference.md 中——在编写任何非平凡调用（任何超出单个 GET 的操作）之前请先阅读它，以便正确获取字段名称、枚举和默认值，而不是猜测并反复与实时 API 来回验证。
机器可读的 references/openapi.yaml（OpenAPI 3.0，包含从 api-reference.md 移植的响应示例）提供了相同的端点——如果你正在生成客户端、将其提供给代码生成工具或想要一个结构化的差异比较表面，请使用它。对于人类可浏览的版本，打开 references/openapi.html（一个预渲染的静态 Redoc 页面，来源于规范——按标签分组、可搜索、内嵌示例）而不是读取原始的 YAML。
常见模式
curl 示例（列出阻止列表）：
curl -sH "X-Api-Key: $NEXTDNS_API_KEY" \
"https://api.nextdns.io/profiles/$PROFILE_ID/denylist"
将一个域名添加到阻止列表：
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}'
切换一个安全设置：
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}'
当只更改一个区域时，优先在作用域子资源（例如 /security、/settings/logs）上使用 PATCH 而不是对整个配置文件使用 PATCH——这样更难意外地覆盖无关字段。
对于分页（analytics/*、logs），从响应中拉取 meta.pagination.cursor 并将其作为 ?cursor=... 传递到下一个请求；null/缺失的光标表示最后一页。完整的日期格式和时间序列（;series、interval、alignment、timezone）规则在 references/api-reference.md#time-series 中。
保持参考文档的更新
没有官方的上游 OpenAPI 文件可以对比——NextDNS 在 https://nextdns.github.io/api/ 的文档是手写的 HTML。如果需要检查 API 更新，或者在高风险任务中依赖此技能之前，请获取该页面并与 references/api-reference.md 和 references/openapi.yaml 进行比较；如果发现任何漂移，同时更新两者（历史上，新的分析维度和新的设置/安全/隐私开关是发生变化的部分）。有关完整流程，请参见 references/api-reference.md 底部的“保持更新”部分。
编辑 references/openapi.yaml 后，运行 scripts/render-docs.sh——它会检查规范（在 YAML/模式错误到达读者之前捕获它们）并根据规范重新生成 references/openapi.html。将重新生成的 HTML 与 YAML 编辑一起提交，以确保两者不会不同步。