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, adult-blocking, and popup-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",
  "server_type": "private"
}

The protocol field can have one of the following values:

• `"dns": Plain DNS.
• `"dnscrypt": DNSCrypt.
• `"doh": DNS-over-HTTP.
• `"doq": DNS-over-QUIC.
• `"dot": DNS-over-TLS.

The server_type field can have one of the following values:

• "private": A private AdGuard DNS server is used.

  Note

  This does not mean that the server has recognized the user's device. See the device_id and profile_id properties for that.

• "public": A public AdGuard DNS server is used.

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 LINKED_IP_TARGET_URL.

• 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.