Preferred
Bearer header
Send Authorization: Bearer {key} with API requests. Keep the key out of copied URLs and browser history.
Developer documentation
Blocklist API
Find reviewed service IDs, combine them into a list, and request a format that preserves the scope of each rule.
Authentication
Choose the credential for your client.
Create a read-only key under Feeds and keys for API calls. Use a header whenever your client supports it.
For URL-only clients
One apiKey parameter
Some DNS tools need a query credential. Treat it as exposed if it is shared because it may persist in history, logs, backups, or configuration.
Saved subscriptions
Scoped feed URLs
Where subscriptions are enabled, issue a link for a saved list in Feeds and keys. The link grants access to that list in the format you chose. Treat the full URL like a password.
An inline request
Start with a reviewed service ID.
Find an ID with GET /api/catalog. Substitute it below to retrieve a plain-domain list for exact-host rules.
GET /api/blocklist?services={service-id}&format=domains&aggression=conservative
For a saved list, use its stable ID in list instead of services. Request /api/blocklist/metadata with the same selection for versions, scope, and warnings.
Response contract
Errors explain why a request failed.
Unsupported services, incompatible formats, invalid settings, expired credentials, and inaccessible lists return an explicit failure. A generation failure never becomes an empty successful list, a substituted service, or a broader rule.
Metadata and raw blocklist output remain separate so DNS clients do not receive prose in a list.