CleanBrowsing API Documentation

Step 1: API Overview

The CleanBrowsing API provides a REST interface for managing your DNS filtering account programmatically. You can use it to automate IP updates for dynamic networks, manage domain whitelists and blocklists, control category filters, create and delete profiles, and pull activity logs.

All API requests are made over HTTPS to the base URL:

https://my.cleanbrowsing.org/api/v1/

The API accepts parameters via query strings and returns JSON responses. A successful response includes:

{"status": "success"}

Failed requests return an error message describing the issue:

{"status": "error", "message": "Invalid API key"}

Requirements

• Paid account: API access requires an active CleanBrowsing paid subscription.
• API key: Generated from your CleanBrowsing dashboard.
• HTTPS only: All requests must use HTTPS. HTTP requests will be rejected.

Step 2: Authentication

Every API request must include your API key. The key identifies your account and authorizes the requested action.

Getting Your API Key

1. Log in to your CleanBrowsing dashboard at my.cleanbrowsing.org.
2. Navigate to Settings or Account.
3. Locate the API Key section and copy your key.

Passing the API Key

Include the apikey parameter in every request:

curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=profiles/list"

Security note: Keep your API key secret. Do not expose it in client-side code, public repositories, or shared scripts. If your key is compromised, regenerate it immediately from the dashboard.

Step 3: Update IP Address

If your network uses a dynamic IP address, you need to keep CleanBrowsing updated with your current public IP so that filtering rules apply correctly. The API provides endpoints to manage your registered network IP addresses.

List Registered IPs

curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=network/list"

Example response:

{
  "status": "success",
  "networks": [
    {
      "ip": "203.0.113.50",
      "label": "Home Network",
      "profile": "default"
    }
  ]
}

Add or Update an IP Address

curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=network/add&ip=203.0.113.100&label=Office"

Delete an IP Address

curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=network/delete&ip=203.0.113.50"

Dynamic DNS Update Script

You can automate IP updates with a cron job. This script detects your current public IP and updates CleanBrowsing:

#!/bin/bash
# Save as /usr/local/bin/cb-update-ip.sh
API_KEY="YOUR_API_KEY"
CURRENT_IP=$(curl -s https://api.ipify.org)
curl -s "https://my.cleanbrowsing.org/api/v1/?apikey=${API_KEY}&action=network/add&ip=${CURRENT_IP}&label=AutoUpdate"

Add it to crontab to run every 15 minutes:

*/15 * * * * /usr/local/bin/cb-update-ip.sh > /dev/null 2>&1

Step 4: Manage Filters

CleanBrowsing categorizes content into predefined categories (adult content, malware, gambling, social media, etc.). The API lets you block or allow specific categories and manage filtering profiles.

List Blocked Categories

curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=categories/list"

Returns a list of all categories and their current block status.

Block a Category

curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=category/block&category=gambling"

Allow a Category

curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=category/allow&category=gambling"

Available Categories

Manage Profiles

Profiles let you apply different filtering rules to different networks or devices.

# List all profiles
curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=profiles/list"

# Create a new profile
curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=profile/add&name=Kids"

# Delete a profile
curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=profile/delete&name=Kids"

Whitelist-Only Mode

Enable default-block mode to block all domains except those on your whitelist:

# Enable whitelist-only mode
curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=default-block/enable"

# Disable whitelist-only mode
curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=default-block/disable"

Step 5: List Domains

View the domains currently on your whitelist (allowed) and blocklist (blocked).

List Whitelisted Domains

curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=whitelist/list"

Example response:

{
  "status": "success",
  "domains": [
    "example.com",
    "educational-site.org",
    "company-tool.io"
  ]
}

List Blocked Domains

curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=blocklist/list"

Retrieve Activity Logs

The API also lets you pull DNS query logs for auditing and monitoring:

# List available log dates
curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=logs/list"

# Get statistics for a specific date
curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=logs/getstats&date=2026-02-21"

# Download full log dump for a date
curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=logs/getdump&date=2026-02-21"

# Delete logs for a specific date
curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=logs/delete&date=2026-02-21"

Step 6: Add / Remove Custom Domains

Custom domain lists give you fine-grained control over what is allowed or blocked on your network, beyond the predefined category filters.

Add a Domain to the Whitelist

Allow a specific domain that might otherwise be blocked by a category filter:

curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=whitelist/add&domain=example.com"

Remove a Domain from the Whitelist

curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=whitelist/delete&domain=example.com"

Add a Domain to the Blocklist

Block a specific domain that is not covered by an existing category:

curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=blocklist/add&domain=unwanted-site.com"

Remove a Domain from the Blocklist

curl "https://my.cleanbrowsing.org/api/v1/?apikey=YOUR_API_KEY&action=blocklist/delete&domain=unwanted-site.com"

Bulk Domain Management Script

Use this bash script to add multiple domains to your blocklist from a text file:

#!/bin/bash
# Save as /usr/local/bin/cb-bulk-block.sh
# Usage: ./cb-bulk-block.sh domains.txt
API_KEY="YOUR_API_KEY"
DOMAIN_FILE="$1"

while IFS= read -r domain; do
  [ -z "$domain" ] && continue
  echo "Blocking: $domain"
  curl -s "https://my.cleanbrowsing.org/api/v1/?apikey=${API_KEY}&action=blocklist/add&domain=${domain}"
  echo ""
done < "$DOMAIN_FILE"

Create a text file with one domain per line:

unwanted-site1.com
unwanted-site2.net
unwanted-site3.org

Then run:

chmod +x /usr/local/bin/cb-bulk-block.sh
./cb-bulk-block.sh domains.txt

Rate Limits and Best Practices

• HTTPS only: Always use HTTPS. Never send your API key over an unencrypted connection.
• Error handling: Always check the status field in the response before proceeding.
• Key rotation: Periodically regenerate your API key from the dashboard if you suspect it has been exposed.
• Automation: Use cron jobs or CI/CD pipelines to automate IP updates and domain list management.