Quick Start
Get up and running with the DNS Filtering API in minutes. Start classifying domains, looking up content categories and enforcing web filtering policies with enterprise-grade speed and accuracy.
https://api.dnsfilteringservice.com/v1
Your First Request
curl -X POST "https://api.dnsfilteringservice.com/v1/domain/lookup" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain":"example.com"}'Authentication
Every request must include your API key in the Authorization header as a Bearer token. Generate and manage keys from your dashboard.
Authorization: Bearer YOUR_API_KEYBase URL & Rate Limits
All endpoints are served over HTTPS. Responses are JSON. Rate limits scale with your plan.
| Plan | Requests / second | Monthly Quota |
|---|---|---|
| Free | 5 | 10,000 |
| Starter | 50 | 1,000,000 |
| Business | 200 | 10,000,000 |
| Enterprise | Custom | Unlimited |
Domain Lookup
Classify a single domain. Returns primary and secondary categories, and recommended filtering action.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | Fully qualified domain name to classify (e.g. example.com) |
include_subdomains | boolean | No | Analyze subdomains separately (default: false) |
include_metadata | boolean | No | Include extended category metadata (default: true) |
Example Request
const response = await fetch('https://api.dnsfilteringservice.com/v1/domain/lookup', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
domain: 'example.com',
include_metadata: true
})
});
const data = await response.json();
console.log(data);Example Response
{
"domain": "example.com",
"primary_category": "Business & Services",
"secondary_categories": ["Technology", "Reference"],
"category_id": 42,
"recommended_action": "allow",
"last_updated": "2026-04-15T08:32:11Z"
}Bulk Domain Scan
Classify up to 1,000 domains in a single request. Ideal for log processing, firewall rule generation, and content filtering pipelines.
import requests
response = requests.post(
"https://api.dnsfilteringservice.com/v1/domain/bulk",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"domains": ["example.com", "google.com", "blocked-site.xyz"]}
)
for item in response.json()["results"]:
print(item["domain"], "->", item["primary_category"])Category Detail Lookup
Detailed category lookup for a domain. Returns full classification data including all matched categories, sub-categories, and content type metadata.
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.dnsfilteringservice.com/v1/category/example-domain.com"{
"domain": "example-domain.com",
"categories": ["News & Media", "Technology"],
"sub_categories": ["Tech News", "Software Reviews"],
"first_seen": "2026-04-09T14:20:08Z",
"last_updated": "2026-04-18T03:12:47Z",
"content_language": "en"
}Category List
Retrieve the full list of 58 supported filtering categories and their IDs. Useful when building policy UIs or mapping internal rules.
Policy Check
Evaluate whether a domain should be allowed or blocked based on a named policy ID configured in your tenant.
curl -X POST "https://api.dnsfilteringservice.com/v1/policy/check" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain":"facebook.com","policy_id":"corp_strict"}'Response Codes
| Code | Meaning |
|---|---|
200 | OK - request succeeded |
400 | Bad Request - invalid parameters |
401 | Unauthorized - missing or invalid API key |
404 | Not Found - domain not indexed |
429 | Too Many Requests - rate limit exceeded |
500 | Server Error - retry with exponential backoff |
Error Handling
All error responses follow the same JSON structure, making it easy to implement consistent error handling across clients.
{
"error": {
"code": "rate_limited",
"message": "You have exceeded your per-second rate limit.",
"retry_after_ms": 420
}
}