API Documentation

Programmatic access to your DNS filtering platform via REST API.

⬇ Download OpenAPI spec (YAML) Import into Postman, Swagger UI, or use to generate SDK clients

Authentication

All API requests require an API Key in the X-API-Key header. Generate your key in the Account page.

# Include your API key in every request
curl -H "X-API-Key: YOUR_API_KEY" https://YOUR_DOMAIN/api/me

Your API key provides the same access level as your account. Keep it secret. If compromised, regenerate it immediately from the Account page.

Endpoints Reference

Client Management

Method	Endpoint	Description
GET	`/api/admin/users`	List all clients
POST	`/api/admin/users`	Create a new client account
PUT	`/api/admin/users/:user_id/plan`	Change a client's plan
DELETE	`/api/admin/users/:user_id`	Delete a client account

Client Profiles

Method	Endpoint	Description
GET	`/api/admin/users/:user_id/profiles`	List a client's profiles
GET	`/api/admin/users/:user_id/profiles/:config_id`	Get a client's profile details
PUT	`/api/admin/users/:user_id/profiles/:config_id`	Update a client's profile settings
DELETE	`/api/admin/users/:user_id/profiles/:config_id`	Delete a client's profile

Client Analytics

Each profile has a config_id (found in the response of GET /api/admin/users/:user_id/profiles). Use it to query a client's DNS analytics:

# 1. List the client's profiles to find the config_id
curl -s -H "X-API-Key: YOUR_API_KEY" \
  https://YOUR_DOMAIN/api/admin/users/USER_ID/profiles
# Each profile has a "configId" field (e.g. "a1b2c3d4e5f6")

# 2. Use the config_id to query analytics
curl -s -H "X-API-Key: YOUR_API_KEY" \
  https://YOUR_DOMAIN/api/analytics/a1b2c3d4e5f6/stats?period=24h

Method	Endpoint	Description
GET	`/api/analytics/:config_id/stats?period=24h`	Stats overview (24h, 7d, 30d)
GET	`/api/analytics/:config_id/queries?limit=50`	Query log (recent DNS queries)
GET	`/api/analytics/:config_id/top-domains?limit=100`	Top domains, blocked domains, devices
GET	`/api/analytics/:config_id/destinations?period=24h`	Traffic destinations by country

System

Method	Endpoint	Description
GET	`/api/admin/stats?period=24h`	Global stats (all clients)
GET	`/api/admin/node-stats?period=24h`	Per-node stats
GET	`/api/admin/health`	System health checks

Partners use the same endpoints under /api/partner/ instead of /api/admin/.

Profile Settings

When updating a client's profile (PUT /api/admin/users/:user_id/profiles/:config_id), you can set any of these fields:

{
  "name": "My Profile",
  "dns_preset": "security",          // "no_filtering", "security", "family"
  "whitelist": ["allowed.com"],
  "blacklist": ["blocked.com", "*.ads.com"],
  "linked_ips": ["203.0.113.1"],
  "safe_search": true,
  "block_canary": true,
  "block_telemetry": true,
  "safe_browsing": true,
  "block_rebinding": true,
  "blocked_services": ["facebook", "tiktok"],
  "blocked_services_enabled": true,
  "allowlist_enabled": true,
  "denylist_enabled": true
}

Examples

Get account info

curl -s -H "X-API-Key: YOUR_API_KEY" \
  https://YOUR_DOMAIN/api/me | jq

List profiles

curl -s -H "X-API-Key: YOUR_API_KEY" \
  https://YOUR_DOMAIN/api/profiles | jq

Get stats (24h)

curl -s -H "X-API-Key: YOUR_API_KEY" \
  https://YOUR_DOMAIN/api/analytics/CONFIG_ID/stats?period=24h

Add a domain to the denylist

# Get current blacklist, add domain, update
curl -s -X PUT -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"blacklist": ["existing.com", "newdomain.com"]}' \
  https://YOUR_DOMAIN/api/admin/users/USER_ID/profiles/CONFIG_ID

Create a user account (Admin)

curl -s -X POST -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com",
       "password":"SecurePass123",
       "name":"John Doe",
       "notify":true}' \
  https://YOUR_DOMAIN/api/admin/users

List all users (Admin)

curl -s -H "X-API-Key: YOUR_API_KEY" \
  https://YOUR_DOMAIN/api/admin/users | jq

System health check

curl -s -H "X-API-Key: YOUR_API_KEY" \
  https://YOUR_DOMAIN/api/admin/health | jq

Manage a client's profile

# 1. List all clients
curl -s -H "X-API-Key: YOUR_API_KEY" \
  https://YOUR_DOMAIN/api/admin/users | jq

# 2. List a specific client's profiles (use user_id from step 1)
curl -s -H "X-API-Key: YOUR_API_KEY" \
  https://YOUR_DOMAIN/api/admin/users/USER_ID/profiles | jq

# 3. View the client's profile details
curl -s -H "X-API-Key: YOUR_API_KEY" \
  https://YOUR_DOMAIN/api/admin/users/USER_ID/profiles/CONFIG_ID | jq

# 4. Update the client's profile (enable Safe Search + block TikTok)
curl -s -X PUT -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"safe_search": true,
       "blocked_services": ["tiktok"],
       "blocked_services_enabled": true}' \
  https://YOUR_DOMAIN/api/admin/users/USER_ID/profiles/CONFIG_ID

Get stats for all profiles

import requests

API_KEY = "your_key_here"
BASE = "https://YOUR_DOMAIN"
headers = {"X-API-Key": API_KEY}

profiles = requests.get(f"{BASE}/api/profiles", headers=headers).json()["profiles"]

for p in profiles:
    stats = requests.get(f"{BASE}/api/analytics/{p['config_id']}/stats?period=24h", headers=headers).json()
    print(f"{p['name']}: {stats.get('total_queries', 0)} queries, {stats.get('blocked_queries', 0)} blocked")

Add a domain to the denylist

import requests

API_KEY = "your_key_here"
BASE = "https://YOUR_DOMAIN"
CONFIG_ID = "your_config_id"
headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

# Get current profile
profile = requests.get(f"{BASE}/api/profiles/{CONFIG_ID}", headers=headers).json()
blacklist = profile.get("blacklist", []) or []

# Add new domain
blacklist.append("malware.example.com")
requests.put(f"{BASE}/api/profiles/{CONFIG_ID}", headers=headers, json={"blacklist": blacklist})
print("Domain added to denylist")

Create accounts in bulk (Admin)

import requests

API_KEY = "your_key_here"
BASE = "https://YOUR_DOMAIN"
headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

accounts = [
    {"email": "user1@example.com", "password": "Pass1234!", "name": "User One"},
    {"email": "user2@example.com", "password": "Pass5678!", "name": "User Two"},
    {"email": "user3@example.com", "password": "Pass9012!", "name": "User Three"},
]

for acc in accounts:
    acc["notify"] = True
    resp = requests.post(f"{BASE}/api/admin/users", headers=headers, json=acc)
    if resp.status_code == 201:
        print(f"Created: {acc['email']}")
    else:
        print(f"Failed: {acc['email']} — {resp.json().get('error', 'unknown')}")

Block a service on a profile

import requests

API_KEY = "your_key_here"
BASE = "https://YOUR_DOMAIN"
CONFIG_ID = "your_config_id"
headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

requests.put(f"{BASE}/api/profiles/{CONFIG_ID}", headers=headers, json={
    "blocked_services": ["tiktok", "facebook", "instagram"],
    "blocked_services_enabled": True
})
print("Services blocked")

Manage a client's profile (Admin)

import requests

API_KEY = "your_key_here"
BASE = "https://YOUR_DOMAIN"
headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

# 1. List all clients
users = requests.get(f"{BASE}/api/admin/users", headers=headers).json()["users"]
for u in users:
    print(f"{u['email']} — {u['user_id']}")

# 2. List a client's profiles
user_id = "the_user_id"
profiles = requests.get(f"{BASE}/api/admin/users/{user_id}/profiles", headers=headers).json()["profiles"]
for p in profiles:
    print(f"{p['name']} — config_id: {p['configId']}")

# 3. View the client's profile
config_id = "the_config_id"
profile = requests.get(f"{BASE}/api/admin/users/{user_id}/profiles/{config_id}", headers=headers).json()
print(f"Preset: {profile['dnsPreset']}, Safe Search: {profile['safeSearch']}")

# 4. Update the client's profile
requests.put(f"{BASE}/api/admin/users/{user_id}/profiles/{config_id}", headers=headers, json={
    "safe_search": True,
    "dns_preset": "family",
    "blocked_services": ["tiktok"],
    "blocked_services_enabled": True,
})
print("Client profile updated")

Get stats for a profile

<?php
$apiKey = 'your_key_here';
$base = 'https://YOUR_DOMAIN';
$configId = 'your_config_id';

$ch = curl_init("$base/api/analytics/$configId/stats?period=24h");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: $apiKey"]);
$response = curl_exec($ch);
curl_close($ch);

$stats = json_decode($response, true);
echo "Total queries: " . $stats['total_queries'] . "\n";
echo "Blocked: " . $stats['blocked_queries'] . "\n";
echo "Block rate: " . round($stats['blocked_percentage'], 1) . "%\n";

List all users (Admin)

<?php
$apiKey = 'your_key_here';
$base = 'https://YOUR_DOMAIN';

$ch = curl_init("$base/api/admin/users");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: $apiKey"]);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
foreach ($data['users'] as $user) {
    echo $user['email'] . ' — ' . $user['plan'] . "\n";
}

Add a domain to the denylist

<?php
$apiKey = 'your_key_here';
$base = 'https://YOUR_DOMAIN';
$configId = 'your_config_id';

// Get current profile
$ch = curl_init("$base/api/profiles/$configId");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: $apiKey"]);
$profile = json_decode(curl_exec($ch), true);
curl_close($ch);

// Add domain to blacklist
$blacklist = $profile['blacklist'] ?? [];
$blacklist[] = 'malware.example.com';

// Update profile
$ch = curl_init("$base/api/profiles/$configId");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['blacklist' => $blacklist]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: $apiKey", 'Content-Type: application/json']);
curl_exec($ch);
curl_close($ch);

echo "Domain added to denylist\n";

Create a user account (Admin)

<?php
$apiKey = 'your_key_here';
$base = 'https://YOUR_DOMAIN';

$ch = curl_init("$base/api/admin/users");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'email' => 'newuser@example.com',
    'password' => 'SecurePass123',
    'name' => 'John Doe',
    'notify' => true,
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: $apiKey", 'Content-Type: application/json']);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 201) {
    echo "Account created\n";
} else {
    echo "Error: " . json_decode($response, true)['error'] . "\n";
}

Manage a client's profile (Admin)

<?php
$apiKey = 'your_key_here';
$base = 'https://YOUR_DOMAIN';
$userId = 'client_user_id';
$configId = 'your_config_id';

// 1. List a client's profiles
$ch = curl_init("$base/api/admin/users/$userId/profiles");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: $apiKey"]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
foreach ($data['profiles'] as $p) {
    echo $p['name'] . ' — ' . $p['configId'] . "\n";
}

// 2. View the client's profile
$ch = curl_init("$base/api/admin/users/$userId/profiles/$configId");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: $apiKey"]);
$profile = json_decode(curl_exec($ch), true);
curl_close($ch);
echo "Current preset: " . $profile['dnsPreset'] . "\n";

// 3. Update the profile (switch to Family + enable Safe Search)
$ch = curl_init("$base/api/admin/users/$userId/profiles/$configId");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'dns_preset' => 'family',
    'safe_search' => true,
    'blocked_services' => ['tiktok', 'snapchat'],
    'blocked_services_enabled' => true,
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: $apiKey", 'Content-Type: application/json']);
curl_exec($ch);
curl_close($ch);
echo "Client profile updated\n";

Errors

All errors return a JSON object with an error field:

{ "error": "invalid API key" }

HTTP Code	Meaning
`401`	Missing or invalid API key
`403`	Insufficient permissions (not admin/partner)
`404`	Resource not found
`500`	Internal server error