swagger: '2.0' info: title: 'AdGuard Home' description: 'AdGuard Home REST API. Admin web interface is built on top of this REST API.' version: 0.91.0 basePath: /control schemes: - http produces: - application/json tags: - name: global description: 'DNS server general settings and controls' - name: i18n description: 'Application localization' - name: filtering description: 'Rule-based filtering' - name: safebrowsing description: 'Blocking malware/phishing sites' - name: parental description: 'Blocking adult and explicit materials' - name: safesearch description: 'Enforce family-friendly results in search engines' - name: dhcp description: 'Built-in DHCP server controls' paths: /status: get: tags: - global operationId: status summary: 'Get DNS server current status and general settings' responses: 200: description: OK examples: application/json: dns_address: 127.0.0.1 dns_port: 53 protection_enabled: true querylog_enabled: true running: true bootstrap_dns: 8.8.8.8:53 upstream_dns: - tls://1.1.1.1 - tls://1.0.0.1 version: "v0.1" language: "en" /enable_protection: post: tags: - global operationId: enableProtection summary: "Enable protection (turns on dnsfilter module in coredns)" responses: 200: description: OK /disable_protection: post: tags: - global operationId: disableProtection summary: "Disable protection (turns off filtering, sb, parental, safesearch temporarily by disabling dnsfilter module in coredns)" responses: 200: description: OK /querylog: get: tags: - global operationId: queryLog summary: 'Get DNS server query log' parameters: - in: query name: download type: boolean description: 'If any value is set, make the browser download the query instead of displaying it by setting Content-Disposition header' responses: 200: description: OK examples: application/json: - answer: - ttl: 55 type: A value: 217.69.139.201 - ttl: 55 type: A value: 94.100.180.200 - ttl: 55 type: A value: 94.100.180.201 - ttl: 55 type: A value: 217.69.139.200 elapsedMs: '65.469556' question: class: IN host: mail.ru type: A reason: DNSFILTER_NOTFILTERED_NOTFOUND status: NOERROR time: '2018-07-16T22:24:02+03:00' - elapsedMs: '0.15716999999999998' question: class: IN host: doubleclick.net type: A reason: DNSFILTER_FILTERED_BLACKLIST rule: "||doubleclick.net^" status: NXDOMAIN time: '2018-07-16T22:24:02+03:00' - answer: - ttl: 299 type: A value: 176.103.133.78 elapsedMs: '132.110929' question: class: IN host: wmconvirus.narod.ru type: A reason: DNSFILTER_FILTERED_SAFEBROWSING rule: adguard-malware-shavar filterId: 1 status: NOERROR time: '2018-07-16T22:24:02+03:00' /querylog_enable: post: tags: - global operationId: querylogEnable summary: 'Enable querylog' responses: 200: description: OK /querylog_disable: post: tags: - global operationId: querylogDisable summary: 'Disable filtering' responses: 200: description: OK /set_upstream_dns: post: tags: - global operationId: setUpstreamDNS summary: 'Set upstream DNS for coredns, empty value will reset it to default values' consumes: - text/plain parameters: - in: body name: upstream description: 'Upstream servers, separated by newline or space, port is optional after colon' schema: type: string example: | 1.1.1.1 1.0.0.1 8.8.8.8 8.8.4.4 192.168.1.104:53535 responses: 200: description: OK /test_upstream_dns: post: tags: - global operationId: testUpstreamDNS summary: 'Test upstream DNS' consumes: - text/plain parameters: - in: body name: upstream description: 'Upstream servers, separated by newline or space, port is optional after colon' schema: type: string example: | 1.1.1.1 1.0.0.1 8.8.8.8 8.8.4.4 192.168.1.104:53535 responses: 200: description: 'Status of testing each requested server, with "OK" meaning that server works, any other text means an error.' examples: application/json: 1.1.1.1: OK 1.0.0.1: OK 8.8.8.8: OK 8.8.4.4: OK "192.168.1.104:53535": "Couldn't communicate with DNS server" /i18n/change_language: post: tags: - i18n operationId: changeLanguage summary: "Change current language. Argument must be an ISO 639-1 two-letter code" consumes: - text/plain parameters: - in: body name: language description: "New language. It must be known to the server and must be an ISO 639-1 two-letter code" schema: type: string example: en /i18n/current_language: get: tags: - i18n operationId: currentLanguage summary: "Get currently set language. Result is ISO 639-1 two-letter code. Empty result means default language." responses: 200: description: OK examples: text/plain: en /stats_top: get: tags: - global operationId: statusTop summary: 'Get DNS server top client, domain and blocked statistics' responses: 200: description: OK examples: application/json: top_queried_domains: example.org: 12312 example.com: 12312 example.net: 12312 example.ru: 12312 top_clients: 127.0.0.1: 12312 192.168.0.1: 13211 192.168.0.2: 13211 192.168.0.3: 13211 192.168.0.4: 13211 192.168.0.5: 13211 192.168.0.6: 13211 top_blocked_domains: example.org: 12312 example.com: 12312 example.net: 12312 example.ru: 12312 /stats: get: tags: - global operationId: stats summary: 'Get DNS server statistics' responses: 200: description: 'Gives statistics since start of the server' examples: application/json: dns_queries: 1201 blocked_filtering: 123 replaced_safebrowsing: 5 replaced_parental: 18 replaced_safesearch: 94 avg_processing_time: 123 /stats_history: get: tags: - global operationId: stats_history summary: 'Get historical DNS server statistics' parameters: - name: start_time in: query type: string description: 'Start time in ISO8601 (example: `2018-05-04T17:55:33+00:00`)' required: true - name: end_time in: query type: string description: 'End time in ISO8601 (example: `2018-05-04T17:55:33+00:00`)' required: true - name: time_unit in: query type: string description: 'Time unit (`minutes` or `hours`)' required: true enum: - minutes - hours responses: 501: description: 'Requested time window is outside of supported range. It will be supported later, but not now.' 200: description: 'Gives statistics since start of the server. Example below is for 5 minutes. Values are from oldest to newest.' examples: application/json: dns_queries: - 1201 - 1201 - 1201 - 1201 - 1201 blocked_filtering: - 123 - 123 - 123 - 123 - 123 replaced_safebrowsing: - 5 - 5 - 5 - 5 - 5 replaced_parental: - 18 - 18 - 18 - 18 - 18 replaced_safesearch: - 94 - 94 - 94 - 94 - 94 avg_processing_time: - 123 - 123 - 123 - 123 - 123 /stats_reset: post: tags: - global operationId: statsReset summary: "Reset all statistics to zeroes" responses: 200: description: OK /dhcp/status: post: tags: - dhcp operationId: dhcpStatus summary: "Gets the current DHCP settings" responses: 200: description: OK examples: application/json: dhcpEnabled: false gatewayIp: 192.168.1.1 subnetMask: 255.255.255.0 rangeStart: 192.168.1.2 rangeEnd: 192.168.10.50 leaseDuration: 12h leases: mac: 001109b3b3b8 ip: 192.168.1.22 hostname: dell expires: '2018-10-30T12:18:57.223101822+03:00' /dhcp/set_config: post: tags: - dhcp operationId: dhcpSetConfig summary: "Updates the current DHCP server configuration" consumes: - application/json parameters: - in: body name: dhcpConfig description: 'Updates the DHCP module configuration' schema: type: json example: '{ gatewayIp: "192.168.1.1", subnetMask: "255.255.255.0", "rangeStart": "192.168.1.2", "rangeEnd": "192.168.10.50", leaseDuration: "12h" }' responses: 200: description: OK /dhcp/check_active_dhcp: post: tags: - dhcp operationId: checkActiveDhcp summary: "Checks if there's an active DHCP server on the network" responses: 200: description: OK examples: application/json: found: true gatewayIp: 192.168.1.1 /filtering/enable: post: tags: - filtering operationId: filteringEnable summary: 'Enable filtering' responses: 200: description: OK /filtering/disable: post: tags: - filtering operationId: filteringDisable summary: 'Disable filtering' responses: 200: description: OK /filtering/add_url: put: tags: - filtering operationId: filteringAddURL summary: 'Add filter URL' consumes: - text/plain parameters: - in: body name: url description: 'URL containing filtering rules' required: true schema: type: string example: 'url=https://filters.adtidy.org/windows/filters/15.txt' responses: 200: description: OK /filtering/remove_url: delete: tags: - filtering operationId: filteringRemoveURL summary: 'Remove filter URL' consumes: - text/plain parameters: - in: body name: url description: 'Previously added URL containing filtering rules' required: true schema: type: string example: 'url=https://filters.adtidy.org/windows/filters/15.txt' responses: 200: description: OK /filtering/enable_url: post: tags: - filtering operationId: filteringEnableURL summary: 'Enable filter URL' consumes: - text/plain parameters: - in: body name: url description: 'Previously added URL containing filtering rules' required: true schema: type: string example: 'url=https://filters.adtidy.org/windows/filters/15.txt' responses: 200: description: OK /filtering/disable_url: post: tags: - filtering operationId: filteringDisableURL summary: 'Disable filter URL' consumes: - text/plain parameters: - in: body name: url description: 'Previously added URL containing filtering rules' required: true schema: type: string example: 'url=https://filters.adtidy.org/windows/filters/15.txt' responses: 200: description: OK /filtering/refresh: post: tags: - filtering operationId: filteringRefresh summary: | Reload filtering rules from URLs This might be needed if new URL was just added and you dont want to wait for automatic refresh to kick in. This API request is ratelimited, so you can call it freely as often as you like, it wont create unneccessary burden on servers that host the URL. This should work as intended, a `force` parameter is offered as last-resort attempt to make filter lists fresh. If you ever find yourself using `force` to make something work that otherwise wont, this is a bug and report it accordingly. parameters: - name: force in: query type: boolean description: 'If any value is set, ignore cache and force re-download of all filters' responses: 200: description: OK with how many filters were actually updated /filtering/status: get: tags: - filtering operationId: filteringStatus summary: 'Get status of rules-based filter' responses: 200: description: OK examples: application/json: enabled: false filters: enabled: true id: 1 lastUpdated: "2018-10-30T12:18:57.223101822+03:00" name: "AdGuard Simplified Domain Names filter" rulesCount: 24896 url: "https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt" rules: - '@@||yandex.ru^|' /filtering/set_rules: put: tags: - filtering operationId: filteringSetRules summary: 'Set user-defined filter rules' consumes: - text/plain parameters: - in: body name: rules description: 'All filtering rules, one line per rule' schema: type: string example: '@@||yandex.ru^|' responses: 200: description: OK /safebrowsing/enable: post: tags: - safebrowsing operationId: safebrowsingEnable summary: 'Enable safebrowsing' responses: 200: description: OK /safebrowsing/disable: post: tags: - safebrowsing operationId: safebrowsingDisable summary: 'Disable safebrowsing' responses: 200: description: OK /safebrowsing/status: get: tags: - safebrowsing operationId: safebrowsingStatus summary: 'Get safebrowsing status' responses: 200: description: OK examples: application/json: enabled: false /parental/enable: post: tags: - parental operationId: parentalEnable summary: 'Enable parental filtering' consumes: - text/plain parameters: - in: body name: sensitivity description: | Age sensitivity for parental filtering, EARLY_CHILDHOOD is 3 YOUNG is 10 TEEN is 13 MATURE is 17 required: true schema: type: string enum: - EARLY_CHILDHOOD - YOUNG - TEEN - MATURE example: 'sensitivity=TEEN' responses: 200: description: OK /parental/disable: post: tags: - parental operationId: parentalDisable summary: 'Disable parental filtering' responses: 200: description: OK /parental/status: get: tags: - parental operationId: parentalStatus summary: 'Get parental filtering status' responses: 200: description: OK examples: application/json: enabled: true sensitivity: 13 /safesearch/enable: post: tags: - safesearch operationId: safesearchEnable summary: 'Enable safesearch' responses: 200: description: OK /safesearch/disable: post: tags: - safesearch operationId: safesearchDisable summary: 'Disable safesearch' responses: 200: description: OK /safesearch/status: get: tags: - safesearch operationId: safesearchStatus summary: 'Get safesearch status' responses: 200: description: OK examples: application/json: enabled: false definitions: rule: type: string