CloudFlare API documentation v4

Getting started

CloudFlare's API exposes the entire CloudFlare infrastructure via a standardized programmatic interface. Using CloudFlare's API, you can do just about anything you can do on cloudflare.com

The CloudFlare API is a RESTful API based on HTTPS requests and JSON responses. If you are registered with CloudFlare, you can obtain your API key from the bottom of the "My Account" page, found here: Go to My account.

Endpoints

The API is accessed by making HTTPS requests to a specific version endpoint URL, in which GET, POST, PUT, PATCH, and DELETE methods dictate how your interact with the information available. Every endpoint is accessed via the SSL-enabled HTTPS (port 443) protocol

Everything (methods, parameters, etc.) is fixed to a version number, and every call must contain one. The latest version is Version 4.

The stable HTTP endpoint for the latest version is: https://api.cloudflare.com/client/v4/

Requests

Requests are expected to be sent over HTTPS and any payload formatted in JSON. All requests must include both your X-Auth-Key and X-Auth-Email as headers to authenticate.

Responses

Format

Each response is a JSON object. The data you requested is wrapped in the result tag. This means if you have a response, it will always be within the result field. We also include a success flag, an array of potential errors and messages in the response.

An error object will contain an integer code field and a message

Date fields will always be in UTC ISO-8601 format, including microseconds.

A username used to access other cloudflare services, like support"cfuser12345"

min length: 3

max length: 90

telephonestring

User's telephone number"+1 123-123-1234"

max length: 20

countrystring

The country in which the user lives."USA"

max length: 30

zipcodestring

The zipcode or postal code where the user lives."12345"

max length: 20

created_onstring

When the user signed up."2014-01-01T05:20:00Z"

read only

modified_onstring

Last time the user was modified"2014-01-01T05:20:00Z"

read only

api_keystring

User API key for authenticating with the API"c2547eb745579dac9321b638f5e22ccf483cc5cfdda41"

max length: 45

read only

two_factor_authentication_enabledboolean

Whether two-factor authentication is enabled for the user account. This does not apply to API authenticationfalse

valid values: (true,false)

read only

betasarray

A list of betas the user is currently participating in. If a beta is zone-specific, the beta will apply to all zones.["new_feature"]

organizationsarray

A list of the organizations the user is a member of (or invited to) and the permissions granted to them.[{"id":"9a7806061c88ada191ed06f989cc3dac","name":"CloudFlare, Inc.","status":"member","permissions":["#zones:read"],"roles":["All Privileges - Super Administrator"]}]

read only

Zone

A Zone is a domain name along with its subdomains and other identities

POST Create a zone permission needed: #zone:edit

POST /zones

Required parameters

Name /type

Description /example

Constraints

namestring

The domain name"example.com"

max length: 253

read only

Optional parameters

Name /type

Description /example

Constraints

jump_startboolean

Automatically attempt to fetch existing DNS recordstrue

default value: true

valid values: (true,false)

organizationobject

Organization that this zone will belong to{"ID":"5a7805061c76ada191ed06f989cc3dac"}

Response (example)

GET Get Browser Check setting permission needed: #zone_settings:read

Browser Integrity Check is similar to Bad Behavior and looks for common HTTP headers abused most commonly by spammers and denies access to your page. It will also challenge visitors that do not have a user agent or a non standard user agent (also commonly used by abuse bots, crawlers or visitors).

Response (example)

GET Get Cache Level setting permission needed: #zone_settings:read

Cache Level functions based off the setting level. The basic setting will cache most static resources (i.e., css, images, and JavaScript). The simplified setting will ignore the query string when delivering a cached resource. The aggressive setting will cache all static resources, including ones with a query string.

Response (example)

GET Get Challenge TTL setting permission needed: #zone_settings:read

Specify how long a visitor is allowed access to your site after successfully completing a challenge (such as a CAPTCHA). After the TTL has expired the visitor will have to complete a new challenge. We recommend a 15 - 45 minute setting and will attempt to honor any setting above 45 minutes.

Response (example)

GET Get Development Mode setting permission needed: #zone_settings:read

Development Mode temporarily allows you to enter development mode for your websites if you need to make changes to your site. This will bypass CloudFlare's accelerated cache and slow down your site, but is useful if you are making changes to cacheable content (like images, css, or JavaScript) and would like to see those changes right away. Once entered, development mode will last for 3 hours and then automatically toggle off.

When enabled, the Hotlink Protection option ensures that other sites cannot suck up your bandwidth by building pages that use images hosted on your site. Anytime a request for an image on your site hits CloudFlare, we check to ensure that it's not another site requesting them. People will still be able to download and view images from your page, but other sites won't be able to steal them for use on their own pages.

Response (example)

GET Get Rocket Loader setting permission needed: #zone_settings:read

Rocket Loader is a general-purpose asynchronous JavaScript loader coupled with a lightweight virtual browser which can safely run any JavaScript code after window.onload. Turning on Rocket Loader will immediately improve a web page's window.onload time (assuming there is JavaScript on the page), which can have a positive impact on your Google search ranking. Automatic Mode: Rocket Loader will automatically run on the JavaScript resources on your site, with no configuration required after turning on automatic mode. Manual Mode: In order to have Rocket Loader execute for a particular script, you must add the following attribute to the script tag: "data-cfasync='true'". As your page passes through CloudFlare, we'll enable Rocket Loader for that particular script. All other JavaScript will continue to execute without CloudFlare touching the script.

Response (example)

GET Get Security Level setting permission needed: #zone_settings:read

Choose the appropriate security profile for your website, which will automatically adjust each of the security settings. If you choose to customize an individual security setting, the profile will become Custom.

Response (example)

GET Get Server Side Exclude setting permission needed: #zone_settings:read

If there is sensitive content on your website that you want visible to real visitors, but that you want to hide from suspicious visitors, all you have to do is wrap the content with CloudFlare SSE tags. Wrap any content that you want to be excluded from suspicious visitors in the following SSE tags: <!--sse--><!--/sse-->. For example: <!--sse--> Bad visitors won't see my phone number, 555-555-5555 <!--/sse-->. Note: SSE only will work with HTML. If you have HTML minification enabled, you won't see the SSE tags in your HTML source when it's served through CloudFlare. SSE will still function in this case, as CloudFlare's HTML minification and SSE functionality occur on-the-fly as the resource moves through our network to the visitor's computer.

Response (example)

GET Get SSL setting permission needed: #zone_settings:read

SSL encrypts your visitor's connection and safeguards credit card numbers and other personal data to and from your website. SSL can take up to 5 minutes to fully activate. Requires CloudFlare active on your root domain or www domain. Off: no SSL between the visitor and CloudFlare, and no SSL between CloudFlare and your web server (all HTTP traffic). Flexible: SSL between the visitor and CloudFlare -- visitor sees HTTPS on your site, but no SSL between CloudFlare and your web server. You don't need to have an SSL cert on your web server, but your vistors will still see the site as being HTTPS enabled. Full: SSL between the visitor and CloudFlare -- visitor sees HTTPS on your site, and SSL between CloudFlare and your web server. You'll need to have your own SSL cert or self-signed cert at the very least. Full (Strict): SSL between the visitor and CloudFlare -- visitor sees HTTPS on your site, and SSL between CloudFlare and your web server. You'll need to have a valid SSL certificate installed on your web server. This certificate must be signed by a certificate authority, have an expiration date in the future, and respond for the request domain name (hostname).

The WAF examines HTTP requests to your website. It inspects both GET and POST requests and applies rules to help filter out illegitimate traffic from legitimate website visitors. The CloudFlare WAF inspects website addresses or URLs to detect anything out of the ordinary. If the CloudFlare WAF determines suspicious user behavior, then the WAF will ‘challenge’ the web visitor with a page that asks them to submit a CAPTCHA successfully to continue their action. If the challenge is failed, the action will be stopped. What this means is that CloudFlare’s WAF will block any traffic identified as illegitimate before it reaches your origin web server.

Browser Integrity Check is similar to Bad Behavior and looks for common HTTP headers abused most commonly by spammers and denies access to your page. It will also challenge visitors that do not have a user agent or a non standard user agent (also commonly used by abuse bots, crawlers or visitors).

Cache Level functions based off the setting level. The basic setting will cache most static resources (i.e., css, images, and JavaScript). The simplified setting will ignore the query string when delivering a cached resource. The aggressive setting will cache all static resources, including ones with a query string.

Specify how long a visitor is allowed access to your site after successfully completing a challenge (such as a CAPTCHA). After the TTL has expired the visitor will have to complete a new challenge. We recommend a 15 - 45 minute setting and will attempt to honor any setting above 45 minutes.

Development Mode temporarily allows you to enter development mode for your websites if you need to make changes to your site. This will bypass CloudFlare's accelerated cache and slow down your site, but is useful if you are making changes to cacheable content (like images, css, or JavaScript) and would like to see those changes right away. Once entered, development mode will last for 3 hours and then automatically toggle off.

When enabled, the Hotlink Protection option ensures that other sites cannot suck up your bandwidth by building pages that use images hosted on your site. Anytime a request for an image on your site hits CloudFlare, we check to ensure that it's not another site requesting them. People will still be able to download and view images from your page, but other sites won't be able to steal them for use on their own pages.

Rocket Loader is a general-purpose asynchronous JavaScript loader coupled with a lightweight virtual browser which can safely run any JavaScript code after window.onload. Turning on Rocket Loader will immediately improve a web page's window.onload time (assuming there is JavaScript on the page), which can have a positive impact on your Google search ranking. Automatic Mode: Rocket Loader will automatically run on the JavaScript resources on your site, with no configuration required after turning on automatic mode. Manual Mode: In order to have Rocket Loader execute for a particular script, you must add the following attribute to the script tag: "data-cfasync='true'". As your page passes through CloudFlare, we'll enable Rocket Loader for that particular script. All other JavaScript will continue to execute without CloudFlare touching the script.

Choose the appropriate security profile for your website, which will automatically adjust each of the security settings. If you choose to customize an individual security setting, the profile will become Custom.

If there is sensitive content on your website that you want visible to real visitors, but that you want to hide from suspicious visitors, all you have to do is wrap the content with CloudFlare SSE tags. Wrap any content that you want to be excluded from suspicious visitors in the following SSE tags: <!--sse--><!--/sse-->. For example: <!--sse--> Bad visitors won't see my phone number, 555-555-5555 <!--/sse-->. Note: SSE only will work with HTML. If you have HTML minification enabled, you won't see the SSE tags in your HTML source when it's served through CloudFlare. SSE will still function in this case, as CloudFlare's HTML minification and SSE functionality occur on-the-fly as the resource moves through our network to the visitor's computer.

Response (example)

PATCH Change SSL setting permission needed: #zone_settings:edit

SSL encrypts your visitor's connection and safeguards credit card numbers and other personal data to and from your website. SSL can take up to 5 minutes to fully activate. Requires CloudFlare active on your root domain or www domain. Off: no SSL between the visitor and CloudFlare, and no SSL between CloudFlare and your web server (all HTTP traffic). Flexible: SSL between the visitor and CloudFlare -- visitor sees HTTPS on your site, but no SSL between CloudFlare and your web server. You don't need to have an SSL cert on your web server, but your vistors will still see the site as being HTTPS enabled. Full: SSL between the visitor and CloudFlare -- visitor sees HTTPS on your site, and SSL between CloudFlare and your web server. You'll need to have your own SSL cert or self-signed cert at the very least. Full (Strict): SSL between the visitor and CloudFlare -- visitor sees HTTPS on your site, and SSL between CloudFlare and your web server. You'll need to have a valid SSL certificate installed on your web server. This certificate must be signed by a certificate authority, have an expiration date in the future, and respond for the request domain name (hostname).

The WAF examines HTTP requests to your website. It inspects both GET and POST requests and applies rules to help filter out illegitimate traffic from legitimate website visitors. The CloudFlare WAF inspects website addresses or URLs to detect anything out of the ordinary. If the CloudFlare WAF determines suspicious user behavior, then the WAF will ‘challenge’ the web visitor with a page that asks them to submit a CAPTCHA successfully to continue their action. If the challenge is failed, the action will be stopped. What this means is that CloudFlare’s WAF will block any traffic identified as illegitimate before it reaches your origin web server.

Whether or not this setting can be modified for this zone (based on your CloudFlare plan level)true

default value: true

valid values: (true, false)

modified_onstring

last time this setting was modified"2014-01-01T05:20:00.12345Z"

time_remainingnumber

Value of the zone setting3600

notes: The interval (in seconds) from when development mode expires (positive integer) or last expired (negative integer) for the domain. If development mode has never been enabled, this value is false.

Optional parameters

Name /type

Description /example

Constraints

bundle_methodstring

A ubiquitous bundle is a bundle that has a higher probability of being verified everywhere, even by clients using outdated or unusual trust stores. An optimal bundle is a bundle with the shortest chain and newest intermediates. A forced method attempt to use the certificate/chain as defined by the input"ubiquitous"

Optional parameters

Name /type

Description /example

Constraints

bundle_methodstring

A ubiquitous bundle is a bundle that has a higher probability of being verified everywhere, even by clients using outdated or unusual trust stores. An optimal bundle is a bundle with the shortest chain and newest intermediates. A forced method attempt to use the certificate/chain as defined by the input"ubiquitous"

The order/priority in which the certificate will be used in a request. Higher numbers will be tried first.1

default value: 20

statusstring

Status of the zone's custom SSL"active"

valid values: (active, expired, deleted)

read only

bundle_methodstring

A ubiquitous bundle is a bundle that has a higher probability of being verified everywhere, even by clients using outdated or unusual trust stores. An optimal bundle is a bundle with the shortest chain and newest intermediates. A forced method attempt to use the certificate/chain as defined by the input"ubiquitous"

default value: ubiquitous

valid values: (ubiquitous, optimal, force)

zone_idstring

API item identifier tag"9a7806061c88ada191ed06f989cc3dac"

max length: 32

read only

permissionsarray

Available permissions on the SSL certificate for the current user requesting the item["#ssl:read","#ssl:edit"]

read only

uploaded_onstring

When the certificate was uploaded to CloudFlare"2014-01-01T05:20:00Z"

read only

modified_onstring

When the certificate was last modified"2014-01-01T05:20:00Z"

read only

expires_onstring

When the certificate from the authority expires"2016-01-01T05:20:00Z"

read only

keyless_serverobject

A Keyless certificate is an SSL certificate where the SSL private key is not stored on CloudFlare{"id":"9a7806061c88ada191ed06f989cc3dac","name":"example.com Keyless SSL","host":"example.com","port":24008,"status":"active","enabled":false,"permissions":["#ssl:read","#ssl:edit"],"created_on":"2014-01-01T05:20:00Z","modified_on":"2014-01-01T05:20:00Z"}

Optional parameters

Name /type

Description /example

Constraints

bundle_methodstring

A ubiquitous bundle is a bundle that has a higher probability of being verified everywhere, even by clients using outdated or unusual trust stores. An optimal bundle is a bundle with the shortest chain and newest intermediates. A forced method attempt to use the certificate/chain as defined by the input"ubiquitous"