a/badguardhome
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
502fe3cfc5
badguardhome/openapi/openapi.yaml
Simon Zolin e2ddc82d70 + DNS: add fastest_addr setting 
* API: /dns_info, /dns_config: add "parallel_requests" instead of "all_servers" from /set_upstreams_config
* API: /status: removed fields

#715

Squashed commit of the following:

commit 7dd913bd336ecbaa7419b998d0bf913d89702fe6
Merge: 43706970 8170955a
Author: Simon Zolin <s.zolin@adguard.com>
Date:   Wed Apr 22 19:09:36 2020 +0300

    Merge remote-tracking branch 'origin/master' into 715-fastest-addr

commit 437069702a3e91e0b066e4b22b08cdc02ff19eaf
Author: Simon Zolin <s.zolin@adguard.com>
Date:   Wed Apr 22 19:08:55 2020 +0300

    minor

commit 9e713df80c5bf113c98794c0a20915c756a76938
Merge: e3bf4037 9b7c1181
Author: Simon Zolin <s.zolin@adguard.com>
Date:   Tue Apr 21 16:02:03 2020 +0300

    Merge remote-tracking branch 'origin/master' into 715-fastest-addr

commit e3bf4037f49198e42bde55305d6f9077341b556a
Author: Simon Zolin <s.zolin@adguard.com>
Date:   Tue Apr 21 15:40:49 2020 +0300

    minor

commit d6e6a823c5e51acc061b2850d362772efcb827e1
Author: Simon Zolin <s.zolin@adguard.com>
Date:   Fri Apr 17 17:56:24 2020 +0300

    * API changes

    . removed POST /set_upstreams_config
    . removed fields from GET /status: bootstrap_dns, upstream_dns, all_servers
    . added new fields to /dns_config and /dns_info

commit 237a452d09cc48ff8f00e81c7fd35e7828bea835
Author: Simon Zolin <s.zolin@adguard.com>
Date:   Fri Apr 17 16:43:13 2020 +0300

    * API: /dns_info, /dns_config: add "parallel_requests" instead of "all_servers" from /set_upstreams_config

commit 9976723b9725ed19e0cce152d1d1198b13c4acc1
Author: Simon Zolin <s.zolin@adguard.com>
Date:   Mon Mar 23 10:28:25 2020 +0300

    openapi

commit 6f8ea16c6332606f29095b0094d71e8a91798f82
Merge: 36e4d4e8 c8285c41
Author: Simon Zolin <s.zolin@adguard.com>
Date:   Fri Mar 20 19:18:48 2020 +0300

    Merge remote-tracking branch 'origin/master' into 715-fastest-addr

commit 36e4d4e82cadeaba5a11313f0d69d66a0924c342
Author: Simon Zolin <s.zolin@adguard.com>
Date:   Fri Mar 20 18:13:43 2020 +0300

    + DNS: add fastest_addr setting
2020-04-22 19:14:04 +03:00

1930 lines
58 KiB
YAML
Raw Blame History

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.102'
schemes:
- http
basePath: /control
produces:
- application/json
tags:
-
name: global
description: 'AdGuard Home server general settings and controls'
-
name: tls
description: 'AdGuard Home HTTPS/DOH/DOT settings'
-
name: log
description: 'AdGuard Home query log'
-
name: stats
description: 'AdGuard Home statistics'
-
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'
-
name: clients
description: 'Clients list operations'
-
name: install
description: 'First-time install configuration handlers'
paths:
# API TO-DO LIST
# TODO: Use JSON where it is possible
# TODO: Use lower_case for all objects' properties
# TODO: Move to definitions what's missing from there
# --------------------------------------------------
# General settings and controls
# --------------------------------------------------
/status:
get:
tags:
- global
operationId: status
summary: 'Get DNS server current status and general settings'
produces:
- application/json
responses:
200:
description: OK
schema:
$ref: "#/definitions/ServerStatus"
/dns_info:
get:
tags:
- global
operationId: dnsInfo
summary: 'Get general DNS parameters'
responses:
200:
description: OK
schema:
$ref: "#/definitions/DNSConfig"
/dns_config:
post:
tags:
- global
operationId: dnsConfig
summary: "Set general DNS parameters"
consumes:
- application/json
parameters:
- in: "body"
name: "body"
schema:
$ref: "#/definitions/DNSConfig"
responses:
200:
description: OK
/test_upstream_dns:
post:
tags:
- global
operationId: testUpstreamDNS
summary: "Test upstream configuration"
consumes:
- application/json
parameters:
- in: "body"
name: "body"
description: "Upstream configuration to be tested"
schema:
$ref: "#/definitions/UpstreamsConfig"
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"
/version.json:
post:
tags:
- global
operationId: getVersionJson
summary: 'Gets information about the latest available version of AdGuard'
consumes:
- application/json
parameters:
- in: "body"
name: "body"
required: true
schema:
$ref: "#/definitions/GetVersionRequest"
produces:
- 'application/json'
responses:
200:
description: 'Version info. If response message is empty, UI does not show a version update message.'
schema:
$ref: "#/definitions/VersionInfo"
500:
description: 'Cannot write answer'
502:
description: 'Cannot retrieve the version.json file contents'
/update:
post:
tags:
- global
operationId: beginUpdate
summary: 'Begin auto-upgrade procedure'
responses:
200:
description: OK
500:
description: Failed
# --------------------------------------------------
# Query log methods
# --------------------------------------------------
/querylog:
get:
tags:
- log
operationId: queryLog
summary: 'Get DNS server query log'
parameters:
- name: older_than
in: query
type: string
- name: filter_domain
in: query
type: string
description: "Filter by domain name"
- name: filter_client
in: query
type: string
description: "Filter by client"
- name: filter_question_type
in: query
type: string
description: "Filter by question type"
- name: filter_response_status
in: query
type: string
description: "Filter by response status"
enum:
-
- filtered
responses:
200:
description: OK
schema:
$ref: '#/definitions/QueryLog'
/querylog_info:
get:
tags:
- log
operationId: queryLogInfo
summary: 'Get query log parameters'
responses:
200:
description: OK
schema:
$ref: "#/definitions/QueryLogConfig"
/querylog_config:
post:
tags:
- log
operationId: queryLogConfig
summary: "Set query log parameters"
consumes:
- application/json
parameters:
- in: "body"
name: "body"
schema:
$ref: "#/definitions/QueryLogConfig"
responses:
200:
description: OK
/querylog_clear:
post:
tags:
- log
operationId: querylogClear
summary: 'Clear query log'
responses:
200:
description: OK
# --------------------------------------------------
# General statistics methods
# --------------------------------------------------
/stats:
get:
tags:
- stats
operationId: stats
summary: 'Get DNS server statistics'
responses:
200:
description: 'Returns statistics data'
schema:
$ref: "#/definitions/Stats"
/stats_reset:
post:
tags:
- stats
operationId: statsReset
summary: "Reset all statistics to zeroes"
responses:
200:
description: OK
/stats_info:
get:
tags:
- stats
operationId: statsInfo
summary: 'Get statistics parameters'
responses:
200:
description: OK
schema:
$ref: "#/definitions/StatsConfig"
/stats_config:
post:
tags:
- stats
operationId: statsConfig
summary: "Set statistics parameters"
consumes:
- application/json
parameters:
- in: "body"
name: "body"
schema:
$ref: "#/definitions/StatsConfig"
responses:
200:
description: OK
# --------------------------------------------------
# TLS server methods
# --------------------------------------------------
/tls/status:
get:
tags:
- tls
operationId: tlsStatus
summary: "Returns TLS configuration and its status"
responses:
200:
description: OK
schema:
$ref: "#/definitions/TlsConfig"
/tls/configure:
post:
tags:
- tls
operationId: tlsConfigure
summary: "Updates current TLS configuration"
consumes:
- application/json
parameters:
- in: "body"
name: "body"
description: "TLS configuration JSON"
required: true
schema:
$ref: "#/definitions/TlsConfig"
responses:
200:
description: "TLS configuration and its status"
schema:
$ref: "#/definitions/TlsConfig"
400:
description: "Invalid configuration or unavailable port"
500:
description: "Error occurred while applying configuration"
/tls/validate:
post:
tags:
- tls
operationId: tlsValidate
summary: "Checks if the current TLS configuration is valid"
consumes:
- application/json
parameters:
- in: "body"
name: "body"
description: "TLS configuration JSON"
required: true
schema:
$ref: "#/definitions/TlsConfig"
responses:
200:
description: "TLS configuration and its status"
schema:
$ref: "#/definitions/TlsConfig"
400:
description: "Invalid configuration or unavailable port"
# --------------------------------------------------
# DHCP server methods
# --------------------------------------------------
/dhcp/status:
get:
tags:
- dhcp
operationId: dhcpStatus
summary: "Gets the current DHCP settings and status"
responses:
200:
description: OK
schema:
$ref: "#/definitions/DhcpStatus"
/dhcp/set_config:
post:
tags:
- dhcp
operationId: dhcpSetConfig
summary: "Updates the current DHCP server configuration"
consumes:
- application/json
parameters:
- in: "body"
name: "body"
description: "DHCP configuration JSON"
required: true
schema:
$ref: "#/definitions/DhcpConfig"
responses:
200:
description: OK
/dhcp/find_active_dhcp:
post:
tags:
- dhcp
operationId: checkActiveDhcp
summary: "Searches for an active DHCP server on the network"
responses:
200:
description: OK
schema:
$ref: "#/definitions/DhcpSearchResult"
/dhcp/add_static_lease:
post:
tags:
- dhcp
operationId: dhcpAddStaticLease
summary: "Adds a static lease"
consumes:
- application/json
parameters:
- in: "body"
name: "body"
required: true
schema:
$ref: "#/definitions/DhcpStaticLease"
responses:
200:
description: OK
/dhcp/remove_static_lease:
post:
tags:
- dhcp
operationId: dhcpRemoveStaticLease
summary: "Removes a static lease"
consumes:
- application/json
parameters:
- in: "body"
name: "body"
required: true
schema:
$ref: "#/definitions/DhcpStaticLease"
responses:
200:
description: OK
/dhcp/reset:
post:
tags:
- dhcp
operationId: dhcpReset
summary: "Reset DHCP configuration"
responses:
200:
description: OK
# --------------------------------------------------
# Filtering status methods
# --------------------------------------------------
/filtering/status:
get:
tags:
- filtering
operationId: filteringStatus
summary: 'Get filtering parameters'
responses:
200:
description: OK
schema:
$ref: "#/definitions/FilterStatus"
/filtering/config:
post:
tags:
- filtering
operationId: filteringConfig
summary: 'Set filtering parameters'
parameters:
- in: "body"
name: "body"
required: true
schema:
$ref: "#/definitions/FilterConfig"
responses:
200:
description: OK
/filtering/add_url:
post:
tags:
- filtering
operationId: filteringAddURL
summary: 'Add filter URL or an absolute file path'
consumes:
- application/json
parameters:
- in: "body"
name: "body"
required: true
schema:
$ref: "#/definitions/AddUrlRequest"
responses:
200:
description: OK
/filtering/remove_url:
post:
tags:
- filtering
operationId: filteringRemoveURL
summary: 'Remove filter URL'
consumes:
- application/json
parameters:
- in: "body"
name: "body"
required: true
schema:
$ref: "#/definitions/RemoveUrlRequest"
responses:
200:
description: OK
/filtering/set_url:
post:
tags:
- filtering
operationId: filteringSetURL
summary: 'Set URL parameters'
consumes:
- application/json
parameters:
- in: "body"
name: "body"
schema:
$ref: "#/definitions/FilterSetUrl"
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.
consumes:
- application/json
parameters:
- in: "body"
name: "body"
schema:
$ref: "#/definitions/FilterRefreshRequest"
responses:
200:
description: OK
schema:
$ref: "#/definitions/FilterRefreshResponse"
/filtering/set_rules:
post:
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:
# TODO: move to definitions
type: string
example: '@@||yandex.ru^|'
responses:
200:
description: OK
/filtering/check_host:
get:
tags:
- filtering
operationId: filteringCheckHost
summary: 'Check if host name is filtered'
parameters:
- name: name
in: query
type: string
responses:
200:
description: OK
schema:
$ref: "#/definitions/FilterCheckHostResponse"
# --------------------------------------------------
# Safebrowsing methods
# --------------------------------------------------
/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 control methods
# --------------------------------------------------
/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
# --------------------------------------------------
# Safe search methods
# --------------------------------------------------
/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
# --------------------------------------------------
# Clients list methods
# --------------------------------------------------
/clients:
get:
tags:
- clients
operationId: clientsStatus
summary: 'Get information about configured clients'
responses:
200:
description: OK
schema:
$ref: "#/definitions/Clients"
/clients/add:
post:
tags:
- clients
operationId: clientsAdd
summary: 'Add a new client'
parameters:
- in: "body"
name: "body"
required: true
schema:
$ref: "#/definitions/Client"
responses:
200:
description: OK
/clients/delete:
post:
tags:
- clients
operationId: clientsDelete
summary: 'Remove a client'
parameters:
- in: "body"
name: "body"
required: true
schema:
$ref: "#/definitions/ClientDelete"
responses:
200:
description: OK
/clients/update:
post:
tags:
- clients
operationId: clientsUpdate
summary: 'Update client information'
parameters:
- in: "body"
name: "body"
required: true
schema:
$ref: "#/definitions/ClientUpdate"
responses:
200:
description: OK
/clients/find:
get:
tags:
- clients
operationId: clientsFind
summary: 'Get information about selected clients by their IP address'
parameters:
- name: ip0
in: query
type: string
responses:
200:
description: OK
schema:
$ref: "#/definitions/ClientsFindResponse"
/blocked_services/list:
get:
tags:
- blocked_services
operationId: blockedServicesList
summary: 'Get blocked services list'
responses:
200:
description: OK
schema:
$ref: "#/definitions/BlockedServicesArray"
/blocked_services/set:
post:
tags:
- blocked_services
operationId: blockedServicesSet
summary: 'Set blocked services list'
parameters:
- in: body
name: "body"
schema:
$ref: "#/definitions/BlockedServicesArray"
responses:
200:
description: OK
# --------------------------------------------------
# Rewrite methods
# --------------------------------------------------
/rewrite/list:
get:
tags:
- rewrite
operationId: rewriteList
summary: 'Get list of Rewrite rules'
responses:
200:
description: OK
schema:
$ref: "#/definitions/RewriteList"
/rewrite/add:
post:
tags:
- rewrite
operationId: rewriteAdd
summary: 'Add a new Rewrite rule'
parameters:
- in: "body"
name: "body"
required: true
schema:
$ref: "#/definitions/RewriteEntry"
responses:
200:
description: OK
/rewrite/delete:
post:
tags:
- rewrite
operationId: rewriteDelete
summary: 'Remove a Rewrite rule'
parameters:
- in: "body"
name: "body"
required: true
schema:
$ref: "#/definitions/RewriteEntry"
responses:
200:
description: OK
# --------------------------------------------------
# I18N methods
# --------------------------------------------------
/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:
# TODO: use JSON?
type: string
example: en
responses:
200:
description: OK
/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
# --------------------------------------------------
# First-time install configuration methods
# --------------------------------------------------
/install/get_addresses:
get:
tags:
- install
operationId: installGetAddresses
summary: "Gets the network interfaces information."
responses:
200:
description: OK
schema:
$ref: "#/definitions/AddressesInfo"
/install/check_config:
post:
tags:
- install
operationId: installCheckConfig
summary: "Checks configuration"
parameters:
- in: "body"
name: "body"
description: "Configuration to be checked"
required: true
schema:
$ref: "#/definitions/CheckConfigRequest"
responses:
200:
description: OK
schema:
$ref: "#/definitions/CheckConfigResponse"
400:
description: "Failed to parse JSON or cannot listen on the specified address"
/install/configure:
post:
tags:
- install
operationId: installConfigure
summary: "Applies the initial configuration."
parameters:
- in: "body"
name: "body"
description: "Initial configuration JSON"
required: true
schema:
$ref: "#/definitions/InitialConfiguration"
responses:
200:
description: OK
400:
description: "Failed to parse initial configuration or cannot listen to the specified addresses"
500:
description: "Cannot start the DNS server"
/login:
post:
tags:
- global
operationId: login
summary: "Perform administrator log-in"
consumes:
- application/json
parameters:
- in: "body"
name: "body"
required: true
schema:
$ref: "#/definitions/Login"
responses:
200:
description: OK
/logout:
get:
tags:
- global
operationId: logout
summary: "Perform administrator log-out"
responses:
302:
description: OK
/profile:
get:
tags:
- global
operationId: getProfile
summary: ""
responses:
200:
description: OK
schema:
$ref: "#/definitions/ProfileInfo"
definitions:
ServerStatus:
type: "object"
description: "AdGuard Home server status and configuration"
required:
- "dns_address"
- "dns_port"
- "protection_enabled"
- "querylog_enabled"
- "running"
- "bootstrap_dns"
- "upstream_dns"
- "version"
- "language"
properties:
dns_address:
type: "string"
example: "127.0.0.1"
dns_port:
type: "integer"
format: "int32"
example: 53
minimum: 1
maximum: 65535
protection_enabled:
type: "boolean"
querylog_enabled:
type: "boolean"
running:
type: "boolean"
version:
type: "string"
example: "0.1"
language:
type: "string"
example: "en"
DNSConfig:
type: "object"
description: "Query log configuration"
properties:
bootstrap_dns:
type: "array"
description: 'Bootstrap servers, port is optional after colon. Empty value will reset it to default values'
items:
type: "string"
example:
- "8.8.8.8:53"
- "1.1.1.1:53"
upstream_dns:
type: "array"
description: 'Upstream servers, port is optional after colon. Empty value will reset it to default values'
items:
type: "string"
example:
- "tls://1.1.1.1"
- "tls://1.0.0.1"
protection_enabled:
type: "boolean"
ratelimit:
type: "integer"
blocking_mode:
type: "string"
enum:
- "default"
- "nxdomain"
- "null_ip"
- "custom_ip"
blocking_ipv4:
type: "string"
blocking_ipv6:
type: "string"
edns_cs_enabled:
type: "boolean"
dnssec_enabled:
type: "boolean"
fastest_addr:
type: "boolean"
parallel_requests:
type: "boolean"
description: "If true, parallel queries to all configured upstream servers are enabled"
UpstreamsConfig:
type: "object"
description: "Upstreams configuration"
required:
- "bootstrap_dns"
- "upstream_dns"
properties:
bootstrap_dns:
type: "array"
description: 'Bootstrap servers, port is optional after colon. Empty value will reset it to default values'
items:
type: "string"
example:
- "8.8.8.8:53"
- "1.1.1.1:53"
upstream_dns:
type: "array"
description: 'Upstream servers, port is optional after colon. Empty value will reset it to default values'
items:
type: "string"
example:
- "tls://1.1.1.1"
- "tls://1.0.0.1"
Filter:
type: "object"
description: "Filter subscription info"
required:
- "enabled"
- "id"
- "lastUpdated"
- "name"
- "rulesCount"
- "url"
properties:
enabled:
type: "boolean"
id:
type: "integer"
example: 1234
lastUpdated:
type: "string"
format: "date-time"
example: "2018-10-30T12:18:57+03:00"
name:
type: "string"
example: "AdGuard Simplified Domain Names filter"
rulesCount:
type: "integer"
example: 5912
url:
type: "string"
example: "https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt"
FilterStatus:
type: "object"
description: "Filtering settings"
properties:
enabled:
type: "boolean"
interval:
type: "integer"
filters:
type: "array"
items:
$ref: "#/definitions/Filter"
user_rules:
type: "array"
items:
type: "string"
FilterConfig:
type: "object"
description: "Filtering settings"
properties:
enabled:
type: "boolean"
interval:
type: "integer"
FilterSetUrl:
type: "object"
description: "Filtering URL settings"
properties:
url:
type: "string"
enabled:
type: "boolean"
FilterRefreshRequest:
type: "object"
description: "Refresh Filters request data"
properties:
whitelist:
type: "boolean"
FilterCheckHostResponse:
type: "object"
description: "Check Host Result"
properties:
reason:
type: "string"
description: "DNS filter status"
enum:
- "NotFilteredNotFound"
- "NotFilteredWhiteList"
- "NotFilteredError"
- "FilteredBlackList"
- "FilteredSafeBrowsing"
- "FilteredParental"
- "FilteredInvalid"
- "FilteredSafeSearch"
- "FilteredBlockedService"
- "ReasonRewrite"
filter_id:
type: "integer"
rule:
type: "string"
example: "||example.org^"
description: "Filtering rule applied to the request (if any)"
service_name:
type: "string"
description: "Set if reason=FilteredBlockedService"
cname:
type: "string"
description: "Set if reason=ReasonRewrite"
ip_addrs:
type: "array"
items:
type: "string"
description: "Set if reason=ReasonRewrite"
FilterRefreshResponse:
type: "object"
description: "/filtering/refresh response data"
properties:
updated:
type: "integer"
GetVersionRequest:
type: "object"
description: "/version.json request data"
properties:
recheck_now:
description: "If false, server will check for a new version data only once in several hours"
type: "boolean"
VersionInfo:
type: "object"
description: "Information about the latest available version of AdGuard Home"
properties:
new_version:
type: "string"
example: "v0.9"
announcement:
type: "string"
example: "AdGuard Home v0.9 is now available!"
announcement_url:
type: "string"
example: "https://github.com/AdguardTeam/AdGuardHome/releases/tag/v0.9"
can_autoupdate:
type: "boolean"
Stats:
type: "object"
description: "Server statistics data"
properties:
time_units:
type: "string"
description: "Time units (hours | days)"
example: "hours"
num_dns_queries:
type: "integer"
description: "Total number of DNS queries"
example: 123
num_blocked_filtering:
type: "integer"
description: "Number of requests blocked by filtering rules"
example: 50
num_replaced_safebrowsing:
type: "integer"
description: "Number of requests blocked by safebrowsing module"
example: 5
num_replaced_safesearch:
type: "integer"
description: "Number of requests blocked by safesearch module"
example: 5
num_replaced_parental:
type: "integer"
description: "Number of blocked adult websites"
example: 15
avg_processing_time:
type: "number"
format: "float"
description: "Average time in milliseconds on processing a DNS"
example: 0.34
top_queried_domains:
type: "array"
items:
type: "object"
top_clients:
type: "array"
items:
type: "object"
top_blocked_domains:
type: "array"
items:
type: "object"
dns_queries:
type: "array"
items:
type: "integer"
blocked_filtering:
type: "array"
items:
type: "integer"
replaced_safebrowsing:
type: "array"
items:
type: "integer"
replaced_parental:
type: "array"
items:
type: "integer"
StatsConfig:
type: "object"
description: "Statistics configuration"
properties:
interval:
type: "integer"
description: "Time period to keep data (1 | 7 | 30 | 90)"
DhcpConfig:
type: "object"
description: "Built-in DHCP server configuration"
required:
- "enabled"
- "gateway_ip"
- "subnet_mask"
- "range_start"
- "range_end"
- "lease_duration"
properties:
enabled:
type: "boolean"
gateway_ip:
type: "string"
example: "192.168.1.1"
subnet_mask:
type: "string"
example: "255.255.255.0"
range_start:
type: "string"
example: "192.168.1.2"
range_end:
type: "string"
example: "192.168.10.50"
lease_duration:
type: "string"
example: "12h"
DhcpLease:
type: "object"
description: "DHCP lease information"
required:
- "mac"
- "ip"
- "hostname"
- "expires"
properties:
mac:
type: "string"
example: "00:11:09:b3:b3:b8"
ip:
type: "string"
example: "192.168.1.22"
hostname:
type: "string"
example: "dell"
expires:
type: "string"
format: "date-time"
example: "2017-07-21T17:32:28Z"
DhcpStaticLease:
type: "object"
description: "DHCP static lease information"
required:
- "mac"
- "ip"
- "hostname"
- "expires"
properties:
mac:
type: "string"
example: "00:11:09:b3:b3:b8"
ip:
type: "string"
example: "192.168.1.22"
hostname:
type: "string"
example: "dell"
DhcpStatus:
type: "object"
description: "Built-in DHCP server configuration and status"
required:
- "config"
- "leases"
properties:
config:
$ref: "#/definitions/DhcpConfig"
leases:
type: "array"
items:
$ref: "#/definitions/DhcpLease"
static_leases :
type: "array"
items:
$ref: "#/definitions/DhcpStaticLease"
DhcpSearchResult:
type: "object"
description: "Information about a DHCP server discovered in the current network"
properties:
other_server:
$ref: "#/definitions/DhcpSearchResultOtherServer"
static_ip:
$ref: "#/definitions/DhcpSearchResultStaticIP"
DhcpSearchResultOtherServer:
type: "object"
properties:
found:
type: "string"
description: "yes|no|error"
example: "no"
error:
type: "string"
description: "Set if found=error"
example: ""
DhcpSearchResultStaticIP:
type: "object"
properties:
static:
type: "string"
description: "yes|no|error"
example: "yes"
ip:
type: "string"
description: "Set if static=no"
example: ""
DnsAnswer:
type: "object"
description: "DNS answer section"
properties:
ttl:
type: "integer"
example: 55
type:
type: "string"
example: "A"
value:
type: "string"
example: "217.69.139.201"
DnsQuestion:
type: "object"
description: "DNS question section"
properties:
class:
type: "string"
example: "IN"
host:
type: "string"
example: "example.org"
type:
type: "string"
example: "A"
AddUrlRequest:
type: "object"
description: "/add_url request data"
properties:
name:
type: "string"
url:
description: "URL or an absolute path to the file containing filtering rules"
type: "string"
example: "https://filters.adtidy.org/windows/filters/15.txt"
RemoveUrlRequest:
type: "object"
description: "/remove_url request data"
properties:
url:
description: "Previously added URL containing filtering rules"
type: "string"
example: "https://filters.adtidy.org/windows/filters/15.txt"
QueryLogItem:
type: "object"
description: "Query log item"
properties:
answer:
type: "array"
items:
$ref: "#/definitions/DnsAnswer"
original_answer:
type: "array"
description: "Answer from upstream server (optional)"
items:
$ref: "#/definitions/DnsAnswer"
answer_dnssec:
type: "boolean"
client:
type: "string"
example: "192.168.0.1"
elapsedMs:
type: "string"
example: "54.023928"
question:
$ref: "#/definitions/DnsQuestion"
filterId:
type: "integer"
example: 123123
description: "In case if there's a rule applied to this DNS request, this is ID of the filter that rule belongs to."
rule:
type: "string"
example: "||example.org^"
description: "Filtering rule applied to the request (if any)"
reason:
type: "string"
description: "DNS filter status"
enum:
- "NotFilteredNotFound"
- "NotFilteredWhiteList"
- "NotFilteredError"
- "FilteredBlackList"
- "FilteredSafeBrowsing"
- "FilteredParental"
- "FilteredInvalid"
- "FilteredSafeSearch"
- "FilteredBlockedService"
- "ReasonRewrite"
service_name:
type: "string"
description: "Set if reason=FilteredBlockedService"
status:
type: "string"
description: "DNS response status"
example: "NOERROR"
time:
type: "string"
description: "DNS request processing start time"
example: "2018-11-26T00:02:41+03:00"
QueryLog:
type: "object"
description: "Query log"
properties:
oldest:
type: "string"
example: "2018-11-26T00:02:41+03:00"
data:
type: "array"
items:
$ref: "#/definitions/QueryLogItem"
QueryLogConfig:
type: "object"
description: "Query log configuration"
properties:
enabled:
type: "boolean"
description: "Is query log enabled"
interval:
type: "integer"
description: "Time period to keep data (1 | 7 | 30 | 90)"
anonymize_client_ip:
type: "boolean"
description: "Anonymize clients' IP addresses"
TlsConfig:
type: "object"
description: "TLS configuration settings and status"
properties:
# TLS configuration
enabled:
type: "boolean"
example: "true"
description: "enabled is the encryption (DOT/DOH/HTTPS) status"
server_name:
type: "string"
example: "example.org"
description: "server_name is the hostname of your HTTPS/TLS server"
force_https:
type: "boolean"
example: "true"
description: "if true, forces HTTP->HTTPS redirect"
port_https:
type: "integer"
format: "int32"
example: 443
description: "HTTPS port. If 0, HTTPS will be disabled."
port_dns_over_tls:
type: "integer"
format: "int32"
example: 853
description: "DNS-over-TLS port. If 0, DOT will be disabled."
certificate_chain:
type: "string"
description: "Base64 string with PEM-encoded certificates chain"
private_key:
type: "string"
description: "Base64 string with PEM-encoded private key"
certificate_path:
type: "string"
description: "Path to certificate file"
private_key_path:
type: "string"
description: "Path to private key file"
# Below goes validation fields
valid_cert:
type: "boolean"
example: "true"
description: "valid_cert is true if the specified certificates chain is a valid chain of X509 certificates"
valid_chain:
type: "boolean"
example: "true"
description: "valid_chain is true if the specified certificates chain is verified and issued by a known CA"
subject:
type: "string"
example: "CN=example.org"
description: "subject is the subject of the first certificate in the chain"
issuer:
type: "string"
example: "CN=Let's Encrypt Authority X3,O=Let's Encrypt,C=US"
description: "issuer is the issuer of the first certificate in the chain"
not_before:
type: "string"
example: "2019-01-31T10:47:32Z"
description: "not_before is the NotBefore field of the first certificate in the chain"
not_after:
type: "string"
example: "2019-05-01T10:47:32Z"
description: "not_after is the NotAfter field of the first certificate in the chain"
dns_names:
type: "array"
items:
type: "string"
description: "dns_names is the value of SubjectAltNames field of the first certificate in the chain"
example:
- "*.example.org"
valid_key:
type: "boolean"
example: "true"
description: "valid_key is true if the key is a valid private key"
key_type:
type: "string"
example: "RSA"
description: "key_type is either RSA or ECDSA"
warning_validation:
type: "string"
example: "You have specified an empty certificate"
description: "warning_validation is a validation warning message with the issue description"
valid_pair:
type: "boolean"
example: "true"
description: "valid_pair is true if both certificate and private key are correct"
NetInterface:
type: "object"
description: "Network interface info"
properties:
flags:
type: "string"
example: "up|broadcast|multicast"
hardware_address:
type: "string"
example: "52:54:00:11:09:ba"
mtu:
type: "integer"
format: "int32"
example: 1500
name:
type: "string"
example: "eth0"
ip_addresses:
type: "array"
items:
type: "string"
example:
- "127.0.0.1"
AddressInfo:
type: "object"
description: "Port information"
properties:
ip:
type: "string"
example: "127.0.0.1"
port:
type: "integer"
format: "int32"
example: 53
AddressesInfo:
type: "object"
description: "AdGuard Home addresses configuration"
properties:
dns_port:
type: "integer"
format: "int32"
example: 53
web_port:
type: "integer"
format: "int32"
example: 80
interfaces:
type: "object"
description: "Network interfaces dictionary (key is the interface name)"
additionalProperties:
$ref: "#/definitions/NetInterface"
ProfileInfo:
type: "object"
description: "Information about the current user"
properties:
name:
type: "string"
Client:
type: "object"
description: "Client information"
properties:
name:
type: "string"
description: "Name"
example: "localhost"
ids:
type: "array"
description: "IP, CIDR or MAC address"
items:
type: "string"
use_global_settings:
type: "boolean"
filtering_enabled:
type: "boolean"
parental_enabled:
type: "boolean"
safebrowsing_enabled:
type: "boolean"
safesearch_enabled:
type: "boolean"
use_global_blocked_services:
type: "boolean"
blocked_services:
type: "array"
items:
type: "string"
upstreams:
type: "array"
items:
type: "string"
ClientAuto:
type: "object"
description: "Auto-Client information"
properties:
ip:
type: "string"
description: "IP address"
example: "127.0.0.1"
name:
type: "string"
description: "Name"
example: "localhost"
source:
type: "string"
description: "The source of this information"
example: "etc/hosts"
ClientUpdate:
type: "object"
description: "Client update request"
properties:
name:
type: "string"
data:
$ref: "#/definitions/Client"
ClientDelete:
type: "object"
description: "Client delete request"
properties:
name:
type: "string"
ClientsFindResponse:
type: "array"
description: "Response to clients find operation"
items:
$ref: "#/definitions/ClientsFindEntry"
ClientsFindEntry:
type: "object"
properties:
"1.2.3.4":
items:
$ref: "#/definitions/Client"
Clients:
type: "object"
properties:
clients:
$ref: "#/definitions/ClientsArray"
auto_clients:
$ref: "#/definitions/ClientsAutoArray"
ClientsArray:
type: "array"
items:
$ref: "#/definitions/Client"
description: "Clients array"
ClientsAutoArray:
type: "array"
items:
$ref: "#/definitions/ClientAuto"
description: "Auto-Clients array"
RewriteList:
type: "array"
items:
$ref: "#/definitions/RewriteEntry"
description: "Rewrite rules array"
RewriteEntry:
type: "object"
description: "Rewrite rule"
properties:
domain:
type: "string"
description: "Domain name"
example: "example.org"
answer:
type: "string"
description: "value of A, AAAA or CNAME DNS record"
example: "127.0.0.1"
BlockedServicesArray:
type: "array"
items:
type: "string"
CheckConfigRequest:
type: "object"
description: "Configuration to be checked"
properties:
dns:
$ref: "#/definitions/CheckConfigRequestInfo"
web:
$ref: "#/definitions/CheckConfigRequestInfo"
set_static_ip:
type: "boolean"
example: false
CheckConfigRequestInfo:
type: "object"
properties:
ip:
type: "string"
example: "127.0.0.1"
port:
type: "integer"
format: "int32"
example: 53
autofix:
type: "boolean"
example: false
CheckConfigResponse:
type: "object"
properties:
dns:
$ref: "#/definitions/CheckConfigResponseInfo"
web:
$ref: "#/definitions/CheckConfigResponseInfo"
static_ip:
$ref: "#/definitions/CheckConfigStaticIpInfo"
CheckConfigResponseInfo:
type: "object"
properties:
status:
type: "string"
example: ""
can_autofix:
type: "boolean"
example: false
CheckConfigStaticIpInfo:
type: "object"
properties:
static:
type: "string"
example: "no"
description: "Can be: yes, no, error"
ip:
type: "string"
example: "192.168.1.1"
description: "Current dynamic IP address. Set if static=no"
error:
type: "string"
example: ""
description: "Error text. Set if static=error"
InitialConfiguration:
type: "object"
description: "AdGuard Home initial configuration (for the first-install wizard)"
properties:
dns:
$ref: "#/definitions/AddressInfo"
web:
$ref: "#/definitions/AddressInfo"
username:
type: "string"
description: "Basic auth username"
example: "admin"
password:
type: "string"
description: "Basic auth password"
example: "password"
Login:
type: "object"
description: "Login request data"
properties:
username:
type: "string"
description: "User name"
password:
type: "string"
description: "Password"
Reference in New Issue View Git Blame Copy Permalink