CloudFlare Wiki

Search help:

 Type what you're looking for. We will try to find it for you!

Client Interface API


This page document's CloudFlare's Client Interface API. The Client Interface API is used to check or modify the settings of a CloudFlare account.

Contents

Overview

This API will allow you to:

  • Retrieve basic statistics for your website
  • Retrieve the settings for features such as your Basic Security Level and whether you are currently in Development Mode
  • Toggle on/off the Development Mode feature to temporarily bypass the CloudFlare cache
  • Change the current Basic Security Level
  • Request a purge of the CloudFlare cache
  • Check whether a particular website/domain is associated with an account

To interface with the CloudFlare Client Interface API you will need:

  • Your API Key (which is available on your Account page or if you are a hosting partner, it gets authenticated through the Host API key)
  • Your account's email address
  • The root domain name for a website under your account

You may interface with the API via HTTPS POST or GET requests to www.cloudflare.com/api_json.html. Unencrypted HTTP requests are not supported. (This means you *must* use HTTPS.) Responses are returned in a JSON format.

Ask for a JSONP callback by appending a &callback=mycallback parameter.

Note that all calls are rate limited to 300 per hour, unless otherwise specified. Check the number of calls remaining by adding the parameter &calls_left to any request.

Interface Examples

GET Example

https://www.cloudflare.com/api_json.html?a=stats&z=example.com&u=[email protected]&tkn=799df833d7a42adf3b8e2fd113c7260b955b8e95ac42c

POST Example (example code is PHP v.5.0+) 

   $url = "https://www.cloudflare.com/api_json.html";

   $data = array(
             "a" => "stats",
             "z" => "example.com",
             "u" => "[email protected]",
             "tkn" => "799df833d7a42adf3b8e2fd113c7260b955b8e95ac42c",
             );

   $ch = curl_init();

   curl_setopt($ch, CURLOPT_VERBOSE, 1);
   curl_setopt($ch, CURLOPT_FORBID_REUSE, true); 
   curl_setopt($ch, CURLOPT_URL, $url);
   curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); 
   curl_setopt($ch, CURLOPT_POST, 1);
   curl_setopt($ch, CURLOPT_POSTFIELDS, $data ); 
   curl_setopt($ch, CURLOPT_TIMEOUT, 10);

   $http_result = curl_exec($ch);
   $error = curl_error($ch);

   $http_code = curl_getinfo($ch ,CURLINFO_HTTP_CODE);

   curl_close($ch);
   
   if ($http_code != 200) {
       print "Error: $error\n";
   } else {
       print_r(json_decode($http_result));
   }

Supported Functions

FUNCTION: Current Stats and Settings

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.

Interface 

[a] = stats
[tkn] = Your API Key
[email] = [email protected]
[z] = example.com
[interval] = 20  --- see below.

JSON Response

{"response":{"result":{"timeZero":1287797054000,"count":1,"has_more":false,"objs":[{"cachedServerTime":1290561854000,"cachedExpryTime":1290605054000,"trafficBreakdown":{"pageviews":{"regular":195,"threat":1,"crawler":20},"uniques":{"regular":17,"threat":1,"crawler":10}},"bandwidthServed":{"cloudflare":1497.6806640625,"user":1037.56640625},"requestsServed":{"cloudflare":715,"user":400},"pageLoadTime":{"without":0.47,"cloudflare":0.31},"totalUserTimeSaved":null,"currentServerTime":1290561855000,"interval":20,"userSecuritySetting":"High",dev_mode: 0}]}},"result":"success","msg":null} 

pageviews -- Number of Page Views in the last 30 days, broken up by type.
uniques -- Number of unique IP Addresses, broken up by type.
bandwidthServed -- Number of Bytes send from your server to CloudFlare (user), and from CloudFlare to others on your behalf (cloudflare). 
requestsServed -- Number of raw requests handled by CloudFlare (cloudflare), and requests which were forwarded to your server (user).
pageLoadTime -- Average time taken to load a page view with CloudFlare (cloudflare), and without (without).
userSecuritySetting -- Current user security setting.
dev_mode -- Is the zone currently in dev_mode? 0 if never. Otherwise, timestamp of when dev_move last ended (if in the past) or will end (if in the future).

The interval parameter defines what period you want to look at. Default is 30 days, but 1 day delayed. Pro only intervals are 100, 110, and 120. 

10 = 1 year (between 366 and 1 days ago) 
20 = 30 day (between 31 and 1 days ago) 
30 = 7 day (between 8 and 1 days ago)
40 = 24 hours ago (between 2 and 1 days ago)

<pro only> 

100 = 24 hours ago (between 24 and 0 hours ago)
110 = 12 hours ago (between 12 and 0 hour ago)
120 = 6 hours ago (between 6 and 0 hours ago)

FUNCTION: Set Security Level (sec_lvl)

This function sets the Basic Security Level to HELP I'M UNDER ATTACK / HIGH / MEDIUM / LOW / ESSENTIALLY OFF.

Interface 

[a] = sec_lvl
[tkn] = Your API Key
[email] = [email protected]
[z] = example.com
[v] = help|high|med|low|eoff

JSON Response

{"result":"success","msg":null}

v must be one of low|med|high|help|eoff

FUNCTION: Set Cache Level (cache_lvl)

This function sets the Caching Level to Aggressive or Basic.

Interface 

[a] = cache_lvl
[tkn] = Your API Key
[email] = [email protected]
[z] = example.com
[v] = agg|basic

JSON Response

{"result":"success","msg":null}

v must be one of agg|basic


FUNCTION: Toggle Development Mode (devmode)

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.

Interface 

[a] = devmode
[tkn] = Your API Key
[email] = [email protected]
[z] = example.com
[v] =1

"v" may be set to 1 (on) or 0 (off).

JSON Response 

{"response":{"expires_on":1290572007},"result":"success","msg":null}

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.

FUNCTION: Purge Cache (fpurge_ts)

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.

Interface 

[a] = fpurge_ts
[tkn] = Your API Key
[email] = [email protected]
[z] = example.com
[v] = 1

JSON Response 

{"response":{"fpurge_ts":1290561459},"result":"success","msg":null,"attributes":{"cooldown":20}}

fpurge_ts -- time at which cache was purged
cooldown -- number of seconds before the next time this call is allowed again.

FUNCTION: Zone Check (zone_check)

Check whether one or more websites/domains are active under an account and return the zone ids (zids) for these.

Interface 

[a] = zone_check
[tkn] = Your API Key
[email] = [email protected]
[zones] = example.com,anotherexample.com,yetanotherexample.com

JSON Response

{"response":{"zones":{"linuxdating.com":1099,"supertriceratops.com":2018,"ld.com":0,"unspam.com":0}},"result":"success","msg":null}

result -- Map of passed in zones. If a zone if hosted on CloudFlare AND the email + tkn combination is correct for the given zone, the value for the zone will be its zone id (use this for other API calls). Otherwise 0.

FUNCTION: Pull recent IPs hitting your site (zone_ips)

Returns a list of IP addresses which hit your site classified by type.

Interface 

[a] = zone_ips
[tkn] = Your API Key
[email] = [email protected]
[zid] = ID of the zone you would like to check. 
[hours] = Number of hours to go back. Default is 24, max is 48.
[class] = Restrict the result set to a given class. Currently r|s|t, for regular, crawler, threat resp.
[geo] = Optional token. Add to add longitude and latitude information to the response. 0,0 means no data.

JSON Response

{"response":{"ips":[{ip: "50.17.204.51", classification: "regular", hits: 6}]},"result":"success","msg":null}

FUNCTION: Update the snapshot of your site for CloudFlare's challenge page

Tells CloudFlare to take a new image of your site.

Interface 

[a] = zone_grab
[tkn] = Your API Key
[email] = [email protected]
[zid] = ID of the zone you would like to check.

JSON Response

{"response":{"set":[{time: 1303943984}]},"result":"success","msg":null}

Note that this call is rate limited to once per zone per day. Also the new image may take up to 1 hour to appear.

FUNCTION: Reporting spam to CloudFlare

Used to alert CloudFlare of spam which your site received.

Interface

Make a GET request to the following URL: https://www.cloudflare.com/ajax/external-event.html. Use the parameters: 

[u] = [email protected]
[tkn] = Your API Key
[evnt_t] = CF_USER_SPAM
[evnt_v] = a json encoded array of the form:

array("a" => author of spam,
        "am" => author email,
        "ip" => offending IP,
        "content" => up to 100 characters of the spam);

Make sure to also url_encode the jsonafied array.

Note that this call is rate limited to 150 calls per hour.

FUNCTION: White-list and Black-list an IP address

You can add an IP address to your white or black lists.

Interface

Make a GET request to the following url:

https://www.cloudflare.com/api.html?a=wl&key=116.74.99.115&u=[email protected]&tkn=cf-auth-token.

Parameters include

a -- The action you wish to make. Possible values are "wl" for white-listing and "ban" for black listing. key -- The address you wish to set a rule for. u -- The email you use to log in to cloudflare.com. tkn -- Your CloudFlare authentication token. Get one by going to the my-account section of cloudflare.com.

Response

On success returns string OK

On failure returns:

E_UNAUTH -- Authorization could not be completed. E_INVLDIP -- Malformed IPv4 address passed in. E_INVLDINPUT -- Some other input was not valid. E_MAXAPI -- You have exceeded your allowed number of API calls.

FUNCTION: Create a new DNS record

Creates a new DNS record for your site. This can be either a CNAME or A record.

Interface 

[a] =rec_set
[tkn] = Your API Key
[zone] = zone
[email] = [email protected]
[type] = A|CNAME
[content] = The value of the cname or IP address (the destination).
[name] = The name of the record you wish to create.
[service_mode] = 0 or 1. 0 means CloudFlare is off (grey cloud) for the new zone, while 1 means a happy orange cloud.

JSON Response

{"response":{"result":"success","msg":null}}

FUNCTION: Delete a DNS record

Deletes an existing DNS record.

Interface 

[a] =rec_del
[tkn] = Your API Key
[zone] = zone
[email] = [email protected]
[name] = The name of the record you wish to remove.

Note: all records of the given name will be deleted. For this reason, you must pass in the full DNS name of the record you wish to remove. For example, sub.foo.com, as opposed to just sub.

JSON Response

{"response":{"result":"success","msg":null}}

FUNCTION: Purge The Preloader Cache

Purges the preloader's cache.

Interface 

[a] =pre_purge
[tkn] = Your API Key
[zone_name] = IP Address
[email] = Email

Note, can take up to an hour for this to take effect.

JSON Response

{"response":{"result":"success","msg":null}}

FUNCTION: Update an existing DNS record

Update a DNS record for your site. This needs to be an A record.

Interface 

[a] = DIUP
[tkn] = Your API Key
[u] = [email protected]
[ip] = The value of the IP address (the destination).
[hosts] = The name of the record you wish to adjust.

JSON Response

{"response":{"result":"success","msg":null}}

FUNCTION: Check the threat score for a given IP

Find the current threat score for a given IP. Note that scores are logarithmically increasing, like the Richter scale.

Interface 

[a] = ip_lkup
[tkn] = Your API Key
[u] = [email protected]
[ip] = IP to check

JSON Response

{response: {1.0.171.33: "BAD:11"}, result: "success", msg: null}

Where BAD marks a threat, SE marks a search engine.

FUNCTION: Toggle IPv6 support for your site

Toggles ipv6 support for a site.

Interface 

[a] = ipv46
[tkn] = Your API Key
[u] = [email protected]
[z] = mysite.com
[v] = [0|1] --- 0 disables, 1 enables support.

JSON Response

{"response":{"result":"success","msg":null}}


Error Conditions

For all calls, errors result in the following response: {"result":"error","msg":"Detailed error message","err_code":"Code"}

For example: {"result":"error","msg":"Invalid zone name","err_code":"E_UNAUTH"}

Retrieved from "http://www.cloudflare.com/wiki/Client_Interface_API"