This document explains in detail the semantics of the function calls you can make using the Client Interface API.
In this document, you will learn:
This document is subject to change. The latest version of this document is always maintained at:
https://www.cloudflare.com/docs/client-api.html
If you have comments, find errors, or have questions, please contact [email protected]
Interaction with the CloudFlare system is accomplished with POST requests through the secure HTTP protocol (HTTPS). This protocol was chosen for its simplicity, network administrators' familiarity with it, its ability to pass through many corporate firewalls without requiring their modification, the protocol's extensive documentation, and the wide availability of access tools written in many languages.
Some links concerning establishing and performing POST requests over secure HTTP sessions are provided below:
There are some general issues that you should keep in mind when designing an application for interacting with this API. You may want to refer to this checklist as you are constructing the application. Neglecting to follow these general guidelines is the usual source of difficulty for application designers.
&callback=mycallback parameter.All GET/POST requests should be directed at the client gateway interface, located at:
https://www.cloudflare.com/api_json.htmlEvery GET/POST request must include at the following basic parameter(s):
This is the API key made available on your Account page.
The e-mail address associated with the API key.
To define which request is being made, the client should POST an
"a" parameter. The "a" specifies which action you'd like to perform.
Specific actions are described in Section 3 below.
If there are errors, the JSON response will include a detailed message in the "msg" field, and sometimes will include one of the following error codes:
Retrieve the current stats and settings for a particular website. This function can be used to get currently settings of values such as the security level.
| Input: | Requires the basic parameters described in Section 2.1 of this document. In addition, you must pass the following parameters:
Here is an example POST to the stats action for retrieving the past 7 days of statistics for example.com: curl https://www.cloudflare.com/api_json.html \ -d 'a=stats' \ -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'email=[email protected]' \ -d 'z=example.com' \ -d 'interval=20' |
| Output: |
{
|
This lists all domains in a CloudFlare account along with other data.
| Input: | Requires the basic parameters described in Section 2.1 of this document. Here is an example POST to the zone_load_multi action for retrieving the list of domains: curl https://www.cloudflare.com/api_json.html \ -d 'a=zone_load_multi' \ -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'email=[email protected]' \ |
| Output: |
{
|
Lists all of the DNS records from a particular domain in a CloudFlare account
| Input: | Requires the basic parameters described in Section 2.1 of this document. In addition you must pass the following parameters:
Here is an example POST to the rec_load_all action for retrieving the DNS records for example.com: curl https://www.cloudflare.com/api_json.html \ -d 'a=rec_load_all' \ -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'email=[email protected]' \ -d 'z=example.com' |
| Output: |
{
|
| Input: | Requires the basic parameters described in Section 2.1 of this document. In addition you must pass the following parameters:
Here is an example POST to the zone_check checking for the zids for a list of different zones: curl https://www.cloudflare.com/api_json.html \ -d 'a=zone_check' \ -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'email=[email protected]' \ -d 'zones=example.com,example2.com,example3.com' |
| Output: |
{
|
Returns a list of IP address which hit your site classified by type.
| Input: | Requires the basic parameters described in Section 2.1 of this document. In addition you must pass the following parameters:
Here is an example POST to the zone_ips action for pulling recent IPs of regular visitors and their location that visited example.com in the last 48 hours: curl https://www.cloudflare.com/api_json.html \ -d 'a=zone_ips' \ -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'email=[email protected]' \ -d 'z=example.com' \ -d 'hours=48' \ -d 'class=r' \ -d 'geo=1' |
| Output: |
{
|
Find the current threat score for a given IP. Note that scores are on a logarithmic scale, where a higher score indicates a higher threat.
| Input: | Requires the basic parameters described in Section 2.1 of this document. In addition you must pass the following parameters:
Here is an example POST to the ip_lkup for looking up the threat score for an example IP: curl https://www.cloudflare.com/api_json.html \ -d 'a=ip_lkup' \ -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'email=[email protected]' \ -d 'ip=0.0.0.0' |
| Output: |
{
|
Retrieves all current settings for a given domain.
| Input: | Requires the basic parameters described in Section 2.1 of this document. In addition you must pass the following parameters:
Here is an example POST to the zone_settings for looking up settings for example.com: curl https://www.cloudflare.com/api_json.html \ -d 'a=zone_settings' \ -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'email=[email protected]' \ -d 'z=example.com' |
| Output: |
{
Explanation of some of the significant fields
|
This function sets the Basic Security Level to I'M UNDER ATTACK! / HIGH / MEDIUM / LOW / ESSENTIALLY OFF.
| Input: | Requires the basic parameters described in Section 2.1 of this document. In addition you must pass the following parameters:
Here is an example POST to the sec_lvl action for setting the security level to "I'm under attack!" for example.com: curl https://www.cloudflare.com/api_json.html \ -d 'a=sec_lvl' \ -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'email=[email protected]' \ -d 'z=example.com' \ -d 'v=help' |
| Output: |
{
|
This function sets the Caching Level to Aggressive or Basic.
| Input: | Requires the basic parameters described in Section 2.1 of this document. In addition you must pass the following parameters:
Here is an example POST to the cache_lvl action for setting the cache level to "Aggressive" for example.com: curl https://www.cloudflare.com/api_json.html \ -d 'a=cache_lvl' \ -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'email=[email protected]' \ -d 'z=example.com' \ -d 'v=agg' |
| Output: |
{
|
This function allows you to toggle Development Mode on or off for a particular domain. When Development Mode is on the cache is bypassed. Development mode remains on for 3 hours or until when it is toggled back off.
| Input: | Requires the basic parameters described in Section 2.1 of this document. In addition you must pass the following parameters:
Here is an example POST to the devmode action for turning on Development Mode for example.com: curl https://www.cloudflare.com/api_json.html \ -d 'a=devmode' \ -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'email=[email protected]' \ -d 'z=example.com' \ -d 'v=1' |
| Output: |
Development mode will expire on "expires_on" (3 hours from when it is toggled on). Development mode can be toggled off immediately by setting "v" to 0. {
|
This function will purge CloudFlare of any cached files. It may take up to 48 hours for the cache to rebuild and optimum performance to be achieved so this function should be used sparingly.
| Input: | Requires the basic parameters described in Section 2.1 of this document. In addition you must pass the following parameters:
Here is an example POST to the fpurge_ts action for purging the cache for example.com: curl https://www.cloudflare.com/api_json.html \ -d 'a=fpurge_ts' \ -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'email=[email protected]' \ -d 'z=example.com' \ -d 'v=1' |
| Output: |
{
|
This function will purge a single file from CloudFlare's cache.
| Input: | Requires the basic parameters described in Section 2.1 of this document. In addition you must pass the following parameters:
Here is an example POST to the zone_file_purge action for purging the cache for example.com: curl https://www.cloudflare.com/api_json.html \ -d 'a=zone_file_purge' \ -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'email=[email protected]' \ -d 'z=example.com' \ -d 'url=http://www.example.com/style.css' |
| Output: |
{
|
Tells CloudFlare to take a new image of your site.
| Input: | Requires the basic parameters described in Section 2.1 of this document. In addition you must pass the following parameters:
Here is an example POST to the zone_grab action for grabbing a new snapshot for for example.com: curl https://www.cloudflare.com/api_json.html \ -d 'a=zone_grab' \ -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'email=[email protected]' \ -d 'zid=42' \ Note: This API call can only be used once per day. |
| Output: |
{
|
Whitelist with "wl" and Blacklist with "ban", and use "nul" to remove the IP from either of those lists
| Input: | Requires the basic parameters described in Section 2.1 of this document. In addition you must pass the following parameters:
Here is an example POST to the wl action to whitelist an IP: curl https://www.cloudflare.com/api_json.html \ -d 'a=wl' \ -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'email=[email protected]' \ -d 'key=0.0.0.0' \ |
| Output: |
{
{
|
Toggles IPv6 support
| Input: | Requires the basic parameters described in Section 2.1 of this document. In addition you must pass the following parameters:
Here is an example POST to the ipv46 action to turn on IPv6 support for example.com: curl https://www.cloudflare.com/api_json.html \ -d 'a=ipv46' \ -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'email=[email protected]' \ -d 'z=example.com' \ -d 'v=1' |
| Output: |
{
|
Changes Rocket Loader setting
| Input: | Requires the basic parameters described in Section 2.1 of this document. In addition you must pass the following parameters:
Here is an example POST to the async action to set Rocket Loader to "automatic" for example.com: curl https://www.cloudflare.com/api_json.html \ -d 'a=async' \ -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'email=[email protected]' \ -d 'z=example.com' \ -d 'v=a' |
| Output: |
{
|
Changes minification settings
| Input: | Requires the basic parameters described in Section 2.1 of this document. In addition you must pass the following parameters:
Here is an example POST to the minify action to set minifcation for CSS and HTML for example.com: curl https://www.cloudflare.com/api_json.html \ -d 'a=minify' \ -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'email=[email protected]' \ -d 'z=example.com' \ -d 'v=6' |
| Output: |
{
|
Create a DNS record for a zone
| Input: | Requires the basic parameters described in Section 2.1 of this document. In addition you must pass the following parameters:
Here is an example POST to the rec_new action to create an A record for example.com: curl https://www.cloudflare.com/api_json.html \ -d 'a=rec_new' \ -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'email=[email protected]' \ -d 'z=example.com' \ -d 'type=A' -d 'name=sub' -d 'content=1.2.3.4' |
| Output: |
{
|
Edit a DNS record for a zone. The record will be updated to the data passed through arguments here.
| Input: | Requires the basic parameters described in Section 2.1 of this document. In addition you must pass the following parameters:
The target domain Here is an example POST to the rec_edit action to edit an A record for example.com: curl https://www.cloudflare.com/api_json.html \ -d 'a=rec_edit' \ -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'id=9001' \ -d 'email=[email protected]' \ -d 'z=example.com' \ -d 'type=A' -d 'name=sub' -d 'content=1.2.3.4' -d 'service_mode=1' -d 'ttl=1' |
| Output: |
{
|
Delete a record for a domain.
| Input: | Requires the basic parameters described in Section 2.1 of this document. In addition you must pass the following parameters:
The target domain Here is an example POST to the rec_delete action to edit A DNS record for example.com: curl https://www.cloudflare.com/api_json.html \ -d 'a=rec_delete' -d 'tkn=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'email=[email protected]' \ -d 'z=example.com' -d 'id=9001' |
| Output: |
{
|
Copyright © 2012 CloudFlare, Inc. All rights reserved.