blocky API

Name: blocky API API
Brand: blocky API
Availability: InStock

★ Only Publicly Available OpenAPI DocumentCloud InfrastructureNetworkingnone6 EndpointsREST

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.

Quickstart

Get started with blocky API in minutes using your preferred integration method.

# Add to your MCP client config (Claude Desktop, Cursor, Windsurf)
{
  "jentic": {
    "url": "https://api.jentic.com/mcp",
    "auth": "oauth"
  }
}

# Then ask your agent:
"control a self-hosted DNS ad-blocker"

# → Jentic returns the GET /events tool with parameter schema, agent executes.

Capabilities

What an agent can do with blocky API 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

GET STARTED

Start building with blocky API API

Explore with Jentic

View OpenAPI Document

Jentic publishes the only available OpenAPI document for blocky API, keeping it validated and agent-ready.

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.

Use Cases

Patterns agents use blocky API 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

Why though Jentic?

Three things that make agents converge on Jentic-routed access.

Credential isolation

Blocky has no built-in auth, so the sensitive value is the resolver's base URL plus any reverse-proxy credential (shared API key or basic-auth header) you have placed in front of it. Jentic stores those values encrypted in the MAXsystem vault and injects them at execution time, so the agent never sees the raw URL or proxy secret in its context.

Intent-based discovery

Agents search by intent — for example 'pause DNS blocking for 30 minutes' or 'flush the DNS cache' — and Jentic returns the matching Blocky operation (such as disableBlocking or cacheFlush) along with its parameter schema, so the agent can call the right endpoint without browsing the spec.

Time to first call

Direct Blocky integration: a few hours to read the spec, write a small client, handle the per-group duration parameter format, and wire up cache and list operations. Through Jentic: under 30 minutes — search, load, execute.

Related APIs

Alternatives and complements available in the Jentic catalogue.

Alternative

NextDNS

NextDNS is a hosted DNS-level ad-blocker and filtering service, where Blocky is the equivalent self-hosted resolver

Choose NextDNS when the user wants a managed DNS filter with no infrastructure to run; choose Blocky when they require local-network deployment, full data privacy, or no third-party telemetry.

Complementary

Cloudflare

Cloudflare provides authoritative DNS, DoH endpoints, and security filtering that can sit upstream of a self-hosted Blocky resolver

Use Cloudflare alongside Blocky when the agent needs to manage public DNS records or upstream resolver configuration; Blocky handles the local recursive query and per-group filtering.

Complementary

NS1

NS1 manages authoritative DNS zones and traffic-steering policies that can complement Blocky's local resolution

Reach for NS1 when authoritative DNS, geo-routing, or traffic policies are needed; Blocky handles the local-network recursive resolver and ad/tracker blocking layer.

FAQs

Specific to using blocky API 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 at https://app.jentic.com/sign-up.

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 the Jentic vault 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.