canonical: https://jentic.com/apis/0xerr0r.github.io/blocky

# 0xerr0r blocky API

Jentic publishes the only available OpenAPI specification for blocky API, keeping it validated and agent-ready. Blocky is a self-hosted DNS proxy and ad-blocker for local networks, written in Go, that filters DNS queries against allow/deny lists, supports DNS over UDP, TCP, HTTPS, and TLS, and exposes a small REST control plane for runtime operations. Through this REST API, operators and agents can toggle blocking on or off, inspect current blocking status, refresh external block lists, flush the DNS response cache, and run ad-hoc DNS queries against the resolver. The API is designed for local-network deployments such as Raspberry Pi, Docker, or Kubernetes, where Blocky acts as the primary DNS resolver for clients, smart home devices, or family-group profiles.

## For AI agents

Control a self-hosted Blocky DNS proxy and ad-blocker: toggle blocking, refresh block lists, flush the DNS cache, and run DNS queries against the resolver.

## Scope

Does not handle authoritative DNS hosting, DNS record management, or public DNS resolution - use for controlling a self-hosted Blocky DNS proxy and ad-blocker only.

## Capabilities

- Pause DNS-level ad and tracker blocking for a specific duration or set of client groups
- Re-enable blocking immediately after maintenance, troubleshooting, or a temporary allowlist window
- Inspect the current blocking state, including which groups are disabled and seconds until auto re-enable
- Trigger a refresh of all external allow and deny lists without restarting the Blocky resolver
- Flush the DNS response cache to force fresh upstream resolution after configuration changes
- Run an ad-hoc DNS query through Blocky and inspect the response code, reason, and whether it was blocked or cached

## Use cases

### Temporary ad-blocking pause for a client group

Pause Blocky's DNS-level ad and tracker blocking for a specific group of devices, such as a kids profile or smart home segment, without affecting the rest of the network. The `/blocking/disable` endpoint accepts a duration string (for example 5m or 1h) and a comma-separated list of groups, so operators can grant a short allowlist window and let blocking automatically re-engage afterward. This is useful when a streaming app, captive portal, or smart device is being incorrectly blocked and needs a brief unblocked window to function.

Example prompt: Call GET `/blocking/disable` with duration=30m and groups=kids, then call GET `/blocking/status` and confirm that autoEnableInSec is around 1800 and 'kids' appears in disabledGroups.

### Refresh deny and allow lists after a config change

After updating the URLs or contents of external allow or deny lists, operators need Blocky to reload them without restarting the resolver and dropping its DNS cache. The `/lists/refresh` endpoint reloads all configured lists in place. This keeps Blocky's filtering up to date with new threat feeds, advertising domains, or family-friendly lists while preserving uptime as the network's primary DNS resolver.

Example prompt: Call POST `/lists/refresh` and check that the response status is 200; if it returns 500, capture the plain-text error body and surface it to the operator for triage.

### Diagnose why a domain is being blocked

When a user reports that a website or service is broken, operators can use Blocky's /query endpoint to perform a DNS lookup through the resolver and inspect exactly how Blocky handled it. The response includes the return code, the response itself, the response type (such as CACHED or BLOCKED), and Blocky's internal reason for the resolution. This lets operators quickly distinguish between a denied domain, an upstream failure, and a stale cache entry without tailing logs on the host.

Example prompt: Call POST /query with body {"query": "ads.example.com", "type": "A"} and report the responseType and reason fields back to the user so they can see whether the domain was BLOCKED, CACHED, or RESOLVED.

### AI agent operations playbook for self-hosted DNS

An AI agent managing a home or small-office network can use Blocky's REST control plane through Jentic to run operations playbooks: pause blocking when guests join a video call, refresh deny lists on a schedule, flush the cache after upstream resolver changes, and verify the current blocking state before and after each action. Because Blocky has no built-in authentication and is intended for local networks, Jentic stores the resolver's base URL and any reverse-proxy credentials in its vault and lets the agent target operations by intent rather than memorising the path layout.

Example prompt: Search Jentic for 'control a self-hosted DNS ad-blocker', load the disableBlocking and blockingStatus operations, and execute a 1-hour pause for the 'guests' group followed by a status check that confirms the pause took effect.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/blocking/disable` | Disable blocking for a duration and optional groups |
| GET | `/blocking/enable` | Re-enable blocking immediately |
| GET | `/blocking/status` | Get current blocking status and disabled groups |
| POST | `/lists/refresh` | Reload all external allow and deny lists |
| POST | `/cache/flush` | Clear the DNS response cache |
| POST | `/query` | Perform a DNS query through Blocky |

## Key resources

- **blocking** — Enable, disable, and inspect the DNS query blocking state, including per-group pauses with a duration window and auto re-enable timer.
- **lists** — Refresh external allow and deny lists at runtime so Blocky picks up updated filter sources without a restart.
- **cache** — Flush the DNS response cache to force fresh upstream resolution after configuration or upstream changes.
- **query** — Run an ad-hoc DNS query through the Blocky resolver and inspect the response code, response type, and reason for the resolution.

## Why Jentic

- **Setup:** Wiring Blocky by hand means pointing at the right self-hosted resolver base URL and handling any reverse-proxy credential you placed in front of it yourself, since Blocky ships no built-in auth. Through Jentic you install once, import the blocky API from the API Directory, store the resolver URL and any proxy secret once, and your agent calls it.
- **Permission scoping:** Blocky exposes control operations rather than per-resource ids, so limit the agent to the operations it needs, such as checking blocking status or refreshing lists, and leave out state-changing calls like disabling blocking or flushing the cache unless you add them. You choose the allowed set, so the agent only runs the operations you pick.
- **Credential handling:** The resolver URL and any reverse-proxy credential are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'pause DNS blocking' or 'flush the DNS cache', and Jentic returns the matching Blocky operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **NextDNS** — NextDNS is a hosted DNS-level ad-blocker and filtering service, where Blocky is the equivalent self-hosted resolver
- **Cloudflare** — Cloudflare provides authoritative DNS, DoH endpoints, and security filtering that can sit upstream of a self-hosted Blocky resolver
- **NS1** — NS1 manages authoritative DNS zones and traffic-steering policies that can complement Blocky's local resolution

## FAQ

### Why is there no official OpenAPI spec for blocky API?

0xERR0R, the maintainer of Blocky, does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call blocky API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the blocky API use?

The Blocky REST API itself has no authentication scheme defined in the spec - it is intended to listen on a trusted local network or behind a reverse proxy. When you call it through Jentic, the resolver's base URL and any reverse-proxy credentials (such as a shared API key or basic-auth header you have placed in front of Blocky) are stored encrypted in your Jentic One instance and injected at execution time, so they never appear in the agent's prompt or logs.

### Can I pause ad-blocking for just one group of devices with the blocky API?

Yes. The GET `/blocking/disable` endpoint accepts a 'duration' query parameter (for example 5m, 1h, or 5m30s) and a 'groups' query parameter as a comma-separated list of group names. Only the named groups are disabled; if you omit 'groups', all groups are disabled. After the duration elapses, blocking automatically re-engages, and you can inspect the remaining time via GET `/blocking/status.`

### What are the rate limits for the blocky API?

Blocky does not document rate limits in its OpenAPI spec, and because it runs as a self-hosted resolver on your own hardware (Docker, Raspberry Pi, or Kubernetes), the practical ceiling is whatever your host can handle. For control-plane endpoints like `/lists/refresh` and `/cache/flush`, treat them as occasional maintenance calls rather than per-request operations - refreshing block lists is I/O heavy and is typically done on a schedule, not on every event.

### How do I run a test DNS query through blocky API using Jentic?

Search Jentic for 'run a DNS query through blocky', load the 'query' operation, and execute it with a body like {"query": "example.com", "type": "A"}. The response includes the return code, the response itself, the responseType (such as CACHED or BLOCKED), and Blocky's internal reason - useful for diagnosing whether a domain was filtered by a deny list or resolved upstream. Install with pip install jentic to call this from Python.

### Is the blocky API free to use?

Yes. Blocky is open source under the Apache 2.0 license and is free to self-host. There are no per-call fees because the API runs on your own infrastructure; your only costs are the hardware and bandwidth you provide.

### How do I refresh Blocky's deny lists without restarting the resolver?

Call POST `/lists/refresh` through Jentic. Blocky reloads all configured allow and deny lists in place and returns 200 on success or 500 with a plain-text error body if a source could not be fetched. Because the resolver does not restart, the DNS cache and active connections are preserved.

### Can I limit what my agent is allowed to do with the Blocky API?

Yes. Because Jentic One is self-hosted, you decide which of Blocky's control operations the agent can call and which credentials it uses. Since the API exposes operations rather than per-resource ids, you can allow read-only calls like checking blocking status or running a test DNS query while leaving out state-changing operations such as disabling blocking, refreshing lists, or flushing the cache.