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
                            bootstrap_dns: 8.8.8.8:53
                            upstream_dns:
                              - 1.1.1.1
                              - 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
    /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