About the CleanBrowsing API

CleanBrowsing offers it’s user an easy to use dashboard to accomplish most of the key functions when operating your own DNS resolver. There are, however, instances where an organization might not want to use our dashboard, instead integrating functionality into their own platform. To help with this, we have our own Application Programming Interface (API) available to all customers on the Pro 500 or higher.

This guide will highlight how to work with the API and its available functions. This guide is specific to the Pro 500 Paid Plan, if you’re looking for instructions for the Free plans we encourage you to refer to the Getting Started instructions.

Working with the CleanBrowsing API

The API will be immediately available post-purchase in your dashboard.

Every account will get a unique API Key. You will require this key to interact with your account. You access the API using any HTTPS library or leveraging the CURL command. You can expect all normal CRUD operations in our API.

Available API Functions

The API provides the following functions:

Ability to manipulate profiles:

1. Profile/add: Adds a new profile.
2. Profile/delete: Deletes an existing profile.
3. Profiles/list: List all available profiles.

Ability to customize the network filters with:

1. Whitelist/add: Adds a new domain to the whitelist.
2. Whitelist/delete: Deletes a domain from the whitelist.
3. Whitelist/list: List all domains in the whitelist.
4. Blocklist/add: Adds a new domain to the blocklist.
5. Blocklist/delete: Deletes a domain from the blocklist.
6. Blocklist/list: List all domains in the blocklist.

Customize the networks that fall within a specific filter grouping:

1. Network/add: Adds a new IP address to your network list.
2. Network/delete: Deletes an IP address from the network list.
3. Network/list: List all IP addresses in the network list.

Better control of your logs:

1. Logs/list: List all the available logs for your account.
2. Logs/getstats: Get detailed stats for a specific day.
3. Logs/getdump: Get all the logs (dump) of all activity for a specific day.
4. Logs/delete: Delete a specific log (stats won’t be deleted).

Example of CleanBrowsing API Usage

Full examples of the available actions and values can be found inside your dashboard.

This is what an organization might use if they were adding a new profile to their account:

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

This is what an organization might use to whitelist a specific domain:

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

The dashboard provides an example for every function above, along with the associated errors and results.