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 프로필을 수동으로 클릭하지 않고 버전 관리 및 재현할 수 있습니다.
- 대량 목록 관리 — 외부 소스(유지 관리되는 블록리스트, CSV, 다른 시스템의 내보내기)에서
거부 목록 또는 허용 목록을
PUT전체 교체 또는 엔트리별POST/PATCH/DELETE엔드포인트를 통해 동기화합니다. - 예약/조건부 토글 — 설정을 일정 또는 트리거에 따라 전환합니다. 예를 들어 특정 시간 동안
더 엄격한
parentalControl카테고리를 활성화하거나 외부 이벤트에 따라settings.web3/security.*플래그를 전환합니다. - 모니터링 및 알림 —
analytics/*(상태, 상위 차단 도메인/디바이스, 이유)를 폴링하여 대시보드 또는 알림을 구축합니다. 예를 들어 차단 쿼리 볼륨이 급증하거나 새 디바이스가 트래픽을 생성하기 시작할 때 알림을 보냅니다.;series시계열 변형을 사용하면 그래프 친화적입니다. - 로그 테일링 및 내보내기 —
/logs/stream(SSE)을 사용하여 터미널 또는 로그 파이프라인에서 실시간 쿼리 테일을 확인하거나/logs/download를 사용하여 오프라인 분석/아카이브용 전체 내보내기를 가져옵니다. - 감사/규정 준수 확인 — 주기적으로 프로필의 전체 구성을 GET한 후 예상 기준선과 비교하여 드리프트(예: 대시보드에서 누군가 꺼버린 보안 토글)를 포착합니다.
- 다중 프로필 플릿 — 여러 네트워크/가정/사이트에 대해 NextDNS를 한 곳에서 관리하는
사용자를 위해 많은
:profileID에 대해 동일한 작업을 수행합니다.
사용 시기
- 거부 목록/허용 목록 엔트리, 보안/개인정보 토글, 자녀 보호 서비스/카테고리 또는 프로필 전체 설정을 읽거나 쓸 때.
- 분석(상위 도메인, 디바이스, 프로토콜, 차단 이유, 지리) 또는 원시/스트리밍 쿼리 로그를 가져올 때(시계열 분석 포함).
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> | 상태, 도메인, 이유, IP, 디바이스, 프로토콜, 쿼리 유형, IP 버전, DNSSEC, 암호화, 대상; 시간 버킷을 위해 ;series 추가 |
| 로그 | /profiles/:profile/logs | 목록, /stream(SSE), /download, DELETE로 지우기 |
전체 매개변수 테이블, 모든 JSON 스키마, 모든 예제 응답은
references/api-reference.md에 있습니다 — 중요하지 않은 호출(단일 GET 이상)을 작성하기 전에
이 문서를 읽어 필드 이름, 열거형, 기본값을 처음에 올바르게 파악하고 추측하거나
라이브 API와의 왕복을 피하세요.
기계 판독 가능한 references/openapi.yaml(OpenAPI 3.0, api-reference.md에서 가져온 응답 예제 포함)은
동일한 엔드포인트를 미러링합니다 — 클라이언트를 생성하거나 코드 생성 도구에 공급하거나
구조화된 diff 표면을 원할 때 사용하세요. 사람이 읽을 수 있는 버전은
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 파일이 없으므로 diff 대상이 없습니다 — 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을 커밋하여
둘이 분리되지 않도록 하세요.