2019-10-18 10:43:12 +00:00
# AdGuard Home API Change Log
2020-12-17 10:32:46 +00:00
<!-- TODO(a.garipov): Reformat in accordance with the KeepAChangelog spec. -->
2021-05-26 14:55:19 +00:00
## v0.107: API changes
2021-06-01 18:06:55 +00:00
### The parameter `"host"` in `GET /apple/*.mobileconfig` is now required.
* The parameter `"host"` in `GET` requests for `/apple/doh.mobileconfig` and
`/apple/doh.mobileconfig` is now required to prevent unexpected server name's
value.
2021-06-01 11:28:34 +00:00
### The new field `"default_local_ptr_upstreams"` in `GET /control/dns_info`
* The new optional field `"default_local_ptr_upstreams"` is the list of IP
addresses AdGuard Home would use by default to resolve PTR request for
addresses from locally-served networks.
2021-05-26 14:55:19 +00:00
### The field `"use_private_ptr_resolvers"` in DNS configuration
* The new optional field `"use_private_ptr_resolvers"` of `"DNSConfig"`
specifies if the DNS server should use `"local_ptr_upstreams"` at all.
2021-04-02 14:30:39 +00:00
## v0.106: API changes
2021-05-06 13:41:33 +00:00
### The field `"supported_tags"` in `GET /control/clients`
2021-05-26 14:55:19 +00:00
* Previously undocumented field `"supported_tags"` in the response is now
2021-05-06 13:41:33 +00:00
documented.
### The field `"whois_info"` in `GET /control/clients`
* Objects in the `"auto_clients"` array now have the `"whois_info"` field.
2021-04-27 15:56:32 +00:00
### New response code in `POST /control/login`
* `429` is returned when user is out of login attempts. It adds the
`Retry-After` header with the number of seconds of block left in it.
### New `"private_upstream"` field in `POST /test_upstream_dns`
2021-04-07 17:16:06 +00:00
* The new optional field `"private_upstream"` of `UpstreamConfig` contains the
upstream servers for resolving locally-served ip addresses to be checked.
### New fields `"resolve_clients"` and `"local_ptr_upstreams"` in DNS configuration
* The new optional field `"resolve_clients"` of `DNSConfig` is used to turn
resolving clients' addresses on and off.
* The new optional field `"local_ptr_upstreams"` of `"DNSConfig"` contains the
upstream servers for resolving addresses from locally-served networks. The
empty `"local_ptr_resolvers"` states that AGH should use resolvers provided by
the operating system.
2021-04-02 14:30:39 +00:00
### New `"client_info"` field in `GET /querylog` response
* The new optional field `"client_info"` of `QueryLogItem` objects contains
a more full information about the client.
2020-12-17 10:32:46 +00:00
## v0.105: API changes
2021-02-11 12:41:03 +00:00
### New `"client_id"` field in `GET /querylog` response
* The new field `"client_id"` of `QueryLogItem` objects is the ID sent by the
client for encrypted requests, if there was any. See the
"[Identifying clients]" section of our wiki.
2021-01-27 15:32:13 +00:00
### New `"dnscrypt"` `"client_proto"` value in `GET /querylog` response
* The field `"client_proto"` can now have the value `"dnscrypt"` when the
request was sent over a DNSCrypt connection.
2020-12-21 14:48:07 +00:00
### New `"reason"` in `GET /filtering/check_host` and `GET /querylog`
2020-12-28 15:41:50 +00:00
* The new `RewriteRule` reason is added to `GET /filtering/check_host` and
2020-12-21 14:48:07 +00:00
`GET /querylog` .
2020-12-17 10:32:46 +00:00
2020-12-21 14:48:07 +00:00
* Also, the reason which was incorrectly documented as `"ReasonRewrite"` is now
correctly documented as `"Rewrite"` , and the previously undocumented
`"RewriteEtcHosts"` is now documented as well.
### Multiple matched rules in `GET /filtering/check_host` and `GET /querylog`
2020-12-17 10:32:46 +00:00
* The properties `rule` and `filter_id` are now deprecated. API users should
2020-12-21 14:48:07 +00:00
inspect the newly-added `rules` object array instead. For most rules, it's
either empty or contains one object, which contains the same things as the old
two properties did, but under more correct names:
2020-12-17 10:32:46 +00:00
```js
{
// …
// Deprecated.
"rule": "||example.com^",
// Deprecated.
"filter_id": 42,
// Newly-added.
"rules": [{
"text": "||example.com^",
"filter_list_id": 42
}]
}
```
2020-12-21 14:48:07 +00:00
For `$dnsrewrite` rules, they contain all rules that contributed to the
result. For example, if you have the following filtering rules:
```
||example.com^$dnsrewrite=127.0.0.1
||example.com^$dnsrewrite=127.0.0.2
```
The `"rules"` will be something like:
```js
{
// …
"rules": [{
"text": "||example.com^$dnsrewrite=127.0.0.1",
"filter_list_id": 0
}, {
"text": "||example.com^$dnsrewrite=127.0.0.2",
"filter_list_id": 0
}]
}
```
2020-12-17 10:32:46 +00:00
The old fields will be removed in v0.106.0.
2021-01-13 14:26:57 +00:00
As well as other documentation fixes.
2021-02-11 12:41:03 +00:00
[Identifying clients]: https://github.com/AdguardTeam/AdGuardHome/wiki/Clients#idclient
2020-05-26 12:37:37 +00:00
## v0.103: API changes
2020-07-23 16:25:42 +00:00
### API: replace settings in GET /control/dns_info & POST /control/dns_config
* added "upstream_mode"
"upstream_mode": "" | "parallel" | "fastest_addr"
* removed "fastest_addr", "parallel_requests"
2020-05-26 12:37:37 +00:00
### API: Get querylog: GET /control/querylog
* Added optional "offset" and "limit" parameters
We are still using "older_than" approach in AdGuard Home UI, but we realize that it's easier to use offset/limit so here is this option now.
2019-10-18 10:43:12 +00:00
2020-07-23 16:25:42 +00:00
2020-04-22 16:14:04 +00:00
## v0.102: API changes
### API: Get general status: GET /control/status
* Removed "upstream_dns", "bootstrap_dns", "all_servers" parameters
### API: Get DNS general settings: GET /control/dns_info
* Added "parallel_requests", "upstream_dns", "bootstrap_dns" parameters
Request:
GET /control/dns_info
Response:
200 OK
{
"upstream_dns": ["tls://...", ...],
"bootstrap_dns": ["1.2.3.4", ...],
"protection_enabled": true | false,
"ratelimit": 1234,
"blocking_mode": "default" | "nxdomain" | "null_ip" | "custom_ip",
"blocking_ipv4": "1.2.3.4",
"blocking_ipv6": "1:2:3::4",
"edns_cs_enabled": true | false,
"dnssec_enabled": true | false
"disable_ipv6": true | false,
"fastest_addr": true | false, // use Fastest Address algorithm
"parallel_requests": true | false, // send DNS requests to all upstream servers at once
}
### API: Set DNS general settings: POST /control/dns_config
* Added "parallel_requests", "upstream_dns", "bootstrap_dns" parameters
* removed /control/set_upstreams_config method
Request:
POST /control/dns_config
{
"upstream_dns": ["tls://...", ...],
"bootstrap_dns": ["1.2.3.4", ...],
"protection_enabled": true | false,
"ratelimit": 1234,
"blocking_mode": "default" | "nxdomain" | "null_ip" | "custom_ip",
"blocking_ipv4": "1.2.3.4",
"blocking_ipv6": "1:2:3::4",
"edns_cs_enabled": true | false,
"dnssec_enabled": true | false
"disable_ipv6": true | false,
"fastest_addr": true | false, // use Fastest Address algorithm
"parallel_requests": true | false, // send DNS requests to all upstream servers at once
}
Response:
200 OK
2020-02-28 15:34:09 +00:00
## v0.101: API changes
### API: Refresh filters: POST /control/filtering/refresh
* Added "whitelist" boolean parameter
2020-03-13 09:11:52 +00:00
* Response is in JSON format
2020-02-28 15:34:09 +00:00
Request:
POST /control/filtering/refresh
{
"whitelist": true
}
2020-03-13 09:11:52 +00:00
Response:
200 OK
{
"updated": 123 // number of filters updated
}
2020-02-28 15:34:09 +00:00
2019-11-19 16:34:07 +00:00
## v0.100: API changes
### API: Get list of clients: GET /control/clients
* "ip" and "mac" fields are removed
* "ids" and "ip_addrs" fields are added
Response:
200 OK
{
clients: [
{
name: "client1"
ids: ["...", ...] // IP or MAC
ip_addrs: ["...", ...] // all IP addresses (set by user and resolved by MAC)
use_global_settings: true
filtering_enabled: false
parental_enabled: false
safebrowsing_enabled: false
safesearch_enabled: false
use_global_blocked_services: true
blocked_services: [ "name1", ... ]
whois_info: {
key: "value"
...
}
}
]
auto_clients: [
{
name: "host"
ip: "..."
source: "etc/hosts" || "rDNS"
whois_info: {
key: "value"
...
}
}
]
}
### API: Add client: POST /control/clients/add
* "ip" and "mac" fields are removed
* "ids" field is added
Request:
POST /control/clients/add
{
name: "client1"
ids: ["...", ...] // IP or MAC
use_global_settings: true
filtering_enabled: false
parental_enabled: false
safebrowsing_enabled: false
safesearch_enabled: false
use_global_blocked_services: true
blocked_services: [ "name1", ... ]
}
### API: Update client: POST /control/clients/update
* "ip" and "mac" fields are removed
* "ids" field is added
Request:
POST /control/clients/update
{
name: "client1"
data: {
name: "client1"
ids: ["...", ...] // IP or MAC
use_global_settings: true
filtering_enabled: false
parental_enabled: false
safebrowsing_enabled: false
safesearch_enabled: false
use_global_blocked_services: true
blocked_services: [ "name1", ... ]
}
}
2019-11-14 12:18:43 +00:00
## v0.99.3: API changes
### API: Get query log: GET /control/querylog
The response data is now a JSON object, not an array.
Response:
200 OK
{
"oldest":"2006-01-02T15:04:05.999999999Z07:00"
"data":[
{
"answer":[
{
"ttl":10,
"type":"AAAA",
"value":"::"
}
...
],
"client":"127.0.0.1",
"elapsedMs":"0.098403",
"filterId":1,
"question":{
"class":"IN",
"host":"doubleclick.net",
"type":"AAAA"
},
"reason":"FilteredBlackList",
"rule":"||doubleclick.net^",
"status":"NOERROR",
"time":"2006-01-02T15:04:05.999999999Z07:00"
}
...
]
}
2019-10-23 16:19:04 +00:00
## v0.99.1: API changes
### API: Get current user info: GET /control/profile
Request:
GET /control/profile
Response:
200 OK
{
"name":"..."
}
2019-11-15 08:36:47 +00:00
### Set DNS general settings: POST /control/dns_config
Replaces these API methods:
POST /control/enable_protection
POST /control/disable_protection
Request:
POST /control/dns_config
{
"protection_enabled": true | false,
"ratelimit": 1234,
"blocking_mode": "nxdomain" | "null_ip" | "custom_ip",
"blocking_ipv4": "1.2.3.4",
"blocking_ipv6": "1:2:3::4",
}
Response:
200 OK
2019-10-18 10:43:12 +00:00
## v0.99: incompatible API changes
* A note about web user authentication
* Set filtering parameters: POST /control/filtering/config
* Set filter parameters: POST /control/filtering/set_url
* Set querylog parameters: POST /control/querylog_config
* Get statistics data: GET /control/stats
### A note about web user authentication
If AdGuard Home's web user is password-protected, a web client must use authentication mechanism when sending requests to server. Basic access authentication is the most simple method - a client must pass `Authorization` HTTP header along with all requests:
Authorization: Basic BASE64_DATA
where BASE64_DATA is base64-encoded data for `username:password` string.
### Set filtering parameters: POST /control/filtering/config
Replaces these API methods:
POST /control/filtering/enable
POST /control/filtering/disable
Request:
POST /control/filtering_config
{
"enabled": true | false
"interval": 0 | 1 | 12 | 1*24 | 3*24 | 7*24
}
Response:
200 OK
### Set filter parameters: POST /control/filtering/set_url
Replaces these API methods:
POST /control/filtering/enable_url
POST /control/filtering/disable_url
Request:
POST /control/filtering/set_url
{
"url": "..."
"enabled": true | false
}
Response:
200 OK
### Set querylog parameters: POST /control/querylog_config
Replaces these API methods:
POST /querylog_enable
POST /querylog_disable
Request:
POST /control/querylog_config
{
"enabled": true | false
"interval": 1 | 7 | 30 | 90
}
Response:
200 OK
### Get statistics data: GET /control/stats
Replaces these API methods:
GET /control/stats_top
GET /control/stats_history
Request:
GET /control/stats
Response:
200 OK
{
time_units: hours | days
// total counters:
num_dns_queries: 123
num_blocked_filtering: 123
num_replaced_safebrowsing: 123
num_replaced_safesearch: 123
num_replaced_parental: 123
avg_processing_time: 123.123
// per time unit counters
dns_queries: [123, ...]
blocked_filtering: [123, ...]
replaced_parental: [123, ...]
replaced_safebrowsing: [123, ...]
top_queried_domains: [
{host: 123},
...
]
top_blocked_domains: [
{host: 123},
...
]
top_clients: [
{IP: 123},
...
]
}
