AdGuardDNS/doc/http.md

AdGuard DNS HTTP API

The main HTTP API is served on the same port as the DNS-over-HTTP servers as well as on other addresses, if the web configuration is set appropriately.

Contents

• Block Pages
• DNS Server Check
• Linked IP Proxy
• Static Content

Block Pages

The safe browsing and adult blocking servers. Every request is responded with the content from the configured file, with the exception of GET /favicon.ico and GET /robots.txt requests, which are handled separately:

• GET /favicon.ico requests are responded with a plain-text 404 Not Found response.

• GET /robots.txt requests are responded with:

  User-agent: *
  Disallow: /
  

The static content is not served on these servers.

DNS Server Check

GET /dnscheck/test is the DNS server check HTTP API. It should be requested with a random ID prepended to one of the check domains with a hyphen. The random ID must have from 4 to 63 characters and only include the alphanumeric characters and a hyphen.

Example of the request:

curl 'https://0123-abcd-dnscheck.example.com/dnscheck/test'

Example of the output:

{
  "client_ip": "1.2.3.4",
  "device_id": "abcd1234",
  "profile_id": "defa5678",
  "protocol": "dot",
  "node_location": "ams",
  "node_name": "eu-1.dns.example.com",
  "server_group_name": "adguard_dns_default",
  "server_name": "default_dns"
}

The protocol field can have one of the following values:

"dns-tcp"

Plain DNS over TCP.

"dns-udp"

Plain DNS over UDP.

"dnscrypt-tcp"

DNSCrypt over TCP.

"dnscrypt-udp"

DNSCrypt over UDP.

"doh"

DNS-over-HTTP.

"doq"

DNS-over-QUIC.

"dot"

DNS-over-TLS.

Linked IP Proxy

The linked IP and Dynamic DNS (DDNS, DynDNS) HTTP proxy. If the linked IP configuration is not empty, the following queries are either processed or proxied to BACKEND_ENDPOINT.

• GET /robots.txt: a special response is served, see below;
• GET /linkip/{device_id}/{encrypted}/status: proxied;
• GET /linkip/{device_id}/{encrypted}: proxied;
• POST /ddns/{device_id}/{encrypted}/{domain}: proxied;
• POST /linkip/{device_id}/{encrypted}: proxied.

In the case of a GET /robots.txt request, the following content is served:

User-agent: *
Disallow: /

The static content is not served on the linked IP addresses.

Static Content

The static content server. Enabled if the static content configuration is not empty. Static content is not served on the linked IP proxy server and the safe browsing and adult blocking servers.