API

The NOC 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).
category/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)

A list of the available categories:

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

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>

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>

CATEGORY/list

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>

PROFILE/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/list
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

Was this article helpful?

Related Articles