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)
  • 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. Responses are returned in a JSON format.

Interface Examples

GET Example

https://www.cloudflare.com/api_json.html?a=stats&z=example.com&u=me@example.com&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" => "me@example.com",
             "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] = me@example.com
[z] = example.com

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).

FUNCTION: Set Security Level (sec_lvl)

This function sets the Basic Security Level to HIGH / MEDIUM / LOW.

Interface

[a] = sec_lvl
[tkn] = Your API Key
[email] = me@example.com
[z] = example.com
[v] = high

JSON Response

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

v must be one of low|med|high

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] = me@example.com
[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] = me@example.com
[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.

Interface

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

One or more zones may be passed in the "zones" paramater as a comma-separated list.

JSON Response

{"response":{"zones":{"linuxdating.com":true,"supertriceratops.com":true,"ld.com":false,"unspam.com":false}},"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 TRUE. Otherwise FALSE.

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"}