0xerr0r blocky API
Agent-ready OpenAPI document · curated by JenticCloud InfrastructureNetworkingnone6 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For 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.
Use for: I need to disable Blocky ad-blocking for 30 minutes on the kids group, Re-enable DNS blocking after a maintenance window, Check whether Blocky is currently blocking DNS queries for any group, Refresh all Blocky deny lists after updating the source URLs
Not supported: 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.
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.
Install Jentic One Beta
Connect the blocky API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the blocky API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2F0xerr0r.github.io%2Fblocky" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2F0xerr0r.github.io%2Fblocky" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with blocky API.
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
Patterns agents use blocky API for, with concrete tasks.
★ 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.
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.
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.
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.
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
6 endpoints — jentic publishes the only available openapi specification for blocky api, keeping it validated and agent-ready.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using blocky API through Jentic.
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.
GET STARTED