Reference

AdGuard DNS API

DNS API documentation

AdGuard DNS API Change Log

v1.0

• Added authentication.
• CRUD operations with devices and DNS servers.
• Query log.
• Downloading DOT and DOT .mobileconfig.
• Filter Lists and Web-Services.

v1.1

• Added methods to retrieve statistics by time, domains, companies and devices.

• Added method for updating device settings.

• Fixed required fields definition.

v1.2

• Added new protocol types DNS and DNSCRYPT. Deprecating the PLAIN_TCP, PLAIN_UDP, DNSCRYPT_TCP and DNSCRYPT_UDP that will be removed later.

v1.3

• Added method to get account limits.

v1.4

• Added configurable option for blocking response: default (0.0.0.0), REFUSED, NXDOMAIN or custom IP-address.

v1.5

• Added new setting block_nrd and group all security-related settings to one place.

Model for safebrowsing settings changed from

{
   "enabled": true
}

to:

{
   "enabled": true,
   "block_dangerous_domains": true,
   "block_nrd": false
}

where enabled is now control all settings in group, block_dangerous_domains is previous model field "enabled" and block_nrd is settings for filtering newly registered domains.

Model for saving server settings changed from

{
  "protection_enabled" : true,
  "safebrowsing_enabled" : true,
  ...
}

to:

{
  "protection_enabled" : true,
  "safebrowsing_settings" : {
     "enabled": true,
     "block_dangerous_domains": true,
     "block_nrd": false
  }
  ...
}

here new field safebrowsing_settings is used instead of deprecated safebrowsing_enabled, whose value stored in block_dangerous_domains.

Version: 1.5

/oapi/v1/account/limits

GET

Summary

Gets account limits

Responses

Code	Description
200	Account limits info

/oapi/v1/devices

GET

Summary

Lists devices

Responses

Code	Description
200	List of devices

POST

Summary

Creates a new device

Responses

Code	Description
200	Device created
400	Validation failed
429	Devices count reached the limit

/oapi/v1/devices/{device_id}

DELETE

Summary

Removes a device

Parameters

Name	Located in	Description	Required	Schema
device_id	path		Yes	string

Responses

Code	Description
200	Device deleted
404	Device not found

GET

Summary

Gets an existing device by ID

Parameters

Name	Located in	Description	Required	Schema
device_id	path		Yes	string

Responses

Code	Description
200	Device info
404	Device not found

PUT

Summary

Updates an existing device

Parameters

Name	Located in	Description	Required	Schema
device_id	path		Yes	string

Responses

Code	Description
200	Device updated
400	Validation failed
404	Device not found

/oapi/v1/devices/{device_id}/doh.mobileconfig

GET

Summary

Gets DNS-over-HTTPS .mobileconfig file.

Parameters

Name	Located in	Description	Required	Schema
device_id	path		Yes	string
exclude_wifi_networks	query	List Wi-Fi networks by their SSID in which you want AdGuard DNS to be disabled	No	[ string ]
exclude_domain	query	List domains that will use default DNS servers instead of AdGuard DNS	No	[ string ]

Responses

Code	Description
200	DNS-over-HTTPS .plist file
404	Device not found

/oapi/v1/devices/{device_id}/dot.mobileconfig

GET

Summary

Gets DNS-over-TLS .mobileconfig file.

Parameters

Name	Located in	Description	Required	Schema
device_id	path		Yes	string
exclude_wifi_networks	query	List Wi-Fi networks by their SSID in which you want AdGuard DNS to be disabled	No	[ string ]
exclude_domain	query	List domains that will use default DNS servers instead of AdGuard DNS	No	[ string ]

Responses

Code	Description
200	DNS-over-HTTPS .plist file
404	Device not found

/oapi/v1/devices/{device_id}/settings

PUT

Summary

Updates device settings

Parameters

Name	Located in	Description	Required	Schema
device_id	path		Yes	string

Responses

Code	Description
200	Device settings updated
400	Validation failed
404	Device not found

/oapi/v1/dns_servers

GET

Summary

Lists DNS servers that belong to the user.

Description

Lists DNS servers that belong to the user. By default there is at least one default server.

Responses

Code	Description
200	List of DNS servers

POST

Summary

Creates a new DNS server

Description

Creates a new DNS server. You can attach custom settings, otherwise DNS server will be created with default settings.

Responses

Code	Description
200	DNS server created
400	Validation failed
429	DNS servers count reached the limit

/oapi/v1/dns_servers/{dns_server_id}

DELETE

Summary

Removes a DNS server

Description

Removes a DNS server. All devices attached to this DNS server will be moved to the default DNS server. Deleting the default DNS server is forbidden.

Parameters

Name	Located in	Description	Required	Schema
dns_server_id	path		Yes	string

Responses

Code	Description
200	DNS server deleted
404	DNS server not found

GET

Summary

Gets an existing DNS server by ID

Parameters

Name	Located in	Description	Required	Schema
dns_server_id	path		Yes	string

Responses

Code	Description
200	DNS server info
404	DNS server not found

PUT

Summary

Updates an existing DNS server

Parameters

Name	Located in	Description	Required	Schema
dns_server_id	path		Yes	string

Responses

Code	Description
200	DNS server updated
400	Validation failed
404	DNS server not found

/oapi/v1/dns_servers/{dns_server_id}/settings

PUT

Summary

Updates DNS server settings

Parameters

Name	Located in	Description	Required	Schema
dns_server_id	path		Yes	string

Responses

Code	Description
200	DNS server settings updated
400	Validation failed
404	DNS server not found

/oapi/v1/filter_lists

GET

Summary

Gets filter lists

Responses

Code	Description
200	List of filters

/oapi/v1/oauth_token

POST

Summary

Generates Access and Refresh token

Responses

Code	Description
200	Access token issued
400	Missing required parameters
401	Invalid credentials, MFA token or refresh token provided

null

/oapi/v1/query_log

DELETE

Summary

Clears query log

Responses

Code	Description
202	Query log was cleared

GET

Summary

Gets query log

Parameters

Name	Located in	Description	Required	Schema
time_from_millis	query	Time from in milliseconds (inclusive)	Yes	long
time_to_millis	query	Time to in milliseconds (inclusive)	Yes	long
devices	query	Filter by devices	No	[ string ]
countries	query	Filter by countries	No	[ string ]
companies	query	Filter by companies	No	[ string ]
statuses	query	Filter by statuses	No	[ FilteringActionStatus ]
categories	query	Filter by categories	No	[ CategoryType ]
search	query	Filter by domain name	No	string
limit	query	Limit the number of records to be returned	No	integer
cursor	query	Pagination cursor. Use cursor from response to paginate through the pages.	No	string

Responses

Code	Description
200	Query log

/oapi/v1/revoke_token

POST

Summary

Revokes a Refresh Token

Parameters

Name	Located in	Description	Required	Schema
refresh_token	query	Refresh Token	Yes	string

Responses

Code	Description
200	Refresh token revoked

null

/oapi/v1/stats/categories

GET

Summary

Gets categories statistics

Parameters

Name	Located in	Description	Required	Schema
time_from_millis	query	Time from in milliseconds (inclusive)	Yes	long
time_to_millis	query	Time to in milliseconds (inclusive)	Yes	long
devices	query	Filter by devices	No	[ string ]
countries	query	Filter by countries	No	[ string ]

Responses

Code	Description
200	Categories statistics received
400	Validation failed

/oapi/v1/stats/companies

GET

Summary

Gets companies statistics

Parameters

Name	Located in	Description	Required	Schema
time_from_millis	query	Time from in milliseconds (inclusive)	Yes	long
time_to_millis	query	Time to in milliseconds (inclusive)	Yes	long
devices	query	Filter by devices	No	[ string ]
countries	query	Filter by countries	No	[ string ]

Responses

Code	Description
200	Companies statistics received
400	Validation failed

/oapi/v1/stats/companies/detailed

GET

Summary

Gets detailed companies statistics

Parameters

Name	Located in	Description	Required	Schema
time_from_millis	query	Time from in milliseconds (inclusive)	Yes	long
time_to_millis	query	Time to in milliseconds (inclusive)	Yes	long
devices	query	Filter by devices	No	[ string ]
countries	query	Filter by countries	No	[ string ]
cursor	query	Pagination cursor	No	string

Responses

Code	Description
200	Detailed companies statistics received
400	Validation failed

/oapi/v1/stats/countries

GET

Summary

Gets countries statistics

Parameters

Name	Located in	Description	Required	Schema
time_from_millis	query	Time from in milliseconds (inclusive)	Yes	long
time_to_millis	query	Time to in milliseconds (inclusive)	Yes	long
devices	query	Filter by devices	No	[ string ]
countries	query	Filter by countries	No	[ string ]

Responses

Code	Description
200	Countries statistics received
400	Validation failed

/oapi/v1/stats/devices

GET

Summary

Gets devices statistics

Parameters

Name	Located in	Description	Required	Schema
time_from_millis	query	Time from in milliseconds (inclusive)	Yes	long
time_to_millis	query	Time to in milliseconds (inclusive)	Yes	long
devices	query	Filter by devices	No	[ string ]
countries	query	Filter by countries	No	[ string ]

Responses

Code	Description
200	Devices statistics received
400	Validation failed

/oapi/v1/stats/domains

GET

Summary

Gets domains statistics

Parameters

Name	Located in	Description	Required	Schema
time_from_millis	query	Time from in milliseconds (inclusive)	Yes	long
time_to_millis	query	Time to in milliseconds (inclusive)	Yes	long
devices	query	Filter by devices	No	[ string ]
countries	query	Filter by countries	No	[ string ]

Responses

Code	Description
200	Domains statistics received
400	Validation failed

/oapi/v1/stats/time

GET

Summary

Gets time statistics

Parameters

Name	Located in	Description	Required	Schema
time_from_millis	query	Time from in milliseconds (inclusive)	Yes	long
time_to_millis	query	Time to in milliseconds (inclusive)	Yes	long
devices	query	Filter by devices	No	[ string ]
countries	query	Filter by countries	No	[ string ]

Responses

Code	Description
200	Time statistics received
400	Validation failed

/oapi/v1/web_services

GET

Summary

Lists web services

Responses

Code	Description
200	List of web-services