mirror of
https://github.com/AdguardTeam/AdGuardHome.git
synced 2024-11-16 10:28:29 -07:00
591065aa3a
Updated the openapi.yaml accordingly Some minor refactoring/renaming Fix other review comments
594 lines
21 KiB
YAML
594 lines
21 KiB
YAML
swagger: '2.0'
|
|
info:
|
|
title: 'AdGuard Home'
|
|
description: 'Control AdGuard Home server with this API'
|
|
version: 0.0.0
|
|
basePath: /control
|
|
schemes:
|
|
- http
|
|
produces:
|
|
- application/json
|
|
tags:
|
|
-
|
|
name: global
|
|
description: 'DNS server controls'
|
|
-
|
|
name: filtering
|
|
description: 'Rule-based filtering'
|
|
-
|
|
name: safebrowsing
|
|
description: 'Malware/hazardous sites'
|
|
-
|
|
name: parental
|
|
description: 'Sites inappropriate for children'
|
|
-
|
|
name: safesearch
|
|
description: 'Enforce family-friendly results in search engines'
|
|
paths:
|
|
/status:
|
|
get:
|
|
tags:
|
|
- global
|
|
operationId: status
|
|
summary: 'Get DNS server status'
|
|
responses:
|
|
200:
|
|
description: OK
|
|
examples:
|
|
application/json:
|
|
dns_address: 127.0.0.1
|
|
dns_port: 53
|
|
protection_enabled: true
|
|
querylog_enabled: true
|
|
running: true
|
|
upstream_dns:
|
|
- 1.1.1.1
|
|
- 1.0.0.1
|
|
version: "v0.1"
|
|
/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"
|
|
/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
|
|
/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
|