API Reference

Manage your CleanBrowsing dashboard via a simple REST API.

All API calls use https://my.cleanbrowsing.org/api with your API key. Access your key in the CleanBrowsing Dashboard → API Access.

Find your key in the CleanBrowsing Dashboard under API Access. All examples below will update with your key.

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"}

Categories

category/block

Adds a new category to the block list.

Parameter Required Description
category_name Yes Category identifier (see list below)
profile_name No Profile name. Defaults to default if not provided. 
curl "https://my.cleanbrowsing.org/api?apikey=YOUR_API_KEY&action=category/block&category_name=category_gambling"
Available Categories
Category Name Description
category_adult Pornography and adult content
category_adultmixed Mixed adult content (e.g., Reddit)
category_advertising_tracking Advertising and tracking domains
category_torrents Torrent trackers
category_p2p_file_sharing Peer-to-peer file sharing
category_proxy_vpn VPN and proxy bypass services
category_gaming Online gaming platforms
category_gambling Gambling and betting sites
category_dating Dating websites and apps
category_social_network Social networking sites
category_search_engine Search engines
category_online_radio Online radio and podcasts
category_weapons Weapons-related content
category_malicious_blacklisted Malware, phishing, and malicious domains
category_video_streaming Video streaming platforms
category_drugs Drug-related content
category_alcohol Alcohol-related content
category_lingerie Lingerie and swimwear
category_hate_speech Hate speech and extremism
category_academic_fraud Academic fraud and cheating services

category/allow

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

Parameter Required Description
category_name Yes Category identifier
profile_name No Profile name. Defaults to default. 
curl "https://my.cleanbrowsing.org/api?apikey=YOUR_API_KEY&action=category/allow&category_name=category_gambling"

categories/list

List all categories currently blocked.

Parameter Required Description
profile_name No Profile name. Defaults to default. 
curl "https://my.cleanbrowsing.org/api?apikey=YOUR_API_KEY&action=categories/list"

Profiles

profile/add

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

Parameter Required Description
profile_name Yes Alphanumeric name, minimum 4 characters 
curl "https://my.cleanbrowsing.org/api?apikey=YOUR_API_KEY&action=profile/add&profile_name=KidsDevices"

profile/delete

Deletes an existing profile.

Parameter Required Description
profile_name Yes Profile name to delete 
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

whitelist/add

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

Parameter Required Description
domain_name Yes Valid domain name
profile_name No Profile name. Defaults to default. 
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.

Parameter Required Description
domain_name Yes Domain to remove
profile_name No Profile name. Defaults to default. 
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.

Parameter Required Description
profile_name No Profile name, or lists all profiles if omitted. 
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

blocklist/add

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

Parameter Required Description
domain_name Yes Valid domain name
profile_name No Profile name. Defaults to default. 
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.

Parameter Required Description
domain_name Yes Domain to remove
profile_name No Profile name. Defaults to default. 
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.

Parameter Required Description
profile_name No Profile name, or lists all profiles if omitted. 
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.

Parameter Required Description
tld Yes Valid TLD (e.g., .xyz, .top, .ru)
profile_name No Profile name. Defaults to default. 
curl "https://my.cleanbrowsing.org/api?apikey=YOUR_API_KEY&action=tld_blocklist/add&tld=.xyz"

Default Block

default-block/enable

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

Parameter Required Description
profile_name Yes Profile name to enable default-block on 
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.

Parameter Required Description
profile_name Yes Profile name 
curl "https://my.cleanbrowsing.org/api?apikey=YOUR_API_KEY&action=default-block/disable&profile_name=default"

Network

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.

Parameter Required Description
ip_address Yes Valid IPv4 address
profile_name No Profile name. Defaults to default.
label No Label for this network (e.g., "Home", "Office") 
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.

Parameter Required Description
ip_address Yes IPv4 address to remove
profile_name No Profile name. Defaults to default. 
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.

Parameter Required Description
profile_name No Profile name, or lists all profiles if omitted. 
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

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.

Parameter Required Description
date Yes Date in yyyy-mm-dd format 
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.

Parameter Required Description
date Yes Date in yyyy-mm-dd format 
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.

Parameter Required Description
date Yes Date in yyyy-mm-dd format 
curl "https://my.cleanbrowsing.org/api?apikey=YOUR_API_KEY&action=logs/delete&date=2026-03-06"

Need Help?

If you have questions about the API or need help integrating, contact our support team at support@cleanbrowsing.org.

For more guides and tutorials: