API Reference

Authentication

All API requests require your API key, passed as a query parameter on every call:

https://my.cleanbrowsing.org/api?apikey=YOUR_API_KEY&action=ACTION&...

Your API key is available in the CleanBrowsing dashboard under API Access. Keep it private — anyone with your key can manage your account.

Request Format

The API is very simple and can be accessed via curl or any HTTPS library. All calls follow the same pattern:

https://my.cleanbrowsing.org/api?apikey=YOUR_API_KEY&action=ACTION_NAME&param1=value1&param2=value2

Parameters are passed as URL query strings. All requests must use HTTPS.

Response Format

All responses are JSON. Successful calls return:

{"status": "success"}

Failed calls return:

{"status": "failed", "reason": "Description of what went wrong"}

category/block

Adds a new category to the block list.

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

Available Categories

category/allow

Removes a category from the block list (allows it).

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

categories/list

List all categories currently blocked.

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

profile/add

Adds a new filtering profile. Profiles let you apply different filtering rules to different networks or devices.

curl "https://my.cleanbrowsing.org/api?apikey=YOUR_API_KEY&action=profile/add&profile_name=KidsDevices"

profile/delete

Deletes an existing profile.

curl "https://my.cleanbrowsing.org/api?apikey=YOUR_API_KEY&action=profile/delete&profile_name=KidsDevices"

profiles/list

List all existing profiles.

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

Response:

{"status": "success", "profiles": ["default", "KidsDevices", "GuestWiFi"]}

whitelist/add

Adds a domain to the whitelist. Whitelisted domains are always allowed, even if they match a blocked category.

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

whitelist/delete

Removes a domain from the whitelist.

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

whitelist/list

List all domains in the whitelist. Returns domains grouped by profile.

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

Response:

{"status": "success", "whitelist": {"default": ["example.com", "educational-site.org"], "KidsDevices": ["learning-app.com"]}}

blocklist/add

Adds a domain to the blocklist. Blocklisted domains are always blocked regardless of category settings.

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

blocklist/delete

Removes a domain from the blocklist.

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

blocklist/list

List all domains in the blocklist. Returns domains grouped by profile.

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

Response:

{"status": "success", "blocklist": {"default": ["unwanted-site.com", "blocked-domain.net"], "KidsDevices": ["distraction.com"]}}

tld_blocklist/add

Adds a TLD (top-level domain) to the blocklist. All domains under that TLD will be blocked.

curl "https://my.cleanbrowsing.org/api?apikey=YOUR_API_KEY&action=tld_blocklist/add&tld=.xyz"

default-block/enable

Enables default-block mode for a profile. All domains will be blocked unless explicitly whitelisted. Use with caution.

curl "https://my.cleanbrowsing.org/api?apikey=YOUR_API_KEY&action=default-block/enable&profile_name=default"

default-block/disable

Disables default-block mode for a profile.

curl "https://my.cleanbrowsing.org/api?apikey=YOUR_API_KEY&action=default-block/disable&profile_name=default"

network/add

Adds a new IP address to your network list. CleanBrowsing uses your registered IPs to apply the correct filtering profile to your traffic.

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

Dynamic DNS Update Script

Automate IP updates for dynamic networks with a cron job:

#!/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?apikey=${API_KEY}&action=network/add&ip_address=${CURRENT_IP}&label=AutoUpdate"

Add to crontab to run every 15 minutes:

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

network/delete

Removes an IP address from the network list.

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

network/list

List all IP addresses in your network list. Returns IPs grouped by profile.

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

Response:

{"status": "success", "networks": {"default": ["203.0.113.50", "198.51.100.10"], "KidsDevices": ["192.0.2.25"]}}

logs/list

List all available days with full logs for your account.

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

Response:

{"status": "success", "logs": ["2026-03-06", "2026-03-05", "2026-03-04"]}

logs/getstats

Get detailed activity stats for a specific day, broken down by hour. Includes top IPs, request types, blocks by category, and top domains.

curl "https://my.cleanbrowsing.org/api?apikey=YOUR_API_KEY&action=logs/getstats&date=2026-03-06"

Response (abbreviated):

{
  "ips": {"2026-03-06 00:00": {"203.0.113.50": 1230}, ...},
  "reqtypes": {"2026-03-06 00:00": {"A": 1103, "AAAA": 125, "PTR": 2}, ...},
  "action": {"2026-03-06 00:00": {"Allowed": 1185, "Blocked": 45}, ...},
  "blocks": {"2026-03-06 00:00": {"category_advertising_tracking": 43}, ...},
  "domains": {"2026-03-06 00:00": {"Allowed": {"www.google.com.": 38}, "Blocked": {"tracker.ads.com.": 12}}, ...}
}

logs/getdump

Download all logs for a specific day in text format. Warning: The response can be very large (hundreds of MB). Do not call more than once per hour — ideally once per day.

curl "https://my.cleanbrowsing.org/api?apikey=YOUR_API_KEY&action=logs/getdump&date=2026-03-06"

Response (plain text):

2026-03-06 00:00:29 111 pass-through: allowed: 203.0.113.50: 1: play.google.com. (185.228.168.1)
2026-03-06 00:00:30 111 pass-through: allowed: 203.0.113.50: 1: www.gstatic.com. (185.228.168.1)
2026-03-06 00:00:33 111 pass-through: blocked: 203.0.113.50: 1: tracker.ads.com. (185.228.168.1)

logs/delete

Delete logs for a specific date. Aggregated stats are not deleted, only raw log entries.

curl "https://my.cleanbrowsing.org/api?apikey=YOUR_API_KEY&action=logs/delete&date=2026-03-06"