API

The CleanBrowsing API uses basic CRUD operations. It’s designed to be simple and can be accessed any HTTPS library (e.g., cURL). Access control is managed via an authentication key, denoted as the “API Key”. This key should be present in all requests and should be managed using encryption protocols (e.g., HTTPS).

Operation	Description
category/block	Adds a new category to the block list.
category/allow	Removes a category from the block list (allows it).
categories/list	List all categories blocked.
profile/add	Adds a new profile.
profile/delete	Deletes an existing profile.
profiles/list	Listt all available profiles.
whitelist/add	Adds a new domain to the whitelist.
whitelist/delete	Deletes a domain from the whitelist.
whitelist/list	List all domain in the whitelist.
blocklist/add	Adds a new domain to the blocklist.
blocklist/delete	Deletes a domain from the blocklist.
blocklist/list	List all domains in the blocklist.
default-block/enable	Enable defaults-block. Only whitelisted domains are allowed.
default-block/disable	Disable the default-block option.
network/add	Adds a new IP address to your network list.
network/delete	Deletes an IP address form the network list.
network/list	List all IP addresses in the network list
logs/list	List all the available logs for your account.
logs/getstats	Get details stats for a specific day.
logs/getdump	Get all the logs (dump) of all activity for a specific day.
logs/delete	Delete a specific log (Stats won’t be deleted)

Name	Options
Category Names:	category_adult category_adultmixed category_advertising_tracking category_torrents category_p2p_file_sharing category_proxy_vpn category_gaming category_gambling category_dating category_social_network category_search_engine category_online_radio category_weapons category_malicious_blacklisted category_video_streaming category_drugs category_alcohol category_lingerie category_hate_speech category_academic_fraud category_instant_messaging category_self_harm

CATEGORY/block

Adds a new category to the block list.

Parameter	Arguement
Action	category/block
Required Value	category_name=[a-zA-Z0-9]{4,}
Optional Value	profile_name=(valid_profile_name) or “default” when not provided
Results	{“status” = “success”};
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=category/block&category_name=<CATEGORYNAME>

CATEGORY/allow

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

Parameter	Arguement
Action	category/allow
Required Value	category_name=[a-zA-Z0-9]{4,}
Optional Value	profile_name=(valid_profile_name) or “default” when not provided
Results	{“status” = “success”};
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=category/allow&category_name=<CATEGORYNAME>

List all categories blocked.

Parameter	Arguement
Action	categories/list
Required Value	N/A
Optional Value	profile_name=(valid_profile_name) or “default” when not provided
Results	{“status” = “success”};
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=category/list

PROFILE/add

Adds a new profile.

Parameter	Arguement
Action	profile/add
Required Value	profile_name=[a-zA-Z0-9]{4,}
Optional Value	N/A
Results	{“status” = “success”};
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=profile/add&profile_name=<PROFILENAME>

PROFILE/delete

Deletes an existing profile.

Parameter	Arguement
Action	profile/delete
Required Value	profile_name=[a-zA-Z0-9]{4,}
Optional Value	N/A
Results	{“status” = “success”};
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=profile/delete&profile_name=<PROFILENAME>

PROFILES/list

List all existing profiles.

Parameter	Arguement
Action	profiles/list
Required Value	profile_name=[a-zA-Z0-9]{4,}
Optional Value	N/A
Results	{“status” = “success”};
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=profile/list

WHITELIST/add

Adds a new domain to the whitelist (list of domains that are always allowed, overwriting the default categories).

Parameter	Arguement
Action	whitelist/add
Required Value	domain_name=(valid_domain_name)
Optional Value	profile_name=(valid_profile_name) or “default” when not provided
Results	{“status” = “success”};
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=whitelist/add&domain_name=<domain_name>

WHITELIST/delete

Deletes a domain from the whitelist.

Parameter	Arguement
Action	whitelist/delete
Required Value	domain_name=(valid_domain_name)
Optional Value	profile_name=(valid_profile_name) or “default” when not provided
Results	{“status” = “success”};
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=whitelist/delete&domain_name=<DOMAINNAME>

WHITELIST/list

List all domains in the whitelist (all profiles it will be listed if no profile_name is included).

Parameter	Arguement
Action	whitelist/list
Required Value	N/A
Optional Value	profile_name=(valid_profile_name) or “default” when not provided
Results	{“status”:”success”,”whitelist”:{“default”:[“mytestdomain.com”,”globo.com”],”profileexample”:[“music.com”,”test.com”]}}
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=whitelist/list

BLOCKLIST/add

Adds a new domain to the blocklist (list of domains that are always blocked, overwriting the default categories).

Parameter	Arguement
Action	blocklist/add
Required Value	domain_name=(valid_domain_name)
Optional Value	profile_name=(valid_profile_name) or “default” when not provided
Results	{“status” = “success”};
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=blocklist/add&domain_name=<DOMAINNAME>

BLOCKLIST/delete

Deletes a domain from the blocklist.

Parameter	Arguement
Action	blocklist/delete
Required Value	domain_name=(valid_domain_name)
Optional Value	profile_name=(valid_profile_name) or “default” when not provided
Results	{“status” = “success”};
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=blocklist/delete&domain_name=<DOMAINNAME>

BLOCKLIST/list

List all domains in the blocklist (all profiles it will be listed if no profile_name is included).

Parameter	Arguement
Action	blocklist/list
Required Value	N/A
Optional Value	profile_name=(valid_profile_name) or “default” when not provided
Results	{“status”:”success”,”blocklist”:{“default”:[“mytestdomain.com”,”globo.com”],”profileexample”:[“music.com”,”test.com”]}}
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=blocklist/list

DEFAULT-BLOCK/enable

Enables default-block for the profile. All domains will be blocked unless explicity allowed. WARNING: Use with caution.

Parameter	Arguement
Action	default-block/enable
Required Value	profile_name=(valid_profile_name)
Optional Value	N/A
Results	{“status” = “success”};
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=default-block/enable&profile_name=<default>

DEFAULT-BLOCK/disable

Disables default-block for the profile.

Parameter	Arguement
Action	default-block/disable
Required Value	profile_name=(valid_profile_name)
Optional Value	N/A
Results	{“status” = “success”};
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=default-block/disable&profile_name=<default>

NETWORK/add

Adds a new IP address to your network list.

Parameter	Arguement
Action	network/add
Required Value	ip_address=(valid_ipv4)
Optional Value	profile_name=(valid_profile_name) or “default” when not provided
Results	{“status” = “success”};
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=network/add&ip_address=<IPv4>

NETWORK/delete

Deletes an IP address from the network list.

Parameter	Arguement
Action	network/delete
Required Value	ip_address=(valid_ipv4)
Optional Value	profile_name=(valid_profile_name) or “default” when not provided
Results	{“status” = “success”};
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=network/delete&ip_address=<IPv4>

NETWORK/list

List all IP Addresses in your network list (all profiles it will be listed if no profile_name is included).

Parameter	Arguement
Action	network/list
Required Value	N/A
Optional Value	profile_name=(valid_profile_name) or “default” when not provided
Results	{“status”:”success”,”networks”:{“default”:[“1.2.3.4″,”1.2.3.3″],”profileexample”:[“2.1.1.1″,”2.2.2.2”]}}
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=network/list

LOGS/list

List all the available days with full logs for your account.

Parameter	Arguement
Action	logs/list
Required Value	N/A
Optional Value	N/A
Results	{“status”:”success”,”logs”:[“2019-09-03″,”2019-09-02″,”2019-09-01”]}
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=logs/list

LOGS/getstats

Get detailed activity stats for a specific day. It returns a JSON output with all the activity on that day divided per hour. It is broken down by top IPs, top requests type, blocks, domains blocked, etc. This is a comprehensive view that can be useful when building your own stats.

Parameter	Arguement
Action	logs/getstats
Required Value	date=(valid_date in the format yyyy-mm-dd)
Optional Value	N/A
Results	{“ips”:{“2019-08-29 00:00”:{“47.144.214.39″:1230},”2019-08-29 01:00”:{“47.144.214.39”:1067},… “reqtypes”:{“2019-08-29 00:00”:{“A”:1103,”PTR”:2,”AAAA”:125},”2019-08-29 01:00″:{“A”:798,”AAAA”:266,”PTR”:3},… “action”:{“2019-08-29 00:00”:{“Allowed”:1185,”Blocked”:45},”2019-08-29 01:00″:{“Allowed”:1034,”Blocked”:33},.. “blocks”:{“2019-08-29 00:00”:{“category_advertising_tracking”:43,”custom_filter”:2},”2019-08-29 01:00″:{“category_advertising_tracking”:27,”category_online_radio”:4,”custom_filter”:2}… “domains”:{“2019-08-29 00:00”:{“Allowed”:{“www.gstatic.com.”:38,”ssl.gstatic.com.”:33,”play.google.com.”:26,”push.prod.netflix.com.”:26,”ips1.unifi-ai.com.”:25,”0.client-channel.google.com.”:24..
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=logs/getstats&date=2019-09-02

LOGS/getdump

Get all the logs for a specific day (in text format). The response can be very long (hundreds of MB), so use it with caution. It should not be called more than once per hour. Ideally, it should be called once per day at a maximum.

Parameter	Arguement
Action	logs/getdump
Required Value	date=(valid_date in the format yyyy-mm-dd)
Optional Value	N/A
Results	2019-08-29 00:00:29 111 pass-through: allowed: 47.144.1.1: 1: play.google.com. (185.228.168.1) 2019-08-29 00:00:30 111 pass-through: allowed: 47.144.1.1: 1: people-pa.clients6.google.com. (185.228.168.1) 2019-08-29 00:00:33 111 pass-through: allowed: 47.144.1.1: 1: www.gstatic.com. (185.228.168.1) 2019-08-29 00:00:33 111 pass-through: allowed: 47.144.1.1: 1: www.gstatic.com. (185.228.169.1)
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=logs/getdump&date=2019-09-02

LOGS/delete

Delete a specific log (stats won’t be deleted) for the provided date.

Parameter	Arguement
Action	logs/delete
Required Value	date=(valid_date in the format yyyy-mm-dd)
Optional Value	N/A
Results	{“status” = “success”};
Error	{“status”:”failed”, “reason”:”reason why”}

Example:

https://my.cleanbrowsing.org/api?apikey=[key]&action=logs/delete&date=2019-09-02

Updated on February 6, 2024

Was this article helpful?

Yes No

Need Support?

Can’t find the answer you’re looking for? Don’t worry we’re here to help!

Contact Support

CATEGORIES

CATEGORY/block

CATEGORY/allow

CATEGORIES/list

PROFILE/add

PROFILE/delete

PROFILES/list

WHITELIST/add

WHITELIST/delete

WHITELIST/list

BLOCKLIST/add

BLOCKLIST/delete

BLOCKLIST/list

DEFAULT-BLOCK/enable

DEFAULT-BLOCK/disable

NETWORK/add

NETWORK/delete

NETWORK/list

LOGS/list

LOGS/getstats

LOGS/getdump

LOGS/delete

Related Articles