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}'
プロファイル全体に対して PATCH するよりも、スコープされたサブリソース（例: /security、/settings/logs）に 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 を再生成します。YAML 編集と一緒に再生成された HTML をコミットして、二つが乖離しないようにしてください。