Use the decision API · Blockinator

Check authentication

bash

curl -i -H 'X-Api-Key: YOUR_KEY' \
  http://BLOCKINATOR-HOST:8080/api/v1/ping

A resolver API key authenticates the policy API. Administrator sessions protect management functions; a policy API key alone cannot access administrator runtime diagnostics.

Ask for a decision

bash

curl -sS http://BLOCKINATOR-HOST:8080/api/v1/decision \
  -H 'X-Api-Key: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"server_id":"dns-1","client":{"ip":"192.0.2.42","port":53012},"dns":{"questions":[{"name":"ads.example.net","type":"A","class":"IN"}]}}'

The request above uses documentation-range client data. The result depends on the policies in your installation.

Read the result

Example blocked response

{
  "block": true,
  "reason": "blocklist_match",
  "matched_scope": "Guest Wi-Fi",
  "matched_list": "Advertising",
  "matched_domain": "ads.example.net",
  "response_mode": "nxdomain"
}

Blockinator returns the decision. The resolver plugin enforces it and generates the DNS response. Supported plugin modes include NXDOMAIN, REFUSED, NODATA, and zero-address A/AAAA responses.

Limits and errors

Policy bodies are limited to 256 KiB, with 1–16 questions per request. Invalid payloads return 422; oversized bodies return 413. Multiple questions are evaluated in order, returning the first blocking decision or, if none block, the first allow decision.

Read the upstream documentation ↗

CONTINUE EXPLORINGInstall Blockinator →