{"owner":"0xERR0R","repo":"blocky","hasSpec":true,"specFile":"docs/api/openapi.yaml","branch":"HEAD","format":"yaml","version":"3.x (YAML)","title":"blocky","description":"","endpoints":[],"spec":"openapi: 3.1.1\ninfo:\n  title: blocky API\n  description: >-\n    REST API for Blocky, a DNS proxy and ad-blocker for the local network.\n\n\n    For features, configuration, and installation see the\n    [project documentation](https://0xerr0r.github.io/blocky/) and the\n    [README](https://github.com/0xERR0R/blocky/blob/main/README.md).\n  contact:\n    name: blocky@github\n    url: https://github.com/0xERR0R/blocky\n  license:\n    name: Apache 2.0\n    url: http://www.apache.org/licenses/LICENSE-2.0.html\n  version: '1.0'\nservers:\n  - url: /api\npaths:\n  /blocking/disable:\n    get:\n      operationId: disableBlocking\n      tags:\n        - blocking\n      summary: Disable blocking\n      description: disable the blocking status\n      parameters:\n        - name: duration\n          in: query\n          description: 'duration of blocking (Example: 300s, 5m, 1h, 5m30s)'\n          schema:\n            type: string\n        - name: groups\n          in: query\n          description: groups to disable (comma separated). If empty, disable all groups\n          schema:\n            type: string\n      responses:\n        '200':\n          description: Blocking is disabled\n        '400':\n          description: Bad request (e.g. unknown group)\n          content:\n            text/plain:\n              schema:\n                type: string\n                example: Bad request\n  /blocking/enable:\n    get:\n      operationId: enableBlocking\n      tags:\n        - blocking\n      summary: Enable blocking\n      description: enable the blocking status\n      responses:\n        '200':\n          description: Blocking is enabled\n  /blocking/status:\n    get:\n      operationId: blockingStatus\n      tags:\n        - blocking\n      summary: Blocking status\n      description: get current blocking status\n      responses:\n        '200':\n          description: Returns current blocking status\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/api.BlockingStatus'\n  /lists/refresh:\n    post:\n      operationId: listRefresh\n      tags:\n        - lists\n      summary: List refresh\n      description: Refresh all lists\n      responses:\n        '200':\n          description: Lists were reloaded\n        '500':\n          description: List refresh error\n          content:\n            text/plain:\n              schema:\n                type: string\n                example: Error text\n  /query:\n    post:\n      operationId: query\n      tags:\n        - query\n      summary: Performs DNS query\n      description: Performs DNS query\n      requestBody:\n        description: query data\n        content:\n          application/json:\n            schema:\n              $ref: '#/components/schemas/api.QueryRequest'\n        required: true\n      responses:\n        '200':\n          description: query was executed\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/api.QueryResult'\n        '400':\n          description: Wrong request format\n          content:\n            text/plain:\n              schema:\n                type: string\n                example: Bad request\n  /cache/flush:\n    post:\n      operationId: cacheFlush\n      tags:\n        - cache\n      summary: Clears the DNS response cache\n      description: Removes all DNS responses from cache\n      responses:\n        '200':\n          description: All caches cleared\n  /stats:\n    get:\n      operationId: getStats\n      tags:\n        - stats\n      summary: DNS statistics\n      description: >-\n        In-memory statistics over a rolling 24h window. Requires statistics to be\n        enabled in the configuration; returns 503 otherwise. Independent of Prometheus.\n        All timestamps (start, end, perHour[].hour) are returned in UTC (RFC 3339,\n        `Z` suffix).\n      responses:\n        '200':\n          description: Current statistics\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/api.Stats'\n        '503':\n          description: Statistics are disabled\n          content:\n            text/plain:\n              schema:\n                type: string\n                example: statistics are disabled\ncomponents:\n  schemas:\n    api.BlockingStatus:\n      type: object\n      properties:\n        autoEnableInSec:\n          type: integer\n          minimum: 0\n          description: >-\n            If blocking is temporary disabled: amount of seconds until blocking\n            will be enabled\n        disabledGroups:\n          type: array\n          description: Disabled group names\n          items:\n            type: string\n        enabled:\n          type: boolean\n          description: True if blocking is enabled\n      required:\n        - enabled\n    api.QueryRequest:\n      type: object\n      properties:\n        query:\n          type: string\n          description: query for DNS request\n        type:\n          type: string\n          description: request type (A, AAAA, ...)\n      required:\n        - query\n        - type\n    api.QueryResult:\n      type: object\n      properties:\n        reason:\n          type: string\n          description: blocky reason for resolution\n        response:\n          type: string\n          description: actual DNS response\n        responseType:\n          type: string\n          description: response type (CACHED, BLOCKED, ...)\n        returnCode:\n          type: string\n          description: DNS return code (NOERROR, NXDOMAIN, ...)\n      required:\n        - reason\n        - response\n        - responseType\n        - returnCode\n    api.Stats:\n      type: object\n      description: In-memory DNS statistics snapshot.\n      properties:\n        start:\n          type: string\n          format: date-time\n          description: Start of the covered window for the windowed fields (not the gauges). UTC (RFC 3339).\n        end:\n          type: string\n          format: date-time\n          description: Snapshot time. UTC (RFC 3339).\n        summary:\n          $ref: '#/components/schemas/api.StatsSummary'\n        byResponseType:\n          type: object\n          additionalProperties:\n            type: integer\n          description: Raw per-RType counts over the window (CACHED, BLOCKED, ...).\n        byQueryType:\n          type: object\n          additionalProperties:\n            type: integer\n          description: Counts per DNS query type over the window (A, AAAA, ...).\n        byResponseCode:\n          type: object\n          additionalProperties:\n            type: integer\n          description: Counts per DNS response code over the window (NOERROR, NXDOMAIN, ...).\n        perHour:\n          type: array\n          description: Per-hour time series over the window.\n          items:\n            $ref: '#/components/schemas/api.HourPoint'\n        topDomains:\n          type: array\n          items:\n            $ref: '#/components/schemas/api.NameCount'\n        topBlockedDomains:\n          type: array\n          items:\n            $ref: '#/components/schemas/api.NameCount'\n        topClients:\n          type: array\n          items:\n            $ref: '#/components/schemas/api.NameCount'\n        lists:\n          $ref: '#/components/schemas/api.ListCounts'\n        cache:\n          $ref: '#/components/schemas/api.CacheStats'\n      required:\n        - start\n        - end\n        - summary\n        - byResponseType\n        - byQueryType\n        - byResponseCode\n        - perHour\n        - topDomains\n        - topBlockedDomains\n        - topClients\n        - lists\n        - cache\n    api.StatsSummary:\n      type: object\n      description: Curated outcome categories over the window (server computes the mapping).\n      properties:\n        queries:\n          type: integer\n          description: Total queries received in the window.\n        cached:\n          type: integer\n        forwarded:\n          type: integer\n        blocked:\n          type: integer\n          description: >-\n            Real blocks: denylist hits (BLOCKED) and DNS rebinding-protection hits (REBIND).\n            Excludes query-type filtered and NOTFQDN responses.\n        filtered:\n          type: integer\n          description: >-\n            Query-type filtered (e.g. AAAA via filtering.queryTypes) and NOTFQDN responses.\n            These are not blocks.\n        local:\n          type: integer\n        dropped:\n          type: integer\n        errors:\n          type: integer\n          description: >-\n            Queries that did not resolve: a resolver returned an error, or the answer\n            failed DNSSEC validation (BOGUS). Not blocks.\n        avgResponseMs:\n          type: integer\n        cacheHitRate:\n          type: number\n          format: double\n      required:\n        - queries\n        - cached\n        - forwarded\n        - blocked\n        - filtered\n        - local\n        - dropped\n        - errors\n        - avgResponseMs\n        - cacheHitRate\n    api.NameCount:\n      type: object\n      properties:\n        name:\n          type: string\n        count:\n          type: integer\n      required:\n        - name\n        - count\n    api.HourPoint:\n      type: object\n      properties:\n        hour:\n          type: string\n          format: date-time\n          description: Start of the hour bucket. UTC (RFC 3339).\n        queries:\n          type: integer\n        blocked:\n          type: integer\n          description: Real blocks in this hour, same definition as summary.blocked.\n        filtered:\n          type: integer\n          description: Query-type filtered / NOTFQDN responses in this hour, same definition as summary.filtered.\n      required:\n        - hour\n        - queries\n        - blocked\n        - filtered\n    api.ListCounts:\n      type: object\n      description: Current per-group list entry counts (point-in-time, not windowed).\n      properties:\n        denylist:\n          type: object\n          additionalProperties:\n            type: integer\n        allowlist:\n          type: object\n          additionalProperties:\n            type: integer\n      required:\n        - denylist\n        - allowlist\n    api.CacheStats:\n      type: object\n      description: Current cache state (point-in-time, not windowed).\n      properties:\n        entries:\n          type: integer\n          description: Current number of entries in the result cache.\n      required:\n        - entries\n"}