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、其他系統的匯出）同步封鎖清單或允許清單。 - 排程/條件切換 —— 根據排程或觸發條件切換設定，例如在特定時段啟用更嚴格的家長監護類別，或根據外部事件切換
settings.web3/security.*旗標。 - 監控與警示 —— 輪詢
analytics/*（狀態、最多被封鎖的網域/裝置、原因）以建立儀表板或警示，例如在封鎖查詢量激增或新裝置開始產生流量時發出通知。;series時間序列變體讓這類操作更利於圖表化。 - 記錄即時串流與匯出 —— 使用
/logs/stream（SSE）在終端機或記錄管線中即時查看查詢串流，或使用/logs/download拉取完整匯出以進行離線分析/歸檔。 - 稽核/合規檢查 —— 定期 GET 設定檔的完整配置並與預期基準進行差異比較，以發現偏移（例如有人在儀表板中關閉了某個安全開關）。
- 多設定檔群組管理 —— 對多個
:profileID 執行相同操作，適合從單一位置管理多個網路/家庭/站點的 NextDNS。
何時使用
- 讀取或寫入封鎖清單/允許清單項目、安全性/隱私開關、家長監護服務/類別或設定檔範圍的設定。
- 拉取分析資料（熱門網域、裝置、協議、封鎖原因、地理位置）或原始/即時串流查詢記錄，包括時間序列細分。
- 建立或除錯任何與
https://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 | list, /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 編輯一起提交，確保兩者永遠不會不同步。