Last modified: July 14th, 2015

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 via the customer dashboard.

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.

What is CloudFlare?

CloudFlare makes sites lightning fast, protects them from attacks, ensures they are always online, and makes it simple to add web apps with a single click. More than 5 percent of global Web requests flow through CloudFlare's network; every month more than 1.8 billion people experience a faster, safer, better Internet thanks to CloudFlare.

Audience for APIs

CloudFlare offers public APIs with three audiences in mind.

  1. CloudFlare customers
  2. CloudFlare partners
  3. Developers

Customers: Individuals and organizations all over the world choose CloudFlare to protect and accelerate their web applications. Most customers manage their settings in the web dashboard, built using these APIs. Virtually anything you can do in the customer dashboard may be done via API. Example: purging the CloudFlare edge cache for a single file when it's updated on the origin server.

Partners: Many organizations make using CloudFlare a seamless option for improving their customers' performance and security. These APIs make that easier to do at scale. Example: a CloudFlare Certified Hosting Partner may use APIs to toggle basic security mode inside a hosting control panel.

Developers: Developers all over the world create useful applications which tie into CloudFlare services. These applications may include plugins and extensions to popular content management systems, apps that are offered in the CloudFlare Apps marketplace, runbooks for specific deployment systems, and many others.

Do's and Don'ts

What can you build with CloudFlare APIs?

Anything that's useful and follows the guidelines presented here.

What should you avoid doing with CloudFlare APIs?

Do not do any of the following:

  • Abuse CloudFlare systems or customers
  • Misuse CloudFlare trademarks
  • Misrepresent CloudFlare services as your own

Abuse: Follow all guidelines, including the rate limits defined below. Your ability to use the CloudFlare APIs may be terminated, temporarily or permanently, if our systems are abused. Similarly, anything in an application which goes against the goal of making CloudFlare more useful to CloudFlare customers or attempts to mistreat customers or their data will be grounds for termination.

Trademarks: CloudFlare has several registered trademarks. Details on how and when you may use CloudFlare trademarks are found at https://www.cloudflare.com/trademark, with links to specifics on logo use and spelling. Please review carefully.

Misrepresentation: Draw a clear line between the benefits you provide in your application and those benefits of the CloudFlare service that you enable via API. The APIs are not intended for "white labeling" or reselling CloudFlare services as your own. Nothing in your service or application should create a false sense of endorsement, sponsorship, or association with CloudFlare. You may sell your own application or service which utilizes the CloudFlare APIs, but may not sell CloudFlare services to customers without a commercial agreement with CloudFlare.

The full CloudFlare Terms of Use are found at https://www.cloudflare.com/terms.

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 only 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 HTTPS endpoint for the latest version is: https://api.cloudflare.com/client/v4/

Requests

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

Required parameters

Name Format Description
API Key X-Auth-Key API key generated on the "My Account" page
Email X-Auth-Email Email address associated with your account

Example request

Requests are generally formatted as follows:

GET /object/:object_id
cURL (example)
curl -X GET "https://api.cloudflare.com/client/v4/zones/cd7d0123e3012345da9420df9514dad0" \ -H "Content-Type:application/json" \ -H "X-Auth-Key:1234567893feefc5f0q5000bfo0c38d90bbeb" \ -H "X-Auth-Email:[email protected]"

Rate limiting

The CloudFlare API sets a maximum of 1,200 requests in a five minute period.

Pagination

Depending on your request, the results returned may be limited. You can page through the returned results with the following query parameters.

Name Type Description
page integer Which page of results to return
per_page integer How many results to return per page
order string Attribute name to order the responses by
direction string Either asc or desc
cURL (example)
GET /zones/:zone_identifier/dns_records
curl -X GET "https://api.cloudflare.com/client/v4/zones/cd7d068de3012345da9420df9514dad0/dns_records?page=3&per_page=20&order=type&direction=asc" \ -H "Content-Type:application/json" \ -H "X-Auth-Key:1234567893feefc5f0q5000bfo0c38d90bbeb" \ -H "X-Auth-Email:[email protected]"

Responses

Format

Each response is a JSON object. The data requested is wrapped in the result tag. 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. Some responses can have additional pagination info wrapped in the result_info

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

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

Success Response (example)
{ "result": { "id":"2d4d028de3015345da9420df5514dad0", "type":"A", "name":"blog.example.com", "content":"2.6.4.5", "proxiable":true, "proxied":false, "ttl":1, "priority":0, "locked":false, "zone_id":"cd7d068de3012345da9420df9514dad0", "zone_name":"example.com", "modified_on":"2014-05-28T18:46:18.764425Z", "created_on":"2014-05-28T18:46:18.764425Z" }, "success": true, "errors": [], "messages": [], "result_info": { "page": 1, "per_page": 20, "count": 1, "total_count": 200 } }
Error Response (example)
{ "result": {} "success": false, "errors": [{"code":1003,"message":"Invalid or missing zone id."}], "messages": [] }

HTTP response codes

The status of a response can be determined from the HTTP status code.

Code Status Description
200 OK request successful
304 Not Modified
400 Bad Request request was invalid
401 Unauthorized user does not have permission
403 Forbidden request not authenticated
429 Too many requests client is rate limited
405 Method Not Allowed incorrect HTTP method provided
415 Unsupported Media Type response is not valid JSON

User

The currently logged in/authenticated User

Object definition

View properties and constraints defined on the object

Show definition

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "email": "[email protected]", "first_name": "John", "last_name": "Appleseed", "username": "cfuser12345", "telephone": "+1 123-123-1234", "country": "US", "zipcode": "12345", "created_on": "2014-01-01T05:20:00Z", "modified_on": "2014-01-01T05:20:00Z", "api_key": "c2547eb745579dac9321b638f5e22ccf483cc5cfdda41", "two_factor_authentication_enabled": false }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
email
string

Your contact email address

"[email protected]"
  • max length: 90
first_name
string

User's first name

"John"
  • max length: 60
last_name
string

User's last name

"Appleseed"
  • max length: 60
username
string

A username used to access other cloudflare services, like support

"cfuser12345"
  • min length: 3
  • max length: 90
telephone
string

User's telephone number

"+1 123-123-1234"
  • max length: 20
country
string

The country in which the user lives.

"US"
  • max length: 30
zipcode
string

The zipcode or postal code where the user lives.

"12345"
  • max length: 20
created_on
string

When the user signed up.

"2014-01-01T05:20:00Z"
  • read only
modified_on
string

Last time the user was modified

"2014-01-01T05:20:00Z"
  • read only
api_key
string

User API key for authenticating with the API

"c2547eb745579dac9321b638f5e22ccf483cc5cfdda41"
  • max length: 45
  • read only
two_factor_authentication_enabled
boolean

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

false
  • valid values: (true,false)
  • read only
betas
array

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"]
organizations
array

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

GET User details

GET /user
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/user" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac", "email": "[email protected]", "first_name": "John", "last_name": "Appleseed", "username": "cfuser12345", "telephone": "+1 123-123-1234", "country": "US", "zipcode": "12345", "created_on": "2014-01-01T05:20:00Z", "modified_on": "2014-01-01T05:20:00Z", "api_key": "c2547eb745579dac9321b638f5e22ccf483cc5cfdda41", "two_factor_authentication_enabled": false } }

PATCH Update user

Update part of your user details

PATCH /user

Optional parameters

Name /type Description /example Constraints
first_name
string

User's first name

"John"
  • max length: 60
last_name
string

User's last name

"Appleseed"
  • max length: 60
telephone
string

User's telephone number

"+1 123-123-1234"
  • max length: 20
country
string

The country in which the user lives.

"US"
  • max length: 30
zipcode
string

The zipcode or postal code where the user lives.

"12345"
  • max length: 20
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/user" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"first_name":"John","last_name":"Appleseed","telephone":"+1 123-123-1234","country":"US","zipcode":"12345"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac", "email": "[email protected]", "first_name": "John", "last_name": "Appleseed", "username": "cfuser12345", "telephone": "+1 123-123-1234", "country": "US", "zipcode": "12345", "created_on": "2014-01-01T05:20:00Z", "modified_on": "2014-01-01T05:20:00Z", "api_key": "c2547eb745579dac9321b638f5e22ccf483cc5cfdda41", "two_factor_authentication_enabled": false } }

User Billing Profile

A user billing profile

Object definition

View properties and constraints defined on the object

Show definition

Example object
{ "first_name": "Bob", "last_name": "Smith", "address": "123 3rd St.", "address2": "Apt 123", "company": "CloudFlare", "city": "San Francisco", "state": "CA", "zipcode": "12345", "country": "US", "telephone": "+1 111-867-5309", "card_number": "xxxx-xxxx-xxxx-1234", "card_expiry_year": 2015, "card_expiry_month": 4, "vat": "aaa-123-987", "edited_on": "2014-03-01T12:21:02.0000Z", "created_on": "2014-03-01T12:21:02.0000Z" }
Name /type Description /example Constraints
first_name
string

The first name on the billing profile

"Bob"
  • max length: 50
last_name
string

The last name on the billing profile

"Smith"
  • max length: 90
address
string

Street address on the billing profile

"123 3rd St."
  • max length: 100
address2
string

Street address continued, apartment/suite, etc (optional)

"Apt 123"
  • max length: 100
company
string

The company name on the billing profile

"CloudFlare"
  • max length: 100
city
string

The city on the billing profile

"San Francisco"
  • max length: 80
state
string

the state/province on the billing profile

"CA"
  • max length: 40
zipcode
string

The zipcode on the billing profile

"12345"
  • max length: 25
country
string

the country of the address on the billing profile

"US"
  • max length: 50
telephone
string

The telephone associated with the billing profile

"+1 111-867-5309"
  • max length: 20
card_number
string

The last four digits of the credit card on file

"xxxx-xxxx-xxxx-1234"
  • max length: 19
  • read only
card_expiry_year
number

The year when the credit card on file expires

2015
card_expiry_month
number

The month number (1-12) of when the credit card on file expires

4
vat
string

Value Added Tax ID

"aaa-123-987"
  • max length: 255
edited_on
string

When the profile was last modified

"2014-03-01T12:21:02.0000Z"
created_on
string

When the profile was created

"2014-03-01T12:21:02.0000Z"

GET Billing Profile permission needed: #billing:read

Access your billing profile object

GET /user/billing/profile
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/user/billing/profile" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "first_name": "Bob", "last_name": "Smith", "address": "123 3rd St.", "address2": "Apt 123", "company": "CloudFlare", "city": "San Francisco", "state": "CA", "zipcode": "12345", "country": "US", "telephone": "+1 111-867-5309", "card_number": "xxxx-xxxx-xxxx-1234", "card_expiry_year": 2015, "card_expiry_month": 4, "vat": "aaa-123-987", "edited_on": "2014-03-01T12:21:02.0000Z", "created_on": "2014-03-01T12:21:02.0000Z" } }

POST Create billing profile permission needed: #billing:edit

Create your billing profile object

POST /user/billing/profile

Required parameters

Name /type Description /example Constraints
first_name
string

The first name on the billing profile

"Bob"
  • max length: 50
last_name
string

The last name on the billing profile

"Smith"
  • max length: 90
address
string

Street address on the billing profile

"123 3rd St."
  • max length: 100
city
string

The city on the billing profile

"San Francisco"
  • max length: 80
state
string

the state/province on the billing profile

"CA"
  • max length: 40
zipcode
string

The zipcode on the billing profile

"12345"
  • max length: 25
country
string

the country of the address on the billing profile

"US"
  • max length: 50
card_number
string

The last four digits of the credit card on file

"xxxx-xxxx-xxxx-1234"
  • max length: 19
  • read only
card_expiry_year
number

The year when the credit card on file expires

2015
card_expiry_month
number

The month number (1-12) of when the credit card on file expires

4
card_cvv
string

The CVV verification number on the back of the card

"123"
  • max length: 4

Optional parameters

Name /type Description /example Constraints
address2
string

Street address continued, apartment/suite, etc (optional)

"Apt 123"
  • max length: 100
vat
string

Value Added Tax ID

"aaa-123-987"
  • max length: 255
cURL (example)
$ curl -X POST "https://api.cloudflare.com/client/v4/user/billing/profile" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"first_name":"Bob","last_name":"Smith","address":"123 3rd St.","address2":"Apt 123","city":"San Francisco","state":"CA","zipcode":"12345","country":"US","card_number":"xxxx-xxxx-xxxx-1234","card_expiry_year":2015,"card_expiry_month":4,"card_cvv":"123","vat":"aaa-123-987"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "first_name": "Bob", "last_name": "Smith", "address": "123 3rd St.", "address2": "Apt 123", "company": "CloudFlare", "city": "San Francisco", "state": "CA", "zipcode": "12345", "country": "US", "telephone": "+1 111-867-5309", "card_number": "xxxx-xxxx-xxxx-1234", "card_expiry_year": 2015, "card_expiry_month": 4, "vat": "aaa-123-987", "edited_on": "2014-03-01T12:21:02.0000Z", "created_on": "2014-03-01T12:21:02.0000Z" } }

PUT Update billing profile permission needed: #billing:edit

Update your billing profile object

PUT /user/billing/profile

Required parameters

Name /type Description /example Constraints
first_name
string

The first name on the billing profile

"Bob"
  • max length: 50
last_name
string

The last name on the billing profile

"Smith"
  • max length: 90
address
string

Street address on the billing profile

"123 3rd St."
  • max length: 100
city
string

The city on the billing profile

"San Francisco"
  • max length: 80
state
string

the state/province on the billing profile

"CA"
  • max length: 40
zipcode
string

The zipcode on the billing profile

"12345"
  • max length: 25
country
string

the country of the address on the billing profile

"US"
  • max length: 50
card_number
string

The last four digits of the credit card on file

"xxxx-xxxx-xxxx-1234"
  • max length: 19
  • read only
card_expiry_year
number

The year when the credit card on file expires

2015
card_expiry_month
number

The month number (1-12) of when the credit card on file expires

4
card_cvv
string

The CVV verification number on the back of the card

"123"
  • max length: 4

Optional parameters

Name /type Description /example Constraints
address2
string

Street address continued, apartment/suite, etc (optional)

"Apt 123"
  • max length: 100
vat
string

Value Added Tax ID

"aaa-123-987"
  • max length: 255
cURL (example)
$ curl -X PUT "https://api.cloudflare.com/client/v4/user/billing/profile" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"first_name":"Bob","last_name":"Smith","address":"123 3rd St.","address2":"Apt 123","city":"San Francisco","state":"CA","zipcode":"12345","country":"US","card_number":"xxxx-xxxx-xxxx-1234","card_expiry_year":2015,"card_expiry_month":4,"card_cvv":"123","vat":"aaa-123-987"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "first_name": "Bob", "last_name": "Smith", "address": "123 3rd St.", "address2": "Apt 123", "company": "CloudFlare", "city": "San Francisco", "state": "CA", "zipcode": "12345", "country": "US", "telephone": "+1 111-867-5309", "card_number": "xxxx-xxxx-xxxx-1234", "card_expiry_year": 2015, "card_expiry_month": 4, "vat": "aaa-123-987", "edited_on": "2014-03-01T12:21:02.0000Z", "created_on": "2014-03-01T12:21:02.0000Z" } }

PATCH Update particular elements of your billing profile permission needed: #billing:edit

Update particular elements of your billing profile. This feature os only available for VAT

PATCH /user/billing/profile

Required parameters

Name /type Description /example Constraints
vat
string

Value Added Tax ID

"aaa-123-987"
  • max length: 255
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/user/billing/profile" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"vat":"aaa-123-987"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "first_name": "Bob", "last_name": "Smith", "address": "123 3rd St.", "address2": "Apt 123", "company": "CloudFlare", "city": "San Francisco", "state": "CA", "zipcode": "12345", "country": "US", "telephone": "+1 111-867-5309", "card_number": "xxxx-xxxx-xxxx-1234", "card_expiry_year": 2015, "card_expiry_month": 4, "vat": "aaa-123-987", "edited_on": "2014-03-01T12:21:02.0000Z", "created_on": "2014-03-01T12:21:02.0000Z" } }

DELETE Delete billing profile permission needed: #billing:edit

Delete your billing profile. Note: You must cancel all subscriptions to delete billing information.

DELETE /user/billing/profile
cURL (example)
$ curl -X DELETE "https://api.cloudflare.com/client/v4/user/billing/profile" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "first_name": "Bob", "last_name": "Smith", "address": "123 3rd St.", "address2": "Apt 123", "company": "CloudFlare", "city": "San Francisco", "state": "CA", "zipcode": "12345", "country": "US", "telephone": "+1 111-867-5309", "card_number": "xxxx-xxxx-xxxx-1234", "card_expiry_year": 2015, "card_expiry_month": 4, "vat": "aaa-123-987", "edited_on": "2014-03-01T12:21:02.0000Z", "created_on": "2014-03-01T12:21:02.0000Z" } }

User Billing Profile Notes

For internal system reasons, only VAT is available for update via PATCH. All other updates to this object are accomplished via PUT

User Billing History

A user billing history

Object definition

View properties and constraints defined on the object

Show definition

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "type": "charge", "action": "subscription", "description": "The billing item description", "occurred_at": "2014-03-01T12:21:59.3456Z", "amount": 20.99, "currency": "USD", "zone": { "name": "example.com" } }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
type
string

The billing item type

"charge"
  • max length: 30
  • read only
action
string

The billing item action

"subscription"
  • max length: 30
  • read only
description
string

The billing item description

"The billing item description"
  • max length: 255
  • read only
occurred_at
string

When the billing item was created

"2014-03-01T12:21:59.3456Z"
  • read only
amount
number

The amount associated with this billing item

20.99
  • read only
currency
string

The monetary unit in which pricing information is displayed

"USD"
  • read only
zone
object
{"name":"example.com"}
Show definition »
Name /type Description /example Constraints
name
string

The domain name

"example.com"
  • max length: 253
  • read only

GET Billing history permission needed: #billing:read

Access your billing history object

GET /user/billing/history

Optional parameters

Name /type Description /example Constraints
page
number

Page number of paginated results

1
  • default value: 1
  • min value: 1
per_page
number

Number of items per page

20
  • default value: 20
  • min value: 5
  • max value: 50
order
string

Field to order billing history by

"occured_at"
  • valid values: (type, occured_at, action)
type
string

The billing item type

"charge"
  • max length: 30
  • read only
occured_at
string

When the billing item was created

"2014-03-01T12:21:59.3456Z"
  • read only
action
string

The billing item action

"subscription"
  • max length: 30
  • read only
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/user/billing/history?page=1&per_page=20&order=occured_at&type=charge&occured_at=2014-03-01T12:21:59.3456Z&action=subscription" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": [ { "id": "9a7806061c88ada191ed06f989cc3dac", "type": "charge", "action": "subscription", "description": "The billing item description", "occurred_at": "2014-03-01T12:21:59.3456Z", "amount": 20.99, "currency": "USD", "zone": { "name": "example.com" } } ], "result_info": { "page": 1, "per_page": 20, "count": 1, "total_count": 2000 } }

App Subscription

A subscription associated with an app

Object definition

View properties and constraints defined on the object

Show definition

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "status": "active", "price": 20, "currency": "USD", "frequency": "monthly", "plan": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly" }, "activated_on": "2014-03-01T12:20:00Z", "cancelled_on": "2014-04-01T12:20:00Z", "expired_on": "2014-04-02T12:20:00Z", "expires_on": "2014-03-31T12:20:00Z", "renewed_on": "2014-05-11T12:20:00Z", "created_on": "2014-05-11T12:20:00Z", "app_id": "9a7806061c88ada191ed06f989cc3dac", "app_name": "Example App" }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
status
string

The state of the subscription

"active"
  • valid values: (active, expired, cancelled)
  • read only
price
number

The price of the subscription that will be billed, in US dollars

20
  • read only
currency
string

The monetary unit in which pricing information is displayed

"USD"
  • read only
frequency
string

How often the subscription is renewed automatically

"monthly"
  • valid values: (weekly, monthly, quarterly, yearly)
plan
object

Abstract CloudFlare plan

{"id":"9a7806061c88ada191ed06f989cc3dac","name":"Pro Plan","price":20,"currency":"USD","frequency":"monthly"}
Show definition »
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
name
string

The plan name

"Pro Plan"
  • max length: 80
  • read only
price
number

The price of the subscription that will be billed, in US dollars

20
  • read only
currency
string

The monetary unit in which pricing information is displayed

"USD"
  • read only
frequency
string

The frequency at which you will be billed for this plan

"monthly"
  • valid values: (weekly, monthly, quarterly, yearly)
  • read only
activated_on
string

When the subscription was activated

"2014-03-01T12:20:00Z"
  • read only
cancelled_on
string

When the subscription was cancelled

"2014-04-01T12:20:00Z"
  • read only
expired_on
string

When the subscription expired

"2014-04-02T12:20:00Z"
  • read only
expires_on
string

When the subscription will expire

"2014-03-31T12:20:00Z"
  • read only
renewed_on
string

When the subscription was renewed

"2014-05-11T12:20:00Z"
  • read only
created_on
string

When the subscription was initially created

"2014-05-11T12:20:00Z"
  • read only
app_id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
app_name
string

App name

"Example App"
  • max length: 80
zone_id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
zone_name
string

The domain name

"example.com"
  • max length: 253
  • read only

GET List permission needed: billing:read

List all of your app subscriptions

GET /user/billing/subscriptions/apps
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/user/billing/subscriptions/apps" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": [ { "id": "9a7806061c88ada191ed06f989cc3dac", "status": "active", "price": 20, "currency": "USD", "frequency": "monthly", "plan": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly" }, "activated_on": "2014-03-01T12:20:00Z", "cancelled_on": "2014-04-01T12:20:00Z", "expired_on": "2014-04-02T12:20:00Z", "expires_on": "2014-03-31T12:20:00Z", "renewed_on": "2014-05-11T12:20:00Z", "created_on": "2014-05-11T12:20:00Z", "app_id": "9a7806061c88ada191ed06f989cc3dac", "app_name": "Example App" } ], "result_info": { "page": 1, "per_page": 20, "count": 1, "total_count": 2000 } }

GET Search, sort, and paginate permission needed:

Search, sort, and paginate your subscriptions

GET /user/billing/subscriptions/apps

Optional parameters

Name /type Description /example Constraints
page
number

Page number of paginated results

1
  • default value: 1
  • min value: 1
per_page
number

Number of items per page

20
  • default value: 20
  • min value: 5
  • max value: 50
order
string

Field to order subscriptions by

"status"
  • valid values: (created_on, expires_on, activated_on, renewed_on, cancelled_on, name, status, price)
status
string

The state of the subscription

"active"
  • valid values: (active, expired, cancelled)
  • read only
price
number

The price of the subscription that will be billed, in US dollars

20
  • read only
activated_on
string

When the subscription was activated

"2014-03-01T12:20:00Z"
  • read only
expires_on
string

When the subscription will expire

"2014-03-31T12:20:00Z"
  • read only
expired_on
string

When the subscription expired

"2014-04-02T12:20:00Z"
  • read only
cancelled_on
string

When the subscription was cancelled

"2014-04-01T12:20:00Z"
  • read only
renewed_on
string

When the subscription was renewed

"2014-05-11T12:20:00Z"
  • read only
direction
string

Direction to order subscriptions

"desc"
  • valid values: (asc, desc)
match
string

Whether to match all search requirements or at least one (any)

"all"
  • default value: all
  • valid values: (any, all)
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/user/billing/subscriptions/apps?page=1&per_page=20&order=status&status=active&price=20&activated_on=2014-03-01T12:20:00Z&expires_on=2014-03-31T12:20:00Z&expired_on=2014-04-02T12:20:00Z&cancelled_on=2014-04-01T12:20:00Z&renewed_on=2014-05-11T12:20:00Z&direction=desc&match=all" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": [ { "id": "9a7806061c88ada191ed06f989cc3dac", "status": "active", "price": 20, "currency": "USD", "frequency": "monthly", "plan": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly" }, "activated_on": "2014-03-01T12:20:00Z", "cancelled_on": "2014-04-01T12:20:00Z", "expired_on": "2014-04-02T12:20:00Z", "expires_on": "2014-03-31T12:20:00Z", "renewed_on": "2014-05-11T12:20:00Z", "created_on": "2014-05-11T12:20:00Z", "app_id": "9a7806061c88ada191ed06f989cc3dac", "app_name": "Example App" } ], "result_info": { "page": 1, "per_page": 20, "count": 1, "total_count": 2000 } }

GET Info permission needed: billing:read

Billing subscription details

GET /user/billing/subscriptions/apps/:identifier
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/user/billing/subscriptions/apps/9a7806061c88ada191ed06f989cc3dac" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac", "status": "active", "price": 20, "currency": "USD", "frequency": "monthly", "plan": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly" }, "activated_on": "2014-03-01T12:20:00Z", "cancelled_on": "2014-04-01T12:20:00Z", "expired_on": "2014-04-02T12:20:00Z", "expires_on": "2014-03-31T12:20:00Z", "renewed_on": "2014-05-11T12:20:00Z", "created_on": "2014-05-11T12:20:00Z", "app_id": "9a7806061c88ada191ed06f989cc3dac", "app_name": "Example App" } }

Zone Subscription

A plan subscription associated with a zone

Object definition

View properties and constraints defined on the object

Show definition

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "status": "active", "price": 20, "currency": "USD", "frequency": "monthly", "plan": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly" }, "activated_on": "2014-03-01T12:20:00Z", "cancelled_on": "2014-04-01T12:20:00Z", "expired_on": "2014-04-02T12:20:00Z", "expires_on": "2014-03-31T12:20:00Z", "renewed_on": "2014-05-11T12:20:00Z", "created_on": "2014-05-11T12:20:00Z", "zone_id": "9a7806061c88ada191ed06f989cc3dac", "zone_name": "example.com" }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
status
string

The state of the subscription

"active"
  • valid values: (active, expired, cancelled)
  • read only
price
number

The price of the subscription that will be billed, in US dollars

20
  • read only
currency
string

The monetary unit in which pricing information is displayed

"USD"
  • read only
frequency
string

How often the subscription is renewed automatically

"monthly"
  • valid values: (weekly, monthly, quarterly, yearly)
plan
object

Abstract CloudFlare plan

{"id":"9a7806061c88ada191ed06f989cc3dac","name":"Pro Plan","price":20,"currency":"USD","frequency":"monthly"}
Show definition »
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
name
string

The plan name

"Pro Plan"
  • max length: 80
  • read only
price
number

The price of the subscription that will be billed, in US dollars

20
  • read only
currency
string

The monetary unit in which pricing information is displayed

"USD"
  • read only
frequency
string

The frequency at which you will be billed for this plan

"monthly"
  • valid values: (weekly, monthly, quarterly, yearly)
  • read only
activated_on
string

When the subscription was activated

"2014-03-01T12:20:00Z"
  • read only
cancelled_on
string

When the subscription was cancelled

"2014-04-01T12:20:00Z"
  • read only
expired_on
string

When the subscription expired

"2014-04-02T12:20:00Z"
  • read only
expires_on
string

When the subscription will expire

"2014-03-31T12:20:00Z"
  • read only
renewed_on
string

When the subscription was renewed

"2014-05-11T12:20:00Z"
  • read only
created_on
string

When the subscription was initially created

"2014-05-11T12:20:00Z"
  • read only
zone_id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
zone_name
string

The domain name

"example.com"
  • max length: 253
  • read only

GET List permission needed: #billing:read

List all of your zone plan subscriptions

GET /user/billing/subscriptions/zones
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/user/billing/subscriptions/zones" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": [ { "id": "9a7806061c88ada191ed06f989cc3dac", "status": "active", "price": 20, "currency": "USD", "frequency": "monthly", "plan": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly" }, "activated_on": "2014-03-01T12:20:00Z", "cancelled_on": "2014-04-01T12:20:00Z", "expired_on": "2014-04-02T12:20:00Z", "expires_on": "2014-03-31T12:20:00Z", "renewed_on": "2014-05-11T12:20:00Z", "created_on": "2014-05-11T12:20:00Z", "zone_id": "9a7806061c88ada191ed06f989cc3dac", "zone_name": "example.com" } ], "result_info": { "page": 1, "per_page": 20, "count": 1, "total_count": 2000 } }

GET Search, sort, and paginate permission needed:

Search, sort, and paginate your subscriptions

GET /user/billing/subscriptions/zones

Optional parameters

Name /type Description /example Constraints
page
number

Page number of paginated results

1
  • default value: 1
  • min value: 1
per_page
number

Number of items per page

20
  • default value: 20
  • min value: 5
  • max value: 50
order
string

Field to order subscriptions by

"status"
  • valid values: (created_on, expires_on, activated_on, renewed_on, cancelled_on, name, status, price)
status
string

The state of the subscription

"active"
  • valid values: (active, expired, cancelled)
  • read only
price
number

The price of the subscription that will be billed, in US dollars

20
  • read only
activated_on
string

When the subscription was activated

"2014-03-01T12:20:00Z"
  • read only
expires_on
string

When the subscription will expire

"2014-03-31T12:20:00Z"
  • read only
expired_on
string

When the subscription expired

"2014-04-02T12:20:00Z"
  • read only
cancelled_on
string

When the subscription was cancelled

"2014-04-01T12:20:00Z"
  • read only
renewed_on
string

When the subscription was renewed

"2014-05-11T12:20:00Z"
  • read only
direction
string

Direction to order subscriptions

"desc"
  • valid values: (asc, desc)
match
string

Whether to match all search requirements or at least one (any)

"all"
  • default value: all
  • valid values: (any, all)
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/user/billing/subscriptions/zones?page=1&per_page=20&order=status&status=active&price=20&activated_on=2014-03-01T12:20:00Z&expires_on=2014-03-31T12:20:00Z&expired_on=2014-04-02T12:20:00Z&cancelled_on=2014-04-01T12:20:00Z&renewed_on=2014-05-11T12:20:00Z&direction=desc&match=all" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": [ { "id": "9a7806061c88ada191ed06f989cc3dac", "status": "active", "price": 20, "currency": "USD", "frequency": "monthly", "plan": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly" }, "activated_on": "2014-03-01T12:20:00Z", "cancelled_on": "2014-04-01T12:20:00Z", "expired_on": "2014-04-02T12:20:00Z", "expires_on": "2014-03-31T12:20:00Z", "renewed_on": "2014-05-11T12:20:00Z", "created_on": "2014-05-11T12:20:00Z", "zone_id": "9a7806061c88ada191ed06f989cc3dac", "zone_name": "example.com" } ], "result_info": { "page": 1, "per_page": 20, "count": 1, "total_count": 2000 } }

GET Info permission needed: #billing:read

Billing subscription details

GET /user/billing/subscriptions/zones/:identifier
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/user/billing/subscriptions/zones/9a7806061c88ada191ed06f989cc3dac" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac", "status": "active", "price": 20, "currency": "USD", "frequency": "monthly", "plan": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly" }, "activated_on": "2014-03-01T12:20:00Z", "cancelled_on": "2014-04-01T12:20:00Z", "expired_on": "2014-04-02T12:20:00Z", "expires_on": "2014-03-31T12:20:00Z", "renewed_on": "2014-05-11T12:20:00Z", "created_on": "2014-05-11T12:20:00Z", "zone_id": "9a7806061c88ada191ed06f989cc3dac", "zone_name": "example.com" } }

User-level Firewall access rule

A firewall access rule applied to all zones owned by the user

Object definition

View properties and constraints defined on the object

Show definition

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "notes": "This rule is on because of an event that occured on date X", "allowed_modes": [ "whitelist", "block", "challenge" ], "mode": "challenge", "configuration": { "target": "ip", "value": "1.2.3.4" }, "scope": { "id": "9a7806061c88ada191ed06f989cc3dac", "email": "[email protected]", "type": "user" }, "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
notes
string

A personal note about the rule. Typically used as a reminder or explanation for the rule.

"This rule is on because of an event that occured on date X"
allowed_modes
array

The possible modes the rule can be in.

["whitelist","block","challenge"]
  • read only
mode
string

The action to apply to a matched request

"challenge"
  • valid values: (block, challenge, whitelist)
configuration
object

Rule configuration


One of the following:
Show definition »
Name /type Description /example Constraints
target
string

The request property to target

"ip"
  • valid values: (ip)
value
string

The IP address to target in requests

"1.2.3.4"
Show definition »
Name /type Description /example Constraints
target
string

The request property to target

"ip_range"
  • valid values: (ip_range)
value
string

The IP ranage to target in requests. Limited to /16 and /24

"1.2.3.4/16"
Show definition »
Name /type Description /example Constraints
target
string

The request property to target

"country"
  • valid values: (country)
value
string

The 2-digit country code to target in requests. The full list of valid country codes can be found here

"US"
scope
object

All zones owned by the user will have the rule applied.

{"id":"9a7806061c88ada191ed06f989cc3dac","email":"[email protected]","type":"user"}
Show definition »
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
email
string

Your contact email address

"[email protected]"
  • max length: 90
type
string

The scope of the rule

"user"
  • valid values: (user)
  • read only
created_on
string

When the rule was created

"2014-01-01T05:20:00.12345Z"
  • read only
modified_on
string

When the rule was last modified

"2014-01-01T05:20:00.12345Z"
  • read only

GET List access rules

Search, sort, and filter IP/country access rules

GET /user/firewall/access_rules/rules

Optional parameters

Name /type Description /example Constraints
mode
string

The action to apply to a matched request

"challenge"
  • valid values: (block, challenge, whitelist)
configuration_target
string

The rule configuration target

"ip"
  • valid values: (ip, ip_range, country)
configuration_value
string

Search by IP, range, or county code

"1.2.3.4"
page
number

Page number of paginated results

1
  • default value: 1
  • min value: 1
per_page
number

Number of rules per page

50
  • default value: 50
  • min value: 5
  • max value: 100
order
string

Field to order rules by

"mode"
  • valid values: (configuration_target, configuration_value, mode)
direction
string

Direction to order rules

"desc"
  • valid values: (asc, desc)
match
string

Whether to match all search requirements or at least one (any)

"all"
  • default value: all
  • valid values: (any, all)
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/user/firewall/access_rules/rules?mode=challenge&configuration_target=ip&configuration_value=1.2.3.4&page=1&per_page=50&order=mode&direction=desc&match=all" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": [ { "id": "9a7806061c88ada191ed06f989cc3dac", "notes": "This rule is on because of an event that occured on date X", "allowed_modes": [ "whitelist", "block", "challenge" ], "mode": "challenge", "configuration": { "target": "ip", "value": "1.2.3.4" }, "scope": { "id": "9a7806061c88ada191ed06f989cc3dac", "email": "[email protected]", "type": "user" }, "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z" } ], "result_info": { "page": 1, "per_page": 20, "count": 1, "total_count": 2000 } }

POST Create access rule

Make a new IP, IP range, or country access rule for all zones owned by the user. Note: If you would like to create an access rule that applies to a specific zone only, use the zone firewall endpoints.

POST /user/firewall/access_rules/rules

Required parameters

Name /type Description /example Constraints
mode
string

The action to apply to a matched request

"challenge"
  • valid values: (block, challenge, whitelist)
configuration
object

Rule configuration


One of the following:
Show definition »
Name /type Description /example Constraints
target
string

The request property to target

"ip"
  • valid values: (ip)
value
string

The IP address to target in requests

"1.2.3.4"
Show definition »
Name /type Description /example Constraints
target
string

The request property to target

"ip_range"
  • valid values: (ip_range)
value
string

The IP ranage to target in requests. Limited to /16 and /24

"1.2.3.4/16"
Show definition »
Name /type Description /example Constraints
target
string

The request property to target

"country"
  • valid values: (country)
value
string

The 2-digit country code to target in requests. The full list of valid country codes can be found here

"US"

Optional parameters

Name /type Description /example Constraints
notes
string

A personal note about the rule. Typically used as a reminder or explanation for the rule.

"This rule is on because of an event that occured on date X"
cURL (example)
$ curl -X POST "https://api.cloudflare.com/client/v4/user/firewall/access_rules/rules" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"mode":"challenge","configuration":{"target":"ip","value":"1.2.3.4"},"notes":"This rule is on because of an event that occured on date X"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac", "notes": "This rule is on because of an event that occured on date X", "allowed_modes": [ "whitelist", "block", "challenge" ], "mode": "challenge", "configuration": { "target": "ip", "value": "1.2.3.4" }, "scope": { "id": "9a7806061c88ada191ed06f989cc3dac", "email": "[email protected]", "type": "user" }, "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Update access rule

Update rule state and/or configuration. This will be applied across all zones owned by the user.

PATCH /user/firewall/access_rules/rules/:identifier

Optional parameters

Name /type Description /example Constraints
mode
string

The action to apply to a matched request

"challenge"
  • valid values: (block, challenge, whitelist)
configuration
object

Rule configuration


One of the following:
Show definition »
Name /type Description /example Constraints
target
string

The request property to target

"ip"
  • valid values: (ip)
value
string

The IP address to target in requests

"1.2.3.4"
Show definition »
Name /type Description /example Constraints
target
string

The request property to target

"ip_range"
  • valid values: (ip_range)
value
string

The IP ranage to target in requests. Limited to /16 and /24

"1.2.3.4/16"
Show definition »
Name /type Description /example Constraints
target
string

The request property to target

"country"
  • valid values: (country)
value
string

The 2-digit country code to target in requests. The full list of valid country codes can be found here

"US"
notes
string

A personal note about the rule. Typically used as a reminder or explanation for the rule.

"This rule is on because of an event that occured on date X"
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/user/firewall/access_rules/rules/9a7806061c88ada191ed06f989cc3dac" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"mode":"challenge","configuration":{"target":"ip","value":"1.2.3.4"},"notes":"This rule is on because of an event that occured on date X"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac", "notes": "This rule is on because of an event that occured on date X", "allowed_modes": [ "whitelist", "block", "challenge" ], "mode": "challenge", "configuration": { "target": "ip", "value": "1.2.3.4" }, "scope": { "id": "9a7806061c88ada191ed06f989cc3dac", "email": "[email protected]", "type": "user" }, "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z" } }

DELETE Delete access rule

Remove an access rule so it is no longer evaluated during requests. This will apply to all zones owned by the user

DELETE /user/firewall/access_rules/rules/:identifier
cURL (example)
$ curl -X DELETE "https://api.cloudflare.com/client/v4/user/firewall/access_rules/rules/9a7806061c88ada191ed06f989cc3dac" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac" } }

User's Organizations

A list of organizations this user is a member of

Object definition

View properties and constraints defined on the object

Show definition

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "name": "CloudFlare, Inc.", "status": "member", "permissions": [ "#zones:read" ], "roles": [ "All Privileges - Super Administrator" ] }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
name
string

Organization Name

"CloudFlare, Inc."
  • max length: 100
status
string

Whether or not the user is a member of the organization or has an inivitation pending

"member"
  • valid values: (member, invited)
permissions
array

Access permissions for this User

["#zones:read"]
  • read only
roles
array

List of role names for the User at the Organization

["All Privileges - Super Administrator"]
  • read only

GET List organizations

List organizations the user is associated with

GET /user/organizations

Optional parameters

Name /type Description /example Constraints
status
string

Whether or not the user is a member of the organization or has an inivitation pending

"member"
  • valid values: (member, invited)
name
string

Organization Name

"CloudFlare, Inc."
  • max length: 100
page
number

Page number of paginated results

1
  • default value: 1
  • min value: 1
per_page
number

Number of organizations per page

20
  • default value: 20
  • min value: 5
  • max value: 50
order
string

Field to order organizations by

"status"
  • valid values: (id, name, status)
direction
string

Direction to order organizations

"desc"
  • valid values: (asc, desc)
match
string

Whether to match all search requirements or at least one (any)

"all"
  • default value: all
  • valid values: (any, all)
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/user/organizations?status=member&name=CloudFlare, Inc.&page=1&per_page=20&order=status&direction=desc&match=all" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": [ { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "CloudFlare, Inc.", "status": "member", "permissions": [ "#zones:read" ], "roles": [ "All Privileges - Super Administrator" ] } ], "result_info": { "page": 1, "per_page": 20, "count": 1, "total_count": 2000 } }

GET Organization details

Get a specific organization the user is associated with

GET /user/organizations/:identifier
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/user/organizations/9a7806061c88ada191ed06f989cc3dac" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "CloudFlare, Inc.", "status": "member", "permissions": [ "#zones:read" ], "roles": [ "All Privileges - Super Administrator" ] } }

DELETE Leave organization

Remove association to an organization

DELETE /user/organizations/:identifier
cURL (example)
$ curl -X DELETE "https://api.cloudflare.com/client/v4/user/organizations/9a7806061c88ada191ed06f989cc3dac" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "id": "9a7806061c88ada191ed06f989cc3dac" }

User's Invites

Your pending invitations to organizations

Object definition

View properties and constraints defined on the object

Show definition

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "invited_member_id": "5a7805061c76ada191ed06f989cc3dac", "invited_member_email": "[email protected]", "organization_id": "5a7805061c76ada191ed06f989cc3dac", "organization_name": "CloudFlare, Inc.", "roles": [ { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Organization Admin", "description": "Administrative access to the entire Organization", "permissions": [ "#zones:read" ] } ], "invited_by": "[email protected]", "invited_on": "2014-01-01T05:20:00Z", "expires_on": "2014-01-01T05:20:00Z", "status": "accepted" }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
invited_member_id
string

Id of the user to be added to the Organization

"5a7805061c76ada191ed06f989cc3dac"
  • max length: 32
  • read only
invited_member_email
string

Email address of the user to be added to the Organization

"[email protected]"
  • max length: 90
organization_id
string

ID of the Organization the user will be added to

"5a7805061c76ada191ed06f989cc3dac"
  • max length: 32
  • read only
organization_name
string

Organization Name

"CloudFlare, Inc."
  • max length: 100
  • read only
roles
array

Roles to be assigned to this Member

[{"id":"9a7806061c88ada191ed06f989cc3dac","name":"Organization Admin","description":"Administrative access to the entire Organization","permissions":["#zones:read"]}]
invited_by
string

The email address of the user who created the invite

"[email protected]"
  • max length: 90
invited_on
string

When the invite was sent

"2014-01-01T05:20:00Z"
  • read only
expires_on
string

When the invite is no longer active

"2014-01-01T05:20:00Z"
  • read only
status
string

Current status of the invitation

"accepted"
  • valid values: (pending, accepted, rejected, expired)

GET List invitations

List all invitations associated with my user

GET /user/invites
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/user/invites" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": [ { "id": "9a7806061c88ada191ed06f989cc3dac", "invited_member_id": "5a7805061c76ada191ed06f989cc3dac", "invited_member_email": "[email protected]", "organization_id": "5a7805061c76ada191ed06f989cc3dac", "organization_name": "CloudFlare, Inc.", "roles": [ { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Organization Admin", "description": "Administrative access to the entire Organization", "permissions": [ "#zones:read" ] } ], "invited_by": "[email protected]", "invited_on": "2014-01-01T05:20:00Z", "expires_on": "2014-01-01T05:20:00Z", "status": "accepted" } ], "result_info": { "page": 1, "per_page": 20, "count": 1, "total_count": 2000 } }

GET Invitation details

Get the details of an invitation

GET /user/invites/:identifier
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/user/invites/9a7806061c88ada191ed06f989cc3dac" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac", "invited_member_id": "5a7805061c76ada191ed06f989cc3dac", "invited_member_email": "[email protected]", "organization_id": "5a7805061c76ada191ed06f989cc3dac", "organization_name": "CloudFlare, Inc.", "roles": [ { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Organization Admin", "description": "Administrative access to the entire Organization", "permissions": [ "#zones:read" ] } ], "invited_by": "[email protected]", "invited_on": "2014-01-01T05:20:00Z", "expires_on": "2014-01-01T05:20:00Z", "status": "accepted" } }

PATCH Respond to Invitation

Respond to an invitation

PATCH /user/invites/:identifier

Required parameters

Name /type Description /example Constraints
status
string

Status of your response to the invitation (rejected or accepted)

"accepted"
  • valid values: (accepted, rejected)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/user/invites/9a7806061c88ada191ed06f989cc3dac" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"status":"accepted"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac", "invited_member_id": "5a7805061c76ada191ed06f989cc3dac", "invited_member_email": "[email protected]", "organization_id": "5a7805061c76ada191ed06f989cc3dac", "organization_name": "CloudFlare, Inc.", "roles": [ { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Organization Admin", "description": "Administrative access to the entire Organization", "permissions": [ "#zones:read" ] } ], "invited_by": "[email protected]", "invited_on": "2014-01-01T05:20:00Z", "expires_on": "2014-01-01T05:20:00Z", "status": "accepted" } }

Zone

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

Object definitions

View properties and constraints defined on the object

Show definitions

Standard zone

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "name": "example.com", "development_mode": 7200, "original_name_servers": [ "ns1.originaldnshost.com", "ns2.originaldnshost.com" ], "original_registrar": "GoDaddy", "original_dnshost": "NameCheap", "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z", "name_servers": [ "tony.ns.cloudflare.com", "woz.ns.cloudflare.com" ], "owner": { "id": "9a7806061c88ada191ed06f989cc3dac", "email": "[email protected]", "owner_type": "user" }, "permissions": [ "#zone:read", "#zone:edit" ], "plan": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly", "legacy_id": "pro", "is_subscribed": true, "can_subscribe": true }, "plan_pending": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly", "legacy_id": "pro", "is_subscribed": true, "can_subscribe": true }, "status": "active", "paused": false, "type": "full", "checked_on": "2014-01-01T05:20:00.12345Z", "host": { "name": "Example Host", "website": "http://www.examplehost.com" }, "vanity_name_servers": [ "ns1.example.com", "ns2.example.com" ], "betas": [ "new_feature" ], "deactivation_reason": "abuse_violation", "meta": { "custom_certificate_quota": 1, "page_rule_quota": 5, "wildcard_proxiable": false, "phishing_detected": false, "multiple_railgun_connections": false } }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
name
string

The domain name

"example.com"
  • max length: 253
  • read only
development_mode
number

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

7200
  • read only
original_name_servers
array

Original name servers before moving to CloudFlare

["ns1.originaldnshost.com","ns2.originaldnshost.com"]
  • read only
original_registrar
string

Registrar for the domain at the time of switching to CloudFlare

"GoDaddy"
  • read only
original_dnshost
string

DNS host at the time of switching to CloudFlare

"NameCheap"
  • max length: 50
  • read only
created_on
string

When the zone was created

"2014-01-01T05:20:00.12345Z"
  • read only
modified_on
string

When the zone was last modified

"2014-01-01T05:20:00.12345Z"
  • read only
name_servers
array

CloudFlare-assigned name servers. This is only populated for zones that use CloudFlare DNS

["tony.ns.cloudflare.com","woz.ns.cloudflare.com"]
owner
object

Information about the owner of the zone

{"id":"9a7806061c88ada191ed06f989cc3dac","email":"[email protected]","owner_type":"user"}
One of the following:
A user that owns the zone
Show definition »
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
email
string

Your contact email address

"[email protected]"
  • max length: 90
owner_type
string

The type of owner of the zone

"user"
  • valid values: (user)
  • read only
An organization that owns the zone
Show definition »
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
name
string

Organization Name

"CloudFlare, Inc."
  • max length: 100
owner_type
string

The type of owner of the zone

"organization"
  • valid values: (organization)
  • read only
permissions
array

Available permissions on the zone for the current user requesting the item

["#zone:read","#zone:edit"]
  • read only
plan
object

A zone plan

{"id":"9a7806061c88ada191ed06f989cc3dac","name":"Pro Plan","price":20,"currency":"USD","frequency":"monthly","legacy_id":"pro","is_subscribed":true,"can_subscribe":true}
Show definition »
Name /type Description /example Constraints
id
string

API item identifier tag

"\"9a7806061c88ada191ed06f989cc3dac\""
  • max length: 32
  • read only
name
string

The plan name

"\"Pro Plan\""
  • max length: 80
  • read only
price
number

The price of the subscription that will be billed, in US dollars

"20"
  • read only
currency
string

The monetary unit in which pricing information is displayed

"\"USD\""
  • read only
frequency
string

The frequency at which you will be billed for this plan

"\"monthly\""
  • valid values: (weekly, monthly, quarterly, yearly)
  • read only
legacy_id
string

A 'friendly' identifier to indicate to the UI what plan the object is

"\"pro\""
  • valid values: (free, pro, business, enterprise)
is_subscribed
boolean

If the zone is subscribed to this plan

"true"
  • valid values: (true,false)
can_subscribe
boolean

If the zone is allowed to subscribe to this plan

"true"
  • valid values: (true,false)
plan_pending
object

A zone plan

{"id":"9a7806061c88ada191ed06f989cc3dac","name":"Pro Plan","price":20,"currency":"USD","frequency":"monthly","legacy_id":"pro","is_subscribed":true,"can_subscribe":true}
Show definition »
Name /type Description /example Constraints
id
string

API item identifier tag

"\"9a7806061c88ada191ed06f989cc3dac\""
  • max length: 32
  • read only
name
string

The plan name

"\"Pro Plan\""
  • max length: 80
  • read only
price
number

The price of the subscription that will be billed, in US dollars

"20"
  • read only
currency
string

The monetary unit in which pricing information is displayed

"\"USD\""
  • read only
frequency
string

The frequency at which you will be billed for this plan

"\"monthly\""
  • valid values: (weekly, monthly, quarterly, yearly)
  • read only
legacy_id
string

A 'friendly' identifier to indicate to the UI what plan the object is

"\"pro\""
  • valid values: (free, pro, business, enterprise)
is_subscribed
boolean

If the zone is subscribed to this plan

"true"
  • valid values: (true,false)
can_subscribe
boolean

If the zone is allowed to subscribe to this plan

"true"
  • valid values: (true,false)
status
string

Status of the zone

"active"
  • valid values: (active, pending, initializing, moved, deleted, deactivated)
  • read only
paused
boolean

Indicates if the zone is only using CloudFlare DNS services. A true value means the zone will not receive security or performance benefits.

false
  • valid values: (true,false)
  • read only
type
string

A full zone implies that DNS is hosted with CloudFlare. A partial zone is typically a partner-hosted zone or a CNAME setup.

"full"
  • valid values: (full, partial)
  • read only
checked_on
string

When the zone was last checked for activation

"2014-01-01T05:20:00.12345Z"
  • read only
host
object

Hosting partner information, if the zone signed up via a CloudFlare hosting partner

{"name":"Hosting Company, Inc.","website":"http://www.hostingcompanyinc.com"}
Show definition »
Name /type Description /example Constraints
name
string

Host company name

"Example Host"
website
string

The host's website URL

"http://www.examplehost.com"
  • read only
vanity_name_servers
array

An array of domains used for custom name servers. This is only available for Business and Enterprise plans.

["ns1.example.com","ns2.example.com"]
betas
array

A list of beta features in which the zone is participating

["new_feature"]
deactivation_reason
string

Exists only with a deactivated status and indicates the reason the zone is not resolving on the CloudFlare network.

"abuse_violation"
  • valid values: (abuse_violation, plan_limits_exceeded)
meta
object

Metadata about the domain.

{"custom_certificate_quota":1,"page_rule_quota":5,"wildcard_proxiable":false,"phishing_detected":false,"multiple_railgun_connections":false}
Show definition »
Name /type Description /example Constraints
custom_certificate_quota
number

Maximum custom certificates that can be uploaded/used.

1
  • default value: 0
page_rule_quota
number

Maximum page rules that can be created.

5
  • default value: 3
wildcard_proxiable
boolean

Indicates whether wildcard DNS records can receive CloudFlare security and performance features

false
  • valid values: (true,false)
phishing_detected
boolean

Indicates if URLs on the zone have been identified as hosting phishing content.

false
  • valid values: (true,false)
multiple_railgun_connections
boolean

Indicates whether the zone is allowed to be connected to multiple Railguns at once

false
  • valid values: (true,false)
  • read only

Partner-hosted/Partial zone

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "name": "example.com", "development_mode": 7200, "original_name_servers": [ "ns1.originaldnshost.com", "ns2.originaldnshost.com" ], "original_registrar": "GoDaddy", "original_dnshost": "NameCheap", "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z", "owner": { "id": "9a7806061c88ada191ed06f989cc3dac", "email": "[email protected]", "owner_type": "user" }, "permissions": [ "#zone:read", "#zone:edit" ], "plan": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly", "legacy_id": "pro", "is_subscribed": true, "can_subscribe": true }, "plan_pending": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly", "legacy_id": "pro", "is_subscribed": true, "can_subscribe": true }, "status": "active", "paused": false, "type": "full", "checked_on": "2014-01-01T05:20:00.12345Z", "host": { "name": "Example Host", "website": "http://www.examplehost.com" }, "vanity_name_servers": [ "ns1.example.com", "ns2.example.com" ], "betas": [ "new_feature" ], "deactivation_reason": "abuse_violation", "meta": { "custom_certificate_quota": 1, "page_rule_quota": 5, "wildcard_proxiable": false, "phishing_detected": false, "multiple_railgun_connections": false } }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
name
string

The domain name

"example.com"
  • max length: 253
  • read only
development_mode
number

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

7200
  • read only
original_name_servers
array

Original name servers before moving to CloudFlare

["ns1.originaldnshost.com","ns2.originaldnshost.com"]
  • read only
original_registrar
string

Registrar for the domain at the time of switching to CloudFlare

"GoDaddy"
  • read only
original_dnshost
string

DNS host at the time of switching to CloudFlare

"NameCheap"
  • max length: 50
  • read only
created_on
string

When the zone was created

"2014-01-01T05:20:00.12345Z"
  • read only
modified_on
string

When the zone was last modified

"2014-01-01T05:20:00.12345Z"
  • read only
owner
object

Information about the owner of the zone

{"id":"9a7806061c88ada191ed06f989cc3dac","email":"[email protected]","owner_type":"user"}
One of the following:
A user that owns the zone
Show definition »
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
email
string

Your contact email address

"[email protected]"
  • max length: 90
owner_type
string

The type of owner of the zone

"user"
  • valid values: (user)
  • read only
An organization that owns the zone
Show definition »
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
name
string

Organization Name

"CloudFlare, Inc."
  • max length: 100
owner_type
string

The type of owner of the zone

"organization"
  • valid values: (organization)
  • read only
permissions
array

Available permissions on the zone for the current user requesting the item

["#zone:read","#zone:edit"]
  • read only
plan
object

A zone plan

{"id":"9a7806061c88ada191ed06f989cc3dac","name":"Pro Plan","price":20,"currency":"USD","frequency":"monthly","legacy_id":"pro","is_subscribed":true,"can_subscribe":true}
Show definition »
Name /type Description /example Constraints
id
string

API item identifier tag

"\"9a7806061c88ada191ed06f989cc3dac\""
  • max length: 32
  • read only
name
string

The plan name

"\"Pro Plan\""
  • max length: 80
  • read only
price
number

The price of the subscription that will be billed, in US dollars

"20"
  • read only
currency
string

The monetary unit in which pricing information is displayed

"\"USD\""
  • read only
frequency
string

The frequency at which you will be billed for this plan

"\"monthly\""
  • valid values: (weekly, monthly, quarterly, yearly)
  • read only
legacy_id
string

A 'friendly' identifier to indicate to the UI what plan the object is

"\"pro\""
  • valid values: (free, pro, business, enterprise)
is_subscribed
boolean

If the zone is subscribed to this plan

"true"
  • valid values: (true,false)
can_subscribe
boolean

If the zone is allowed to subscribe to this plan

"true"
  • valid values: (true,false)
plan_pending
object

A zone plan

{"id":"9a7806061c88ada191ed06f989cc3dac","name":"Pro Plan","price":20,"currency":"USD","frequency":"monthly","legacy_id":"pro","is_subscribed":true,"can_subscribe":true}
Show definition »
Name /type Description /example Constraints
id
string

API item identifier tag

"\"9a7806061c88ada191ed06f989cc3dac\""
  • max length: 32
  • read only
name
string

The plan name

"\"Pro Plan\""
  • max length: 80
  • read only
price
number

The price of the subscription that will be billed, in US dollars

"20"
  • read only
currency
string

The monetary unit in which pricing information is displayed

"\"USD\""
  • read only
frequency
string

The frequency at which you will be billed for this plan

"\"monthly\""
  • valid values: (weekly, monthly, quarterly, yearly)
  • read only
legacy_id
string

A 'friendly' identifier to indicate to the UI what plan the object is

"\"pro\""
  • valid values: (free, pro, business, enterprise)
is_subscribed
boolean

If the zone is subscribed to this plan

"true"
  • valid values: (true,false)
can_subscribe
boolean

If the zone is allowed to subscribe to this plan

"true"
  • valid values: (true,false)
status
string

Status of the zone

"active"
  • valid values: (active, pending, initializing, moved, deleted, deactivated)
  • read only
paused
boolean

Indicates if the zone is only using CloudFlare DNS services. A true value means the zone will not receive security or performance benefits.

false
  • valid values: (true,false)
  • read only
type
string

A full zone implies that DNS is hosted with CloudFlare. A partial zone is typically a partner-hosted zone or a CNAME setup.

"full"
  • valid values: (full, partial)
  • read only
checked_on
string

When the zone was last checked for activation

"2014-01-01T05:20:00.12345Z"
  • read only
host
object

Hosting partner information, if the zone signed up via a CloudFlare hosting partner

{"name":"Hosting Company, Inc.","website":"http://www.hostingcompanyinc.com"}
Show definition »
Name /type Description /example Constraints
name
string

Host company name

"Example Host"
website
string

The host's website URL

"http://www.examplehost.com"
  • read only
vanity_name_servers
array

An array of domains used for custom name servers. This is only available for Business and Enterprise plans.

["ns1.example.com","ns2.example.com"]
betas
array

A list of beta features in which the zone is participating

["new_feature"]
deactivation_reason
string

Exists only with a deactivated status and indicates the reason the zone is not resolving on the CloudFlare network.

"abuse_violation"
  • valid values: (abuse_violation, plan_limits_exceeded)
meta
object

Metadata about the domain.

{"custom_certificate_quota":1,"page_rule_quota":5,"wildcard_proxiable":false,"phishing_detected":false,"multiple_railgun_connections":false}
Show definition »
Name /type Description /example Constraints
custom_certificate_quota
number

Maximum custom certificates that can be uploaded/used.

1
  • default value: 0
page_rule_quota
number

Maximum page rules that can be created.

5
  • default value: 3
wildcard_proxiable
boolean

Indicates whether wildcard DNS records can receive CloudFlare security and performance features

false
  • valid values: (true,false)
phishing_detected
boolean

Indicates if URLs on the zone have been identified as hosting phishing content.

false
  • valid values: (true,false)
multiple_railgun_connections
boolean

Indicates whether the zone is allowed to be connected to multiple Railguns at once

false
  • valid values: (true,false)
  • read only

POST Create a zone permission needed: #zone:edit

POST /zones

Required parameters

Name /type Description /example Constraints
name
string

The domain name

"example.com"
  • max length: 253
  • read only

Optional parameters

Name /type Description /example Constraints
jump_start
boolean

Automatically attempt to fetch existing DNS records

true
  • default value: true
  • valid values: (true,false)
organization
object

To create a zone owned by an organization, specify the organization parameter. Organization objects can be found in the User or User's Organizations endpoints. You must pass at least the ID of the organization.

{"id":"5a7805061c76ada191ed06f989cc3dac"}
Show definition »
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
name
string

Organization Name

"CloudFlare, Inc."
  • max length: 100
status
string

Status of the zone

"active"
  • valid values: (active, pending, initializing, moved, deleted, deactivated)
  • read only
permissions
array

Access permissions for this User

["#zones:read"]
  • read only
cURL (example)
$ curl -X POST "https://api.cloudflare.com/client/v4/zones" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"name":"example.com","jump_start":true,"organization":{"id":"9a7806061c88ada191ed06f989cc3dac","name":"CloudFlare, Inc.","status":"active","permissions":["#zones:read"]}}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "example.com", "development_mode": 7200, "original_name_servers": [ "ns1.originaldnshost.com", "ns2.originaldnshost.com" ], "original_registrar": "GoDaddy", "original_dnshost": "NameCheap", "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z", "name_servers": [ "tony.ns.cloudflare.com", "woz.ns.cloudflare.com" ], "owner": { "id": "9a7806061c88ada191ed06f989cc3dac", "email": "[email protected]", "owner_type": "user" }, "permissions": [ "#zone:read", "#zone:edit" ], "plan": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly", "legacy_id": "pro", "is_subscribed": true, "can_subscribe": true }, "plan_pending": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly", "legacy_id": "pro", "is_subscribed": true, "can_subscribe": true }, "status": "active", "paused": false, "type": "full", "checked_on": "2014-01-01T05:20:00.12345Z" } }

PUT Initiate another zone activation check permission needed: #zone:edit

PUT /zones/:identifier/activation_check
cURL (example)
$ curl -X PUT "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/activation_check" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac" } }

GET List zones permission needed: #zone:read

List, search, sort, and filter your zones

GET /zones

Optional parameters

Name /type Description /example Constraints
name
string

A domain name

"example.com"
  • max length: 253
status
string

Status of the zone

"active"
  • valid values: (active, pending, initializing, moved, deleted, deactivated)
  • read only
page
number

Page number of paginated results

1
  • default value: 1
  • min value: 1
per_page
number

Number of zones per page

20
  • default value: 20
  • min value: 5
  • max value: 50
order
string

Field to order zones by

"status"
  • valid values: (name, status, email)
direction
string

Direction to order zones

"desc"
  • valid values: (asc, desc)
match
string

Whether to match all search requirements or at least one (any)

"all"
  • default value: all
  • valid values: (any, all)
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones?name=example.com&status=active&page=1&per_page=20&order=status&direction=desc&match=all" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": [ { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "example.com", "development_mode": 7200, "original_name_servers": [ "ns1.originaldnshost.com", "ns2.originaldnshost.com" ], "original_registrar": "GoDaddy", "original_dnshost": "NameCheap", "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z", "name_servers": [ "tony.ns.cloudflare.com", "woz.ns.cloudflare.com" ], "owner": { "id": "9a7806061c88ada191ed06f989cc3dac", "email": "[email protected]", "owner_type": "user" }, "permissions": [ "#zone:read", "#zone:edit" ], "plan": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly", "legacy_id": "pro", "is_subscribed": true, "can_subscribe": true }, "plan_pending": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly", "legacy_id": "pro", "is_subscribed": true, "can_subscribe": true }, "status": "active", "paused": false, "type": "full", "checked_on": "2014-01-01T05:20:00.12345Z" } ], "result_info": { "page": 1, "per_page": 20, "count": 1, "total_count": 2000 } }

GET Zone details permission needed: #zone:read

GET /zones/:identifier
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "example.com", "development_mode": 7200, "original_name_servers": [ "ns1.originaldnshost.com", "ns2.originaldnshost.com" ], "original_registrar": "GoDaddy", "original_dnshost": "NameCheap", "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z", "name_servers": [ "tony.ns.cloudflare.com", "woz.ns.cloudflare.com" ], "owner": { "id": "9a7806061c88ada191ed06f989cc3dac", "email": "[email protected]", "owner_type": "user" }, "permissions": [ "#zone:read", "#zone:edit" ], "plan": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly", "legacy_id": "pro", "is_subscribed": true, "can_subscribe": true }, "plan_pending": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly", "legacy_id": "pro", "is_subscribed": true, "can_subscribe": true }, "status": "active", "paused": false, "type": "full", "checked_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Edit Zone Properties

Only one zone property can be changed at a time

PATCH /zones/:identifier

Optional parameters

Name /type Description /example Constraints
paused
boolean

Indicates if the zone is only using CloudFlare DNS services. A true value means the zone will not receive security or performance benefits.

false
  • valid values: (true,false)
  • read only
vanity_name_servers
array

An array of domains used for custom name servers. This is only available for Business and Enterprise plans.

["ns1.example.com","ns2.example.com"]
plan
object

The desired plan for the zone. Changing this value will create/cancel associated subscriptions. To view available plans for this zone, see Zone Plans

{"id":"9a7806061c88ada191ed06f989cc3dac"}
Show definition »
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"paused":true}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "example.com", "development_mode": 7200, "original_name_servers": [ "ns1.originaldnshost.com", "ns2.originaldnshost.com" ], "original_registrar": "GoDaddy", "original_dnshost": "NameCheap", "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z", "name_servers": [ "tony.ns.cloudflare.com", "woz.ns.cloudflare.com" ], "owner": { "id": "9a7806061c88ada191ed06f989cc3dac", "email": "[email protected]", "owner_type": "user" }, "permissions": [ "#zone:read", "#zone:edit" ], "plan": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly", "legacy_id": "pro", "is_subscribed": true, "can_subscribe": true }, "plan_pending": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly", "legacy_id": "pro", "is_subscribed": true, "can_subscribe": true }, "status": "active", "paused": false, "type": "full", "checked_on": "2014-01-01T05:20:00.12345Z" } }

DELETE Purge all files permission needed: #zone:edit

Remove ALL files from CloudFlare's cache

DELETE /zones/:identifier/purge_cache

Required parameters

Name /type Description /example Constraints
purge_everything
boolean

A flag that indicates all resources in CloudFlare's cache should be removed. Note: This may have dramatic affects on your origin server load after performing this action.

true
  • valid values: (true)
cURL (example)
$ curl -X DELETE "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/purge_cache" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"purge_everything":true}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac" } }

DELETE Purge individual files permission needed: #zone:edit

Remove one or more files from CloudFlare's cache

DELETE /zones/:identifier/purge_cache

Required parameters

Name /type Description /example Constraints
files
array

An array of URLs that should be removed from cache

["http://www.example.com/css/styles.css"]
  • max length: 30
cURL (example)
$ curl -X DELETE "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/purge_cache" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"files":["http://www.example.com/css/styles.css"]}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac" } }

DELETE Delete a zone permission needed: #zone:edit

Delete an existing zone.

DELETE /zones/:identifier
cURL (example)
$ curl -X DELETE "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac" } }

Zone error codes

Code Description
1000 Invalid or missing user
1002 'name' must be a valid domain
1003 'jump_start' must be boolean
1004 Failed to assign name servers
1006 Invalid or missing zone
1008 Invalid or missing Zone id
1010 Invalid Zone
1011 Invalid or missing zone
1012 Request must contain one of 'purge_everything' or 'files'
1013 'purge_everything' must be true
1014 'files' must be an array of urls
1015 Unable to purge <url>
1016 Unable to purge any urls
1017 Unable to purge all
1018 Invalid zone status
1019 Zone is already paused
1020 Invalid or missing zone
1021 Invalid zone status
1022 Zone is already unpaused
1023 Invalid or missing zone
1024 <domain> already exists
1049 <domain> is not a registered domain
1050 <domain> is currently being tasted. It is not currently a registered domain
1051 CloudFlare is already hosting <domain>
1052 An error has occurred and it has been logged. We will fix this problem promptly. We apologize for the inconvenience
1053 <domain> is already disabled
1054 <domain> is already enabled
1055 Failed to disable <domain>
1056 preserve_ini must be a boolean
1057 Zone must be in 'initializing' status
1059 Unable to delete zone
1061 <domain> already exists
1062 Not allowed to update zone status
1063 Not allowed to update zone step
1064 Not allowed to update zone step. Bad zone status
1065 Not allowed to update zone step. Zone has already been set up
1066 Could not promote zone to step 3
1067 Invalid organization identifier passed in your organization variable
1068 Permission denied
1069 organization variable should be an organization object
1070 This operation requires a Business or Enterprise account.
1071 Vanity name server array expected.
1072 Vanity name server array cannot be empty.
1073 A name server provided is in the wrong format.
1074 Could not find a valid zone.
1075 Vanity name server array count is invalid
1076 Name servers have invalid IP addresses
1077 Could not find a valid zone.
1078 This zone has no valid vanity IPs.
1079 This zone has no valid vanity name servers.
1080 There is a conflict with one of the name servers.
1081 There are no valid vanity name servers to disable.
1082 Unable to purge '<url>'. You can only purge files for this zone
1083 Unable to purge '<url>'. Rate limit reached. Please wait if you need to perform more operations
1084 Unable to purge '<url>'.
1085 Only one property can be updated at a time
1086 Invalid property
1087 Zone is in an invalid state

Zone Plan

A zone plan

Object definition

View properties and constraints defined on the object

Show definition

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly", "legacy_id": "pro", "is_subscribed": true, "can_subscribe": true }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
name
string

The plan name

"Pro Plan"
  • max length: 80
  • read only
price
number

The price of the subscription that will be billed, in US dollars

20
  • read only
currency
string

The monetary unit in which pricing information is displayed

"USD"
  • read only
frequency
string

The frequency at which you will be billed for this plan

"monthly"
  • valid values: (weekly, monthly, quarterly, yearly)
  • read only
legacy_id
string

A 'friendly' identifier to indicate to the UI what plan the object is

"pro"
  • valid values: (free, pro, business, enterprise)
is_subscribed
boolean

If the zone is subscribed to this plan

true
  • valid values: (true,false)
can_subscribe
boolean

If the zone is allowed to subscribe to this plan

true
  • valid values: (true,false)

GET Available plans permission needed: #billing:read

List all plans the zone can subscribe to.

GET /zones/:zone_identifier/available_plans
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/available_plans" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": [ { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly", "legacy_id": "pro", "is_subscribed": true, "can_subscribe": true } ], "result_info": { "page": 1, "per_page": 20, "count": 1, "total_count": 2000 } }

GET Plan details permission needed: #billing:read

GET /zones/:zone_identifier/available_plans/:identifier
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/available_plans/9a7806061c88ada191ed06f989cc3dac" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "Pro Plan", "price": 20, "currency": "USD", "frequency": "monthly", "legacy_id": "pro", "is_subscribed": true, "can_subscribe": true } }

Zone Plan error codes

Code Description
1004 Cannot find a valid zone.
1005 Cannot find a valid plan.
1006 Cannot find a valid reseller plan.
1007 Cannot find a valid zone.

Zone Settings

A Zone setting changes how the Zone works in relation to caching, security, or other features of CloudFlare

Object definitions

View properties and constraints defined on the object

Show definitions

Always Online Mode

Example object
{ "id": "always_online", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"always_online"
  • valid values: (always_online)
value
string

Value of the zone setting

"on"
  • default value: on
  • valid values: (on, off)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Advanced DDoS Protection

Example object
{ "id": "advanced_ddos", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"advanced_ddos"
  • valid values: (advanced_ddos)
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
  • notes: Defaults to on for Business+ plans
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Browser Cache TTL

Example object
{ "id": "browser_cache_ttl", "value": 14400, "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"browser_cache_ttl"
  • valid values: (browser_cache_ttl)
value
number

Value of the zone setting

14400
  • default value: 14400
  • valid values: (30, 60, 300, 1200, 1800, 3600, 7200, 10800, 14400, 18000, 28800, 43200, 57600, 72000, 86400, 172800, 259200, 345600, 432000, 691200, 1382400, 2073600, 2678400, 5356800, 16070400, 31536000)
  • notes: The minimum TTL available depends on the plan level of the zone. (Enterprise = 30, Business = 1800, Pro = 1800, Free = 1800)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Browser Check

Example object
{ "id": "browser_check", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"browser_check"
  • valid values: (browser_check)
value
string

Value of the zone setting

"on"
  • default value: on
  • valid values: (on, off)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

CloudFlare Cache Level

Example object
{ "id": "cache_level", "value": "aggressive", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"cache_level"
  • valid values: (cache_level)
value
string

Value of the zone setting

"aggressive"
  • default value: aggressive
  • valid values: (aggressive, basic, simplified)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Challenge Page TTL

Example object
{ "id": "challenge_ttl", "value": 1800, "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"challenge_ttl"
  • valid values: (challenge_ttl)
value
number

Value of the zone setting

1800
  • default value: 1800
  • valid values: (300, 900, 1800, 2700, 3600, 7200, 10800, 14400, 28800, 57600, 86400, 604800, 2592000, 31536000)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Development Mode

Example object
{ "id": "development_mode", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z", "time_remaining": 3600 }
Name /type Description /example Constraints
id
string

ID of the zone setting

"development_mode"
  • valid values: (development_mode)
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"
time_remaining
number

Value of the zone setting

3600
  • 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.

Error Pages On

Example object
{ "id": "origin_error_page_pass_thru", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"origin_error_page_pass_thru"
  • valid values: (origin_error_page_pass_thru)
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Get String Sort

Example object
{ "id": "sort_query_string_for_cache", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"sort_query_string_for_cache"
  • valid values: (sort_query_string_for_cache)
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Email Obfuscation

Example object
{ "id": "email_obfuscation", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"email_obfuscation"
  • valid values: (email_obfuscation)
value
string

Value of the zone setting

"on"
  • default value: on
  • valid values: (on, off)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Hotlink Protection

Example object
{ "id": "hotlink_protection", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"hotlink_protection"
  • valid values: (hotlink_protection)
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

IP Geolcation

Example object
{ "id": "ip_geolocation", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"ip_geolocation"
  • valid values: (ip_geolocation)
value
string

Value of the zone setting

"on"
  • default value: on
  • valid values: (on, off)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

IPv6

Example object
{ "id": "ipv6", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"ipv6"
  • valid values: (ipv6)
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (off, on, safe)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Auto-Minify Assets

Example object
{ "id": "minify", "value": { "css": "off", "html": "off", "js": "off" }, "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

Zone setting identifier

"minify"
  • valid values: (minify)
value
object

Value of the zone setting

{"css":"off","html":"off","js":"off"}
Show definition »
Name /type Description /example Constraints
css
string

Automatically minify all CSS for your website

"off"
  • default value: off
  • valid values: (on, off)
html
string

Automatically minify all HTML for your website

"off"
  • default value: off
  • valid values: (on, off)
js
string

Automatically minify all JavaScript for your website

"off"
  • default value: off
  • valid values: (on, off)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Mobile Redirect

Example object
{ "id": "mobile_redirect", "value": { "status": "off", "mobile_subdomain": "m", "strip_uri": false }, "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

identifier of the zone setting

"mobile_redirect"
  • valid values: (mobile_redirect)
value
object

Value of the zone setting

{"status":"off","mobile_subdomain":"m","strip_uri":false}
Show definition »
Name /type Description /example Constraints
status
string

Whether or not the mobile redirection is enabled

"off"
  • default value: off
  • valid values: (on, off)
mobile_subdomain
string

Which subdomain prefix you wish to redirect visitors on mobile devices to (subdomain must already exist).

"m"
  • min length: 1
strip_uri
boolean

Whether to drop the current page path and redirect to the mobile subdomain URL root or to keep the path and redirect to the same page on the mobile subdomain

false
  • valid values: (true,false)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Mirage Image Optimization

Example object
{ "id": "mirage", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"mirage"
  • valid values: (mirage)
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Polish Image Optimization

Example object
{ "id": "polish", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"polish"
  • valid values: (polish)
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (off, lossless, lossy)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Prefetch Preload

Example object
{ "id": "prefetch_preload", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"prefetch_preload"
  • valid values: (prefetch_preload)
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Response Buffering

Example object
{ "id": "response_buffering", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"response_buffering"
  • valid values: (response_buffering)
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Rocket Loader

Example object
{ "id": "rocket_loader", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"rocket_loader"
  • valid values: (rocket_loader)
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off, manual)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Security Header

Example object
{ "id": "security_header", "value": { "strict_transport_security": { "enabled": true, "max_age": 86400, "include_subdomains": true, "nosniff": true } }, "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone's security header

"security_header"
  • valid values: (security_header)
value
object
{"strict_transport_security":{"enabled":true,"max_age":86400,"include_subdomains":true,"nosniff":true}}
Show definition »
Name /type Description /example Constraints
strict_transport_security
object

Strict Transport Security

{"enabled":true,"max_age":86400,"include_subdomains":true,"nosniff":true}
Show definition »
Name /type Description /example Constraints
enabled
boolean

Whether or not strict transport security is enabled

true
  • valid values: (true,false)
max_age
number

Max age in seconds of the strict transport security

86400
include_subdomains
boolean

Include all subdomains for strict transport security

true
  • valid values: (true,false)
nosniff
boolean

Whether or not to include 'X-Content-Type-Options: nosniff' header

true
  • valid values: (true,false)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Security Level

Example object
{ "id": "security_level", "value": "medium", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"security_level"
  • valid values: (security_level)
value
string

Value of the zone setting

"medium"
  • default value: medium
  • valid values: (essentially_off, low, medium, high, under_attack)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Server Side Exclude

Example object
{ "id": "server_side_exclude", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"server_side_exclude"
  • valid values: (server_side_exclude)
value
string

Value of the zone setting

"on"
  • default value: on
  • valid values: (on, off)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

SSL

Example object
{ "id": "ssl", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"ssl"
  • valid values: (ssl)
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (off, flexible, full, full_strict)
  • notes: Depends on the zone's plan level
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

TLS Client Authentication

Example object
{ "id": "tls_client_auth", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"tls_client_auth"
  • valid values: (tls_client_auth)
value
string

value of the zone setting

"on"
  • default value: on
  • valid values: (on, off)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

True Client IP Header

Example object
{ "id": "true_client_ip_header", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"true_client_ip_header"
  • valid values: (true_client_ip_header)
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Web Application Firewall

Example object
{ "id": "waf", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"waf"
  • valid values: (waf)
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

Zone Enable TLS 1.2 Value

Example object
{ "id": "tls_1_2_only", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" }
Name /type Description /example Constraints
id
string

ID of the zone setting

"tls_1_2_only"
  • valid values: (tls_1_2_only)
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
editable
boolean

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_on
string

last time this setting was modified

"2014-01-01T05:20:00.12345Z"

GET Get all Zone settings permission needed: #zone_settings:read

Available settings for your user in relation to a zone

GET /zones/:zone_identifier/settings
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": [ { "id": "always_online", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } ], "result_info": { "page": 1, "per_page": 20, "count": 1, "total_count": 2000 } }

GET Get Advanced DDOS setting permission needed: #zone_settings:read

Advanced protection from Distributed Denial of Service (DDoS) attacks on your website. This is an uneditable value that is 'on' in the case of Business and Enterprise zones

GET /zones/:zone_identifier/settings/advanced_ddos
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/advanced_ddos" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "advanced_ddos", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

GET Get Always Online setting permission needed: #zone_settings:read

When enabled, Always Online will serve pages from our cache if your server is offline (https://support.cloudflare.com/hc/en-us/articles/200168006)

GET /zones/:zone_identifier/settings/always_online
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/always_online" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "always_online", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

GET Get Browser Cache TTL setting permission needed: #zone_settings:read

Browser Cache TTL (in seconds) specifies how long CloudFlare-cached resources will remain on your visitors' computers. CloudFlare will honor any larger times specified by your server. (https://support.cloudflare.com/hc/en-us/articles/200168276)

GET /zones/:zone_identifier/settings/browser_cache_ttl
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/browser_cache_ttl" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "browser_cache_ttl", "value": 14400, "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

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). (https://support.cloudflare.com/hc/en-us/articles/200170086)

GET /zones/:zone_identifier/settings/browser_check
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/browser_check" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "browser_check", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

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. (https://support.cloudflare.com/hc/en-us/articles/200168256)

GET /zones/:zone_identifier/settings/cache_level
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/cache_level" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "cache_level", "value": "aggressive", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

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. (https://support.cloudflare.com/hc/en-us/articles/200170136)

GET /zones/:zone_identifier/settings/challenge_ttl
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/challenge_ttl" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "challenge_ttl", "value": 1800, "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

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.

GET /zones/:zone_identifier/settings/development_mode
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/development_mode" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "development_mode", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z", "time_remaining": 3600 } }

GET Get Email Obfuscation setting permission needed: #zone_settings:read

Encrypt email adresses on your web page from bots, while keeping them visible to humans. (https://support.cloudflare.com/hc/en-us/articles/200170016)

GET /zones/:zone_identifier/settings/email_obfuscation
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/email_obfuscation" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "email_obfuscation", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

GET Get IP Geolocation setting permission needed: #zone_settings:read

Enable IP Geolocation to have CloudFlare geolocate visitors to your website and pass the country code to you. (https://support.cloudflare.com/hc/en-us/articles/200168236)

GET /zones/:zone_identifier/settings/ip_geolocation
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/ip_geolocation" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "ip_geolocation", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

GET Get IPv6 setting permission needed: #zone_settings:read

Enable IPv6 on all subdomains that are CloudFlare enabled. (https://support.cloudflare.com/hc/en-us/articles/200168586)

GET /zones/:zone_identifier/settings/ipv6
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/ipv6" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "ipv6", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

GET Get Minify setting permission needed: #zone_settings:read

Automatically minify certain assets for your website (https://support.cloudflare.com/hc/en-us/articles/200168196).

GET /zones/:zone_identifier/settings/minify
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/minify" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "minify", "value": { "css": "off", "html": "off", "js": "off" }, "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

GET Get Mobile Redirect setting permission needed: #zone_settings:read

Automatically redirect visitors on mobile devices to a mobile-optimized subdomain (https://support.cloudflare.com/hc/en-us/articles/200168336).

GET /zones/:zone_identifier/settings/mobile_redirect
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/mobile_redirect" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "mobile_redirect", "value": { "status": "off", "mobile_subdomain": "m", "strip_uri": false }, "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

GET Get Mirage setting permission needed: #zone_settings:read

Automatically optimize image loading for website visitors on mobile devices (http://blog.cloudflare.com/mirage2-solving-mobile-speed).

GET /zones/:zone_identifier/settings/mirage
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/mirage" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "mirage", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

GET Get Enable Error Pages On setting permission needed: #zone_settings:edit

CloudFlare will proxy customer error pages on any 502,504 errors on origin server instead of showing a default CloudFlare error page. This does not apply to 522 errors and is limited to Enterprise Zones.

GET /zones/:zone_identifier/settings/origin_error_page_pass_thru
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/origin_error_page_pass_thru" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "origin_error_page_pass_thru", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

GET Get Polish setting permission needed: #zone_settings:read

Strips metadata and compresses your images for faster page load times. Basic (Lossless): Reduce the size of PNG, JPEG, and GIF files - no impact on visual quality. Basic + JPEG (Lossy): Further reduce the size of JPEG files for faster image loading. Larger JPEGs are converted to progressive images, loading a lower-resolution image first and ending in a higher-resolution version. Not recommended for hi-res photography sites.

GET /zones/:zone_identifier/settings/polish
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/polish" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "polish", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

GET Get Prefetch Preload setting permission needed: #zone_settings:edit

CloudFlare will prefetch any URLs that are included in the response headers. This is limited to Enterprise Zones.

GET /zones/:zone_identifier/settings/prefetch_preload
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/prefetch_preload" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "prefetch_preload", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

GET Get Response Buffering setting permission needed: #zone_settings:edit

Enables or disables buffering of responses from the proxied server. CloudFlare may buffer the whole payload to deliver it at once to the client versus allowing it to be delivered in chunks. By default, the proxied server streams directly and is not buffered by CloudFlare. This is limited to Enterprise Zones.

GET /zones/:zone_identifier/settings/response_buffering
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/response_buffering" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "response_buffering", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

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. (https://support.cloudflare.com/hc/en-us/articles/200168056)

GET /zones/:zone_identifier/settings/rocket_loader
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/rocket_loader" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "rocket_loader", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

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

CloudFlare security header for a zone.

GET /zones/:zone_identifier/settings/security_header
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/security_header" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "security_header", "value": { "strict_transport_security": { "enabled": true, "max_age": 86400, "include_subdomains": true, "nosniff": true } }, "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

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. (https://support.cloudflare.com/hc/en-us/articles/200170056)

GET /zones/:zone_identifier/settings/security_level
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/security_level" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "security_level", "value": "medium", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

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: . For example: Bad visitors won't see my phone number, 555-555-5555 . 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. (https://support.cloudflare.com/hc/en-us/articles/200170036)

GET /zones/:zone_identifier/settings/server_side_exclude
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/server_side_exclude" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "server_side_exclude", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

GET Get Enable Query String Sort setting permission needed: #zone_settings:edit

CloudFlare will treat files with the same query strings as the same file in cache, regardless of the order of the query strings. This is limited to Enterprise Zones.

GET /zones/:zone_identifier/settings/sort_query_string_for_cache
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/sort_query_string_for_cache" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "sort_query_string_for_cache", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

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). (https://support.cloudflare.com/hc/en-us/articles/200170416)

GET /zones/:zone_identifier/settings/ssl
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/ssl" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "ssl", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

GET Get Zone Enable TLS 1.2 setting permission needed: #zone_settings:edit

Enable Crypto TLS 1.2 feature for this zone and prevent use of previous versions. This is limited to Enterprise or Business Zones.

GET /zones/:zone_identifier/settings/tls_1_2_only
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/tls_1_2_only" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "tls_1_2_only", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

GET Get TLS Client Auth setting permission needed: #zone_settings:read

TLS Client Auth requires CloudFlare to connect to your origin server using a client certificate (Enterprise Only)

GET /zones/:zone_identifier/settings/tls_client_auth
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/tls_client_auth" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "tls_client_auth", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

GET Get True Client IP setting permission needed: #zone_settings:edit

Allows customer to continue to use True Client IP (Akamai feature) in the headers we send to the origin. This is limited to Enterprise Zones.

GET /zones/:zone_identifier/settings/true_client_ip_header
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/true_client_ip_header" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "true_client_ip_header", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

GET Get Web Application Firewall (WAF) setting permission needed: #zone_settings:read

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. (https://support.cloudflare.com/hc/en-us/articles/200172016)

GET /zones/:zone_identifier/settings/waf
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/waf" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "waf", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Edit zone settings info permission needed: #zone_settings:edit

Edit settings for a zone

PATCH /zones/:zone_identifier/settings

Required parameters

Name /type Description /example Constraints
items
array

One or more zone setting objects. Must contain an ID and a value.

[{"id":"always_online","value":"on"},{"id":"browser_cache_ttl","value":18000},{"id":"ip_geolocation","value":"off"}]
  • min value: 1
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"items":[{"id":"always_online","value":"on"},{"id":"browser_cache_ttl","value":18000},{"id":"ip_geolocation","value":"off"}]}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": [ { "id": "always_online", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } ], "result_info": { "page": 1, "per_page": 20, "count": 1, "total_count": 2000 } }

PATCH Change Always Online setting permission needed: #zone_settings:edit

When enabled, Always Online will serve pages from our cache if your server is offline (https://support.cloudflare.com/hc/en-us/articles/200168006)

PATCH /zones/:zone_identifier/settings/always_online

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"on"
  • default value: on
  • valid values: (on, off)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/always_online" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"on"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "always_online", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change Browser Cache TTL setting permission needed: #zone_settings:edit

Browser Cache TTL (in seconds) specifies how long CloudFlare-cached resources will remain on your visitors' computers. CloudFlare will honor any larger times specified by your server. (https://support.cloudflare.com/hc/en-us/articles/200168276)

PATCH /zones/:zone_identifier/settings/browser_cache_ttl

Required parameters

Name /type Description /example Constraints
value
number

Value of the zone setting

14400
  • default value: 14400
  • valid values: (30, 60, 300, 1200, 1800, 3600, 7200, 10800, 14400, 18000, 28800, 43200, 57600, 72000, 86400, 172800, 259200, 345600, 432000, 691200, 1382400, 2073600, 2678400, 5356800, 16070400, 31536000)
  • notes: The minimum TTL available depends on the plan level of the zone. (Enterprise = 30, Business = 1800, Pro = 1800, Free = 1800)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/browser_cache_ttl" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":14400}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "browser_cache_ttl", "value": 14400, "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change Browser Check setting permission needed: #zone_settings:edit

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). (https://support.cloudflare.com/hc/en-us/articles/200170086)

PATCH /zones/:zone_identifier/settings/browser_check

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"on"
  • default value: on
  • valid values: (on, off)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/browser_check" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"on"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "browser_check", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change Cache Level setting permission needed: #zone_settings:edit

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. (https://support.cloudflare.com/hc/en-us/articles/200168256)

PATCH /zones/:zone_identifier/settings/cache_level

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"aggressive"
  • default value: aggressive
  • valid values: (aggressive, basic, simplified)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/cache_level" \ -H "X-Auth-Email: [email protected]" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"aggressive"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "cache_level", "value": "aggressive", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change Challenge TTL setting permission needed: #zone_settings:edit

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. (https://support.cloudflare.com/hc/en-us/articles/200170136)

PATCH /zones/:zone_identifier/settings/challenge_ttl

Required parameters

Name /type Description /example Constraints
value
number

Value of the zone setting

1800
  • default value: 1800
  • valid values: (300, 900, 1800, 2700, 3600, 7200, 10800, 14400, 28800, 57600, 86400, 604800, 2592000, 31536000)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/challenge_ttl" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":1800}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "challenge_ttl", "value": 1800, "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change Development Mode setting permission needed: #zone_settings:edit

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.

PATCH /zones/:zone_identifier/settings/development_mode

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/development_mode" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"off"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "development_mode", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z", "time_remaining": 3600 } }

PATCH Change Email Obfuscation setting permission needed: #zone_settings:edit

Encrypt email adresses on your web page from bots, while keeping them visible to humans. (https://support.cloudflare.com/hc/en-us/articles/200170016)

PATCH /zones/:zone_identifier/settings/email_obfuscation

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"on"
  • default value: on
  • valid values: (on, off)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/email_obfuscation" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"on"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "email_obfuscation", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change Enable Error Pages On setting permission needed: #zone_settings:edit

CloudFlare will proxy customer error pages on any 502,504 errors on origin server instead of showing a default CloudFlare error page. This does not apply to 522 errors and is limited to Enterprise Zones.

PATCH /zones/:zone_identifier/settings/origin_error_page_pass_thru

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/origin_error_page_pass_thru" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"off"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "origin_error_page_pass_thru", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change Enable Query String Sort setting permission needed: #zone_settings:edit

CloudFlare will treat files with the same query strings as the same file in cache, regardless of the order of the query strings. This is limited to Enterprise Zones.

PATCH /zones/:zone_identifier/settings/sort_query_string_for_cache

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/sort_query_string_for_cache" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"off"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "sort_query_string_for_cache", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change IP Geolocation setting permission needed: #zone_settings:edit

Enable IP Geolocation to have CloudFlare geolocate visitors to your website and pass the country code to you. (https://support.cloudflare.com/hc/en-us/articles/200168236)

PATCH /zones/:zone_identifier/settings/ip_geolocation

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"on"
  • default value: on
  • valid values: (on, off)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/ip_geolocation" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"on"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "ip_geolocation", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change IPv6 setting permission needed: #zone_settings:edit

Enable IPv6 on all subdomains that are CloudFlare enabled. (https://support.cloudflare.com/hc/en-us/articles/200168586)

PATCH /zones/:zone_identifier/settings/ipv6

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (off, on, safe)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/ipv6" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"off"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "ipv6", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change Minify setting permission needed: #zone_settings:edit

Automatically minify certain assets for your website (https://support.cloudflare.com/hc/en-us/articles/200168196).

PATCH /zones/:zone_identifier/settings/minify

Required parameters

Name /type Description /example Constraints
value
object

Value of the zone setting

{"css":"off","html":"off","js":"off"}
Show definition »
Name /type Description /example Constraints
css
string

Automatically minify all CSS for your website

"off"
  • default value: off
  • valid values: (on, off)
html
string

Automatically minify all HTML for your website

"off"
  • default value: off
  • valid values: (on, off)
js
string

Automatically minify all JavaScript for your website

"off"
  • default value: off
  • valid values: (on, off)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/minify" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":{"css":"off","html":"off","js":"off"}}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "minify", "value": { "css": "off", "html": "off", "js": "off" }, "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change Mobile Redirect setting permission needed: #zone_settings:edit

Automatically redirect visitors on mobile devices to a mobile-optimized subdomain (https://support.cloudflare.com/hc/en-us/articles/200168336).

PATCH /zones/:zone_identifier/settings/mobile_redirect

Required parameters

Name /type Description /example Constraints
value
object

Value of the zone setting

{"status":"off","mobile_subdomain":"m","strip_uri":false}
Show definition »
Name /type Description /example Constraints
status
string

Whether or not the mobile redirection is enabled

"off"
  • default value: off
  • valid values: (on, off)
mobile_subdomain
string

Which subdomain prefix you wish to redirect visitors on mobile devices to (subdomain must already exist).

"m"
  • min length: 1
strip_uri
boolean

Whether to drop the current page path and redirect to the mobile subdomain URL root or to keep the path and redirect to the same page on the mobile subdomain

false
  • valid values: (true,false)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/mobile_redirect" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":{"status":"off","mobile_subdomain":"m","strip_uri":false}}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "mobile_redirect", "value": { "status": "off", "mobile_subdomain": "m", "strip_uri": false }, "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change Mirage setting permission needed: #zone_settings:edit

Automatically optimize image loading for website visitors on mobile devices (http://blog.cloudflare.com/mirage2-solving-mobile-speed).

PATCH /zones/:zone_identifier/settings/mirage

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/mirage" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"off"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "mirage", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change Polish setting permission needed: #zone_settings:edit

Strips metadata and compresses your images for faster page load times. Basic (Lossless): Reduce the size of PNG, JPEG, and GIF files - no impact on visual quality. Basic + JPEG (Lossy): Further reduce the size of JPEG files for faster image loading. Larger JPEGs are converted to progressive images, loading a lower-resolution image first and ending in a higher-resolution version. Not recommended for hi-res photography sites.

PATCH /zones/:zone_identifier/settings/polish

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (off, lossless, lossy)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/polish" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"off"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "polish", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change Prefetch Preload setting permission needed: #zone_settings:edit

CloudFlare will prefetch any URLs that are included in the response headers. This is limited to Enterprise Zones.

PATCH /zones/:zone_identifier/settings/prefetch_preload

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/prefetch_preload" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"off"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "prefetch_preload", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change Response Buffering setting permission needed: #zone_settings:edit

Enables or disables buffering of responses from the proxied server. CloudFlare may buffer the whole payload to deliver it at once to the client versus allowing it to be delivered in chunks. By default, the proxied server streams directly and is not buffered by CloudFlare. This is limited to Enterprise Zones.

PATCH /zones/:zone_identifier/settings/response_buffering

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/response_buffering" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"off"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "response_buffering", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change Rocket Loader setting permission needed: #zone_settings:edit

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. (https://support.cloudflare.com/hc/en-us/articles/200168056)

PATCH /zones/:zone_identifier/settings/rocket_loader

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off, manual)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/rocket_loader" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"off"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "rocket_loader", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change Security Header setting permission needed: #zone_settings:edit

CloudFlare security header for a zone.

PATCH /zones/:zone_identifier/settings/security_header

Required parameters

Name /type Description /example Constraints
value
object
{"strict_transport_security":{"enabled":true,"max_age":86400,"include_subdomains":true,"nosniff":true}}
Show definition »
Name /type Description /example Constraints
strict_transport_security
object

Strict Transport Security

{"enabled":true,"max_age":86400,"include_subdomains":true,"nosniff":true}
Show definition »
Name /type Description /example Constraints
enabled
boolean

Whether or not strict transport security is enabled

true
  • valid values: (true,false)
max_age
number

Max age in seconds of the strict transport security

86400
include_subdomains
boolean

Include all subdomains for strict transport security

true
  • valid values: (true,false)
nosniff
boolean

Whether or not to include 'X-Content-Type-Options: nosniff' header

true
  • valid values: (true,false)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/security_header" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":{"strict_transport_security":{"enabled":true,"max_age":86400,"include_subdomains":true,"nosniff":true}}}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "security_header", "value": { "strict_transport_security": { "enabled": true, "max_age": 86400, "include_subdomains": true, "nosniff": true } }, "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change Security Level setting permission needed: #zone_settings:edit

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. (https://support.cloudflare.com/hc/en-us/articles/200170056)

PATCH /zones/:zone_identifier/settings/security_level

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"medium"
  • default value: medium
  • valid values: (essentially_off, low, medium, high, under_attack)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/security_level" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"medium"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "security_level", "value": "medium", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change Server Side Exclude setting permission needed: #zone_settings:edit

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: . For example: Bad visitors won't see my phone number, 555-555-5555 . 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. (https://support.cloudflare.com/hc/en-us/articles/200170036)

PATCH /zones/:zone_identifier/settings/server_side_exclude

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"on"
  • default value: on
  • valid values: (on, off)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/server_side_exclude" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"on"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "server_side_exclude", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

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). (https://support.cloudflare.com/hc/en-us/articles/200170416)

PATCH /zones/:zone_identifier/settings/ssl

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (off, flexible, full, full_strict)
  • notes: Depends on the zone's plan level
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/ssl" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"off"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "ssl", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change TLS Client Auth setting permission needed: #zone_settings:edit

TLS Client Auth requires CloudFlare to connect to your origin server using a client certificate (Enterprise Only)

PATCH /zones/:zone_identifier/settings/tls_client_auth

Required parameters

Name /type Description /example Constraints
value

TLS Client Auth requires CloudFlare to connect to your origin server using a client certificate (Enterprise Only)

Show definition »
Name /type Description /example Constraints
id
string

ID of the zone setting

"\"tls_client_auth\""
  • valid values: (tls_client_auth)
value
string

value of the zone setting

"\"on\""
  • default value: on
  • valid values: (on, off)
editable
boolean

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_on
string

last time this setting was modified

"\"2014-01-01T05:20:00.12345Z\""
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/tls_client_auth" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":{"id":"tls_client_auth","value":"on","editable":true,"modified_on":"2014-01-01T05:20:00.12345Z"}}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "tls_client_auth", "value": "on", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change True Client IP setting permission needed: #zone_settings:edit

Allows customer to continue to use True Client IP (Akamai feature) in the headers we send to the origin. This is limited to Enterprise Zones.

PATCH /zones/:zone_identifier/settings/true_client_ip_header

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/true_client_ip_header" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"off"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "true_client_ip_header", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change TLS 1.2 setting permission needed: #zone_settings:edit

Enable Crypto TLS 1.2 feature for this zone and prevent use of previous versions. This is limited to Enterprise or Business Zones.

PATCH /zones/:zone_identifier/settings/tls_1_2_only

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/tls_1_2_only" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"off"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "tls_1_2_only", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

PATCH Change Web Application Firewall (WAF) setting permission needed: #zone_settings:edit

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. (https://support.cloudflare.com/hc/en-us/articles/200172016)

PATCH /zones/:zone_identifier/settings/waf

Required parameters

Name /type Description /example Constraints
value
string

Value of the zone setting

"off"
  • default value: off
  • valid values: (on, off)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/settings/waf" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"value":"off"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "waf", "value": "off", "editable": true, "modified_on": "2014-01-01T05:20:00.12345Z" } }

DNS Records for a Zone

Documentation for CloudFlare DNS records

Object definitions

View properties and constraints defined on the object

Show definitions

A Record

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "type": "A", "name": "example.com", "content": "1.2.3.4", "proxiable": true, "proxied": false, "ttl": 120, "locked": false, "zone_id": "9a7806061c88ada191ed06f989cc3dac", "zone_name": "example.com", "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z", "data": {} }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
type
string

Record type

"A"
  • valid values: (A)
name
string

A valid hostname

"example.com"
  • max length: 255
content
string

A valid IPv4 address

"1.2.3.4"
proxiable
boolean

Whether the record can be proxied by CloudFlare or not

true
  • valid values: (true,false)
  • read only
proxied
boolean

Whether the record is receiving the performance and security benefits of CloudFlare

false
  • valid values: (true,false)
ttl
number

Time to live for DNS record. Value of 1 is 'automatic'

120
  • min value: 1
  • max value: 2147483647
locked
boolean

Whether this record can be modified/deleted (true means it's managed by CloudFlare)

false
  • valid values: (true,false)
  • read only
zone_id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
zone_name
string

The domain of the record

"example.com"
  • read only
created_on
string

When the record was created

"2014-01-01T05:20:00.12345Z"
  • read only
modified_on
string

When the record was last modified

"2014-01-01T05:20:00.12345Z"
  • read only
data
object

Metadata about the record

{}
meta
object

Extra CloudFlare-specific information about the record

{"auto_added":true}
Show definition »
Name /type Description /example Constraints
auto_added
boolean

Will exist if CloudFlare automatically added this DNS record during initial setup.

true
  • valid values: (true,false)

AAAA Record

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "type": "AAAA", "name": "example.com", "content": "2400:cb00:2049:1::173.245.59.16", "proxiable": true, "proxied": false, "ttl": 120, "locked": false, "zone_id": "9a7806061c88ada191ed06f989cc3dac", "zone_name": "example.com", "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z", "data": {} }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
type
string

Record type

"AAAA"
  • valid values: (AAAA)
name
string

A valid hostname

"example.com"
  • max length: 255
content
string

A valid IPv6 address

"2400:cb00:2049:1::173.245.59.16"
proxiable
boolean

Whether the record can be proxied by CloudFlare or not

true
  • valid values: (true,false)
  • read only
proxied
boolean

Whether the record is receiving the performance and security benefits of CloudFlare

false
  • valid values: (true,false)
ttl
number

Time to live for DNS record. Value of 1 is 'automatic'

120
  • min value: 1
  • max value: 2147483647
locked
boolean

Whether this record can be modified/deleted (true means it's managed by CloudFlare)

false
  • valid values: (true,false)
  • read only
zone_id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
zone_name
string

The domain of the record

"example.com"
  • read only
created_on
string

When the record was created

"2014-01-01T05:20:00.12345Z"
  • read only
modified_on
string

When the record was last modified

"2014-01-01T05:20:00.12345Z"
  • read only
data
object

Metadata about the record

{}
meta
object

Extra CloudFlare-specific information about the record

{"auto_added":true}
Show definition »
Name /type Description /example Constraints
auto_added
boolean

Will exist if CloudFlare automatically added this DNS record during initial setup.

true
  • valid values: (true,false)

CNAME Record

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "type": "CNAME", "name": "subdomain.example.com", "content": "example.com", "proxiable": true, "proxied": false, "ttl": 120, "locked": false, "zone_id": "9a7806061c88ada191ed06f989cc3dac", "zone_name": "example.com", "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z", "data": {} }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
type
string

Record type

"CNAME"
  • valid values: (CNAME)
name
string

A valid hostname

"subdomain.example.com"
  • max length: 255
content
string

A valid hostname

"example.com"
proxiable
boolean

Whether the record can be proxied by CloudFlare or not

true
  • valid values: (true,false)
  • read only
proxied
boolean

Whether the record is receiving the performance and security benefits of CloudFlare

false
  • valid values: (true,false)
ttl
number

Time to live for DNS record. Value of 1 is 'automatic'

120
  • min value: 1
  • max value: 2147483647
locked
boolean

Whether this record can be modified/deleted (true means it's managed by CloudFlare)

false
  • valid values: (true,false)
  • read only
zone_id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
zone_name
string

The domain of the record

"example.com"
  • read only
created_on
string

When the record was created

"2014-01-01T05:20:00.12345Z"
  • read only
modified_on
string

When the record was last modified

"2014-01-01T05:20:00.12345Z"
  • read only
data
object

Metadata about the record

{}
meta
object

Extra CloudFlare-specific information about the record

{"auto_added":true}
Show definition »
Name /type Description /example Constraints
auto_added
boolean

Will exist if CloudFlare automatically added this DNS record during initial setup.

true
  • valid values: (true,false)

NS Record

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "type": "NS", "name": "example.com", "content": "ns1.example.com", "proxiable": true, "proxied": false, "ttl": 120, "locked": false, "zone_id": "9a7806061c88ada191ed06f989cc3dac", "zone_name": "example.com", "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z", "data": {} }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
type
string

Record type

"NS"
  • valid values: (NS)
name
string

A valid hostname

"example.com"
  • max length: 255
content
string

A valid name server host name

"ns1.example.com"
proxiable
boolean

Whether the record can be proxied by CloudFlare or not

true
  • valid values: (true,false)
  • read only
proxied
boolean

Whether the record is receiving the performance and security benefits of CloudFlare

false
  • valid values: (true,false)
ttl
number

Time to live for DNS record. Value of 1 is 'automatic'

120
  • min value: 1
  • max value: 2147483647
locked
boolean

Whether this record can be modified/deleted (true means it's managed by CloudFlare)

false
  • valid values: (true,false)
  • read only
zone_id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
zone_name
string

The domain of the record

"example.com"
  • read only
created_on
string

When the record was created

"2014-01-01T05:20:00.12345Z"
  • read only
modified_on
string

When the record was last modified

"2014-01-01T05:20:00.12345Z"
  • read only
data
object

Metadata about the record

{}
meta
object

Extra CloudFlare-specific information about the record

{"auto_added":true}
Show definition »
Name /type Description /example Constraints
auto_added
boolean

Will exist if CloudFlare automatically added this DNS record during initial setup.

true
  • valid values: (true,false)

MX Record

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "type": "MX", "name": "example.com", "content": "mx.example.com", "proxiable": true, "proxied": false, "ttl": 120, "locked": false, "zone_id": "9a7806061c88ada191ed06f989cc3dac", "zone_name": "example.com", "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z", "data": {}, "priority": 10 }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
type
string

Record type

"MX"
  • valid values: (MX)
name
string

A valid hostname

"example.com"
  • max length: 255
content
string

A valid mail server hostname

"mx.example.com"
proxiable
boolean

Whether the record can be proxied by CloudFlare or not

true
  • valid values: (true,false)
  • read only
proxied
boolean

Whether the record is receiving the performance and security benefits of CloudFlare

false
  • valid values: (true,false)
ttl
number

Time to live for DNS record. Value of 1 is 'automatic'

120
  • min value: 1
  • max value: 2147483647
locked
boolean

Whether this record can be modified/deleted (true means it's managed by CloudFlare)

false
  • valid values: (true,false)
  • read only
zone_id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
zone_name
string

The domain of the record

"example.com"
  • read only
created_on
string

When the record was created

"2014-01-01T05:20:00.12345Z"
  • read only
modified_on
string

When the record was last modified

"2014-01-01T05:20:00.12345Z"
  • read only
data
object

Metadata about the record

{}
meta
object

Extra CloudFlare-specific information about the record

{"auto_added":true}
Show definition »
Name /type Description /example Constraints
auto_added
boolean

Will exist if CloudFlare automatically added this DNS record during initial setup.

true
  • valid values: (true,false)
priority
number

Used with some records like MX and SRV to determine priority

10
  • min value: 0
  • max value: 65535

TXT Record

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "type": "TXT", "name": "example.com", "content": "example text content", "proxiable": true, "proxied": false, "ttl": 120, "locked": false, "zone_id": "9a7806061c88ada191ed06f989cc3dac", "zone_name": "example.com", "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z", "data": {} }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
type
string

Record type

"TXT"
  • valid values: (TXT)
name
string

A valid hostname

"example.com"
  • max length: 255
content
string

Text content for the record

"example text content"
proxiable
boolean

Whether the record can be proxied by CloudFlare or not

true
  • valid values: (true,false)
  • read only
proxied
boolean

Whether the record is receiving the performance and security benefits of CloudFlare

false
  • valid values: (true,false)
ttl
number

Time to live for DNS record. Value of 1 is 'automatic'

120
  • min value: 1
  • max value: 2147483647
locked
boolean

Whether this record can be modified/deleted (true means it's managed by CloudFlare)

false
  • valid values: (true,false)
  • read only
zone_id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
zone_name
string

The domain of the record

"example.com"
  • read only
created_on
string

When the record was created

"2014-01-01T05:20:00.12345Z"
  • read only
modified_on
string

When the record was last modified

"2014-01-01T05:20:00.12345Z"
  • read only
data
object

Metadata about the record

{}
meta
object

Extra CloudFlare-specific information about the record

{"auto_added":true}
Show definition »
Name /type Description /example Constraints
auto_added
boolean

Will exist if CloudFlare automatically added this DNS record during initial setup.

true
  • valid values: (true,false)

LOC Record

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "type": "LOC", "name": "example.com", "content": "IN LOC 37 46 46 N 122 23 35 W 0m 100m 0m 0m", "proxiable": true, "proxied": false, "ttl": 120, "locked": false, "zone_id": "9a7806061c88ada191ed06f989cc3dac", "zone_name": "example.com", "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z", "data": { "lat_degrees": 37, "lat_minutes": 46, "lat_seconds": 46, "lat_direction": "N", "long_degrees": 122, "long_minutes": 23, "long_seconds": 35, "long_direction": "W", "altitude": 0, "size": 100, "precision_horz": 0, "precision_vert": 0 } }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
type
string

Record type

"LOC"
  • valid values: (LOC)
name

A valid hostname

"example.com"
  • max length: 255
content
string

Formatted LOC content. See 'data' to set LOC properties

"IN LOC 37 46 46 N 122 23 35 W 0m 100m 0m 0m"
proxiable
boolean

Whether the record can be proxied by CloudFlare or not

true
  • valid values: (true,false)
  • read only
proxied
boolean

Whether the record is receiving the performance and security benefits of CloudFlare

false
  • valid values: (true,false)
ttl
number

Time to live for DNS record. Value of 1 is 'automatic'

120
  • min value: 1
  • max value: 2147483647
locked
boolean

Whether this record can be modified/deleted (true means it's managed by CloudFlare)

false
  • valid values: (true,false)
  • read only
zone_id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
zone_name
string

The domain of the record

"example.com"
  • read only
created_on
string

When the record was created

"2014-01-01T05:20:00.12345Z"
  • read only
modified_on
string

When the record was last modified

"2014-01-01T05:20:00.12345Z"
  • read only
data
object

Components of a LOC record

{"lat_degrees":37,"lat_minutes":46,"lat_seconds":46,"lat_direction":"N","long_degrees":122,"long_minutes":23,"long_seconds":35,"long_direction":"W","altitude":0,"size":100,"precision_horz":0,"precision_vert":0}
Show definition »
Name /type Description /example Constraints
lat_degrees
number

Degrees of latitude

37
  • min value: 0
  • max value: 90
lat_minutes
number

Minutes of latitude

46
  • default value: 0
  • min value: 0
  • max value: 59
lat_seconds
number

Seconds of latitude

46
  • default value: 0
  • min value: 0
  • max value: 59
lat_direction
string

Latitude direction

"N"
  • valid values: (N, S)
long_degrees
number

Degrees of longitude

122
  • min value: 0
  • max value: 180
long_minutes
number

Minutes of longitude

23
  • default value: 0
  • min value: 0
  • max value: 59
long_seconds
number

Seconds of longitude

35
  • default value: 0
  • min value: 0
  • max value: 59
long_direction
string

Longitude direction

"W"
  • valid values: (E, W)
altitude
number

Altitude of location in meters

0
  • min value: -100000
  • max value: 42849672.95
size
number

Size of location in meters

100
  • default value: 0
  • min value: 0
  • max value: 90000000
precision_horz
number

Horizontal precision of location

0
  • default value: 0
  • min value: 0
  • max value: 90000000
precision_vert
number

Vertical precision of location

0
  • default value: 0
  • min value: 0
  • max value: 90000000
meta
object

Extra CloudFlare-specific information about the record

{"auto_added":true}
Show definition »
Name /type Description /example Constraints
auto_added
boolean

Will exist if CloudFlare automatically added this DNS record during initial setup.

true
  • valid values: (true,false)

SRV Record

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "type": "SRV", "name": "_sip._tcp.example.com", "content": "10 IN SRV 5 8806 somewhere.com.", "proxiable": true, "proxied": false, "ttl": 120, "locked": false, "zone_id": "9a7806061c88ada191ed06f989cc3dac", "zone_name": "example.com", "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z", "data": { "service": "_sip", "proto": "_tcp", "name": "example.com", "priority": 10, "weight": 5, "port": 8806, "target": "somewhere.com" } }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
type
string

Record type

"SRV"
  • valid values: (SRV)
name
string

Service, protocol, and SRV name content. See 'data' for setting the individual component values

"_sip._tcp.example.com"
  • max length: 255
content
string

Priority, weight, port, and SRV target. See 'data' for setting the individual component values

"10 IN SRV 5 8806 somewhere.com."
proxiable
boolean

Whether the record can be proxied by CloudFlare or not

true
  • valid values: (true,false)
  • read only
proxied
boolean

Whether the record is receiving the performance and security benefits of CloudFlare

false
  • valid values: (true,false)
ttl
number

Time to live for DNS record. Value of 1 is 'automatic'

120
  • min value: 1
  • max value: 2147483647
locked
boolean

Whether this record can be modified/deleted (true means it's managed by CloudFlare)

false
  • valid values: (true,false)
  • read only
zone_id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
zone_name
string

The domain of the record

"example.com"
  • read only
created_on
string

When the record was created

"2014-01-01T05:20:00.12345Z"
  • read only
modified_on
string

When the record was last modified

"2014-01-01T05:20:00.12345Z"
  • read only
data
object

Components of a SRV record

{"service":"_sip","proto":"_tcp","name":"example.com","priority":10,"weight":5,"port":8806,"target":"somewhere.com"}
Show definition »
Name /type Description /example Constraints
service
string

A service type, prefixed with an underscore

"_sip"
proto
string

A valid protocol

"_tcp"
  • valid values: (_udp, _tcp, _tls)
name
string

A valid hostname

"example.com"
priority
number

Used with some records like MX and SRV to determine priority

10
  • min value: 0
  • max value: 65535
weight
number

The record weight

5
  • min value: 0
  • max value: 65535
port
number

The port of the service

8806
  • min value: 0
  • max value: 65535
target
string

A valid hostname

"somewhere.com"
meta
object

Extra CloudFlare-specific information about the record

{"auto_added":true}
Show definition »
Name /type Description /example Constraints
auto_added
boolean

Will exist if CloudFlare automatically added this DNS record during initial setup.

true
  • valid values: (true,false)

SPF Record

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "type": "SPF", "name": "example.com", "content": "v=spf1 a ip:1.2.3.4", "proxiable": true, "proxied": false, "ttl": 120, "locked": false, "zone_id": "9a7806061c88ada191ed06f989cc3dac", "zone_name": "example.com", "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z", "data": {} }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
type
string

Record type

"SPF"
  • valid values: (SPF)
name
hostname

A valid hostname

"example.com"
  • max length: 255
content
string

A valid SPF format, starting with 'v=spf1'

"v=spf1 a ip:1.2.3.4"
proxiable
boolean

Whether the record can be proxied by CloudFlare or not

true
  • valid values: (true,false)
  • read only
proxied
boolean

Whether the record is receiving the performance and security benefits of CloudFlare

false
  • valid values: (true,false)
ttl
number

Time to live for DNS record. Value of 1 is 'automatic'

120
  • min value: 1
  • max value: 2147483647
locked
boolean

Whether this record can be modified/deleted (true means it's managed by CloudFlare)

false
  • valid values: (true,false)
  • read only
zone_id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
zone_name
string

The domain of the record

"example.com"
  • read only
created_on
string

When the record was created

"2014-01-01T05:20:00.12345Z"
  • read only
modified_on
string

When the record was last modified

"2014-01-01T05:20:00.12345Z"
  • read only
data
object

Metadata about the record

{}
meta
object

Extra CloudFlare-specific information about the record

{"auto_added":true}
Show definition »
Name /type Description /example Constraints
auto_added
boolean

Will exist if CloudFlare automatically added this DNS record during initial setup.

true
  • valid values: (true,false)

POST Create DNS record permission needed: #dns_records:edit

Create a new DNS record for a zone. See the record object definitions for required attributes for each record type

POST /zones/:zone_identifier/dns_records

Required parameters

Name /type Description /example Constraints
type
string

DNS record type

"A"
  • valid values: (A, AAAA, CNAME, TXT, SRV, LOC, MX, NS, SPF)
  • read only
name
string

DNS record name

"example.com"
  • max length: 255
content
string

DNS record content

"127.0.0.1"

Optional parameters

Name /type Description /example Constraints
ttl
number

Time to live for DNS record. Value of 1 is 'automatic'

120
  • min value: 1
  • max value: 2147483647
cURL (example)
$ curl -X POST "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/dns_records" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"type":"A","name":"example.com","content":"127.0.0.1","ttl":120}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac", "type": "A", "name": "example.com", "content": "1.2.3.4", "proxiable": true, "proxied": false, "ttl": 120, "locked": false, "zone_id": "9a7806061c88ada191ed06f989cc3dac", "zone_name": "example.com", "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z", "data": {} } }

GET List DNS Records permission needed: #dns_records:read

List, search, sort, and filter a zones' DNS records.

GET /zones/:zone_identifier/dns_records

Optional parameters

Name /type Description /example Constraints
type
string

DNS record type

"A"
  • valid values: (A, AAAA, CNAME, TXT, SRV, LOC, MX, NS, SPF)
  • read only
name
string

DNS record name

"example.com"
  • max length: 255
content
string

DNS record content

"127.0.0.1"
page
number

Page number of paginated results

1
  • default value: 1
  • min value: 1
per_page
number

Number of DNS records per page

20
  • default value: 20
  • min value: 5
  • max value: 100
order
string

Field to order records by

"type"
  • valid values: (type, name, content, ttl, proxied)
direction
string

Direction to order domains

"desc"
  • valid values: (asc, desc)
match
string

Whether to match all search requirements or at least one (any)

"all"
  • default value: all
  • valid values: (any, all)
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/dns_records?type=A&name=example.com&content=127.0.0.1&page=1&per_page=20&order=type&direction=desc&match=all" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": [ { "id": "9a7806061c88ada191ed06f989cc3dac", "type": "A", "name": "example.com", "content": "1.2.3.4", "proxiable": true, "proxied": false, "ttl": 120, "locked": false, "zone_id": "9a7806061c88ada191ed06f989cc3dac", "zone_name": "example.com", "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z", "data": {} } ], "result_info": { "page": 1, "per_page": 20, "count": 1, "total_count": 2000 } }

GET DNS record details permission needed: #dns_records:read

GET /zones/:zone_identifier/dns_records/:identifier
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/dns_records/9a7806061c88ada191ed06f989cc3dac" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac", "type": "A", "name": "example.com", "content": "1.2.3.4", "proxiable": true, "proxied": false, "ttl": 120, "locked": false, "zone_id": "9a7806061c88ada191ed06f989cc3dac", "zone_name": "example.com", "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z", "data": {} } }

PUT Update DNS record permission needed: #dns_records:edit

PUT /zones/:zone_identifier/dns_records/:identifier
cURL (example)
$ curl -X PUT "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/dns_records/9a7806061c88ada191ed06f989cc3dac" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"id":"9a7806061c88ada191ed06f989cc3dac","type":"A","name":"example.com","content":"1.2.3.4","proxiable":true,"proxied":false,"ttl":120,"locked":false,"zone_id":"9a7806061c88ada191ed06f989cc3dac","zone_name":"example.com","created_on":"2014-01-01T05:20:00.12345Z","modified_on":"2014-01-01T05:20:00.12345Z","data":{}}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac", "type": "A", "name": "example.com", "content": "1.2.3.4", "proxiable": true, "proxied": false, "ttl": 120, "locked": false, "zone_id": "9a7806061c88ada191ed06f989cc3dac", "zone_name": "example.com", "created_on": "2014-01-01T05:20:00.12345Z", "modified_on": "2014-01-01T05:20:00.12345Z", "data": {} } }

DELETE Delete DNS record permission needed: #dns_records:edit

DELETE /zones/:zone_identifier/dns_records/:identifier
cURL (example)
$ curl -X DELETE "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/dns_records/9a7806061c88ada191ed06f989cc3dac" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac" } }

DNS Records for a Zone error codes

Code Description
1000 Invalid user
1002 Invalid or missing zone_id
1003 per_page must be a positive integer
1004 Invalid or missing zone
1005 Invalid or missing record
1007 name required
1008 content required
1009 Invalid or missing record id
1010 Invalid or missing record
1011 Zone file for '<domain name>' could not be found
1012 Zone file for '<domain name>' is not modifiable
1013 The record could not be found
1014 You do not have permission to modify this zone
1015 Unknown error
1017 Content for A record is invalid. Must be a valid IPv4 address
1018 Content for AAAA record is invalid. Must be a valid IPv6 address
1019 Content for CNAME record is invalid
1024 Invalid priority, priority must be set and be between 0 and 65535
1025 Invalid content for an MX record
1026 Invalid format for a SPF record. A valid example is 'v=spf1 a mx -all'. You should not include either the word TXT or the domain name here in the content
1027 Invalid service value
1028 Invalid service value. Must be less than 100 characters
1029 Invalid protocol value
1030 Invalid protocol value. Must be less than 12 characters
1031 Invalid SRV name
1032 Invalid SRV name. Must be less than 90 characters
1033 Invalid weight value. Must be between 0 and 65,535
1034 Invalid port value. Must be between 0 and 65,535
1037 Invalid domain name for a SRV target host
1038 Invalid DNS record type
1039 Invalid TTL. Must be between 120 and 4,294,967,295 seconds, or 1 for automatic
1041 Priority must be set for SRV record
1042 Zone file for '<domain name>' could not be found
1043 Zone file for '<domain name>' is not editable
1044 A record with these exact values already exists. Please modify or remove this record
1045 The record could not be found
1046 A record with these exact values already exists. Please modify or cancel this edit
1047 You do not have permission to modify this zone
1048 You have reached the record limit for this zone
1049 The record content is missing
1050 Could not find record
1052 You can not point a CNAME to itself
1053 Invalid lat_degrees, must be an integer between 0 and 90 inclusive
1054 Invalid lat_minutes, must be an integer between 0 and 59 inclusive
1055 Invalid lat_seconds, must be a floating point number between 0 and 60, including 0 but not including 60
1056 Invalid or missing lat_direction. Values must be N or S
1057 Invalid long_degrees, must be an integer between 0 and 180
1058 Invalid long_minutes, must be an integer between 0 and 59
1059 Invalid long_seconds, must be a floating point number between 0 and 60, including 0 but not including 60
1060 Invalid or missing long_direction. Values must be E or S
1061 Invalid altitude, must be a floating point number between -100000.00 and 42849672.95
1062 Invalid size, must be a floating point number between 0 and 90000000.00
1063 Invalid precision_horz, must be a floating point number between 0 and 90000000.00
1064 Invalid precision_vert, must be a floating point number between 0 and 90000000.00
1065 Invalid or missing data for <type> record
1067 Invalid content for a NS record
1068 Target cannot be an IP address
1069 CNAME content cannot reference itself
1070 CNAME content cannot be an IP
1071 Invalid proxied mode. Record cannot be proxied
1072 Invalid record identifier
1073 Invalid TXT record. Must be less than 255 characters
1074 Invalid TXT record. Record may only contain printable ASCII!

DNS Records for a Zone Notes

If a zone's cname_setup_status is TRUE, you may only add A/AAAA and CNAME records for that zone
When adding a CNAME record, it will not be added if there is an A or AAAA record with the same name
When adding a A or AAAA record, it will not be added if there is an CNAME record with the same name
A CNAME record's name may not match it's content
You cannot add an NS record with the same name as any other record type
You cannot add a record with the same name as any NS record
CloudFlare will not begin serving DNS for a zone until the zone's nameservers are switched to CloudFlare nameservers at the zone's registrar
DNS will continue to be served by CloudFlare for 20 days after a zone's nameservers are switched away from CloudFlare namservers
When using unicode characters in domain names, they will be translated to punycode and as such, the length may end up being larger than what is passed into the API

Railguns for a Zone

Railguns associated with a zone

Object definition

View properties and constraints defined on the object

Show definition

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "name": "My Railgun", "enabled": true, "connected": true }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
name
string

Readable identifier of the railgun

"My Railgun"
  • max length: 160
enabled
boolean

Flag to determine if the Railgun is accepting connections

true
  • valid values: (true,false)
connected
boolean

A flag indicating whether the given zone is connected to the Railgun

true
  • valid values: (true,false)

GET Get available Railguns permission needed: #zone_settings:read

A list of available Railguns the zone can use

GET /zones/:zone_identifier/railguns
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/railguns" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": [ { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "My Railgun", "enabled": true, "connected": true } ], "result_info": { "page": 1, "per_page": 20, "count": 1, "total_count": 2000 } }

GET Get Railgun details permission needed: #zone_settings:read

Details about a specific Railgun

GET /zones/:zone_identifier/railguns/:identifier
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/railguns/9a7806061c88ada191ed06f989cc3dac" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "My Railgun", "enabled": true, "connected": true } }

GET Test Railgun connection permission needed: #zone_settings:read

Test Railgun connection to the Zone

GET /zones/:zone_identifier/railguns/:identifier/diagnose
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/railguns/9a7806061c88ada191ed06f989cc3dac/diagnose" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "method": "GET", "host_name": "www.example.com", "http_status": 200, "railgun": "on", "url": "https://www.cloudflare.com", "response_status": "200 OK", "protocol": "HTTP/1.1", "elapsed_time": "0.239013s", "body_size": "63910 bytes", "body_hash": "be27f2429421e12f200cab1da43ba301bdc70e1d", "missing_headers": "No Content-Length or Transfer-Encoding", "connection_close": false, "cloudflare": "on", "cf-ray": "1ddd7570575207d9-LAX", "cf-wan-error": null, "cf-cache-status": null } }

PATCH Connect or disconnect a Railgun permission needed: #zone_settings:edit

Connect or disconnect a Railgun

PATCH /zones/:zone_identifier/railguns/:identifier

Required parameters

Name /type Description /example Constraints
connected
boolean

A flag indicating whether the given zone is connected to the Railgun

true
  • valid values: (true,false)
cURL (example)
$ curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/railguns/9a7806061c88ada191ed06f989cc3dac" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"connected":true}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "My Railgun", "enabled": true, "connected": true } }

Zone Analytics

Analytics data for a zone

Object definitions

View properties and constraints defined on the object

Show definitions

Dashboard response

Example object
{ "totals": { "since": "2015-01-01T12:23:00Z", "until": "2015-01-02T12:23:00Z", "requests": { "all": 1234085328, "cached": 1234085328, "uncached": 13876154, "content_type": { "css": 15343, "html": 1234213, "javascript": 318236, "gif": 23178, "jpeg": 1982048 }, "country": { "US": 4181364, "AG": 37298, "GI": 293846 }, "ssl": { "encrypted": 12978361, "unencrypted": 781263 }, "http_status": { "200": 13496983, "301": 283, "400": 187936, "402": 1828, "404": 1293 } }, "bandwidth": { "all": 213867451, "cached": 113205063, "uncached": 113205063, "content_type": { "css": 237421, "html": 1231290, "javascript": 123245, "gif": 1234242, "jpeg": 784278 }, "country": { "US": 123145433, "AG": 2342483, "GI": 984753 }, "ssl": { "encrypted": 37592942, "unencrypted": 237654192 } }, "threats": { "all": 23423873, "country": { "US": 123, "CN": 523423, "AU": 91 }, "type": { "user.ban.ip": 123, "hot.ban.unknown": 5324, "macro.chl.captchaErr": 1341, "macro.chl.jschlErr": 5323 } }, "pageviews": { "all": 5724723, "search_engines": { "googlebot": 35272, "pingdom": 13435, "bingbot": 5372, "baidubot": 1345 } }, "uniques": { "all": 12343 } }, "timeseries": [ { "since": "2015-01-01T12:23:00Z", "until": "2015-01-02T12:23:00Z", "requests": { "all": 1234085328, "cached": 1234085328, "uncached": 13876154, "content_type": { "css": 15343, "html": 1234213, "javascript": 318236, "gif": 23178, "jpeg": 1982048 }, "country": { "US": 4181364, "AG": 37298, "GI": 293846 }, "ssl": { "encrypted": 12978361, "unencrypted": 781263 }, "http_status": { "200": 13496983, "301": 283, "400": 187936, "402": 1828, "404": 1293 } }, "bandwidth": { "all": 213867451, "cached": 113205063, "uncached": 113205063, "content_type": { "css": 237421, "html": 1231290, "javascript": 123245, "gif": 1234242, "jpeg": 784278 }, "country": { "US": 123145433, "AG": 2342483, "GI": 984753 }, "ssl": { "encrypted": 37592942, "unencrypted": 237654192 } }, "threats": { "all": 23423873, "country": { "US": 123, "CN": 523423, "AU": 91 }, "type": { "user.ban.ip": 123, "hot.ban.unknown": 5324, "macro.chl.captchaErr": 1341, "macro.chl.jschlErr": 5323 } }, "pageviews": { "all": 5724723, "search_engines": { "googlebot": 35272, "pingdom": 13435, "bingbot": 5372, "baidubot": 1345 } }, "uniques": { "all": 12343 } } ] }
Name /type Description /example Constraints
totals
object

Breakdown of totals by data type

{"since":"2015-01-01T12:23:00Z","until":"2015-01-02T12:23:00Z","requests":{"all":1234085328,"cached":1234085328,"uncached":13876154,"content_type":{"css":15343,"html":1234213,"javascript":318236,"gif":23178,"jpeg":1982048},"country":{"US":4181364,"AG":37298,"GI":293846},"ssl":{"encrypted":12978361,"unencrypted":781263},"http_status":{"200":13496983,"301":283,"400":187936,"402":1828,"404":1293}},"bandwidth":{"all":213867451,"cached":113205063,"uncached":113205063,"content_type":{"css":237421,"html":1231290,"javascript":123245,"gif":1234242,"jpeg":784278},"country":{"US":123145433,"AG":2342483,"GI":984753},"ssl":{"encrypted":37592942,"unencrypted":237654192}},"threats":{"all":23423873,"country":{"US":123,"CN":523423,"AU":91},"type":{"user.ban.ip":123,"hot.ban.unknown":5324,"macro.chl.captchaErr":1341,"macro.chl.jschlErr":5323}},"pageviews":{"all":5724723,"search_engines":{"googlebot":35272,"pingdom":13435,"bingbot":5372,"baidubot":1345}},"uniques":{"all":12343}}
Show definition »
Name /type Description /example Constraints
since
string,integer

The (inclusive) beginning of the requested time frame. This value can be a negative integer representing the number of minutes in the past relative to time the request is made, or can be an absolute timestamp that conforms to RFC 3339. At this point in time, it cannot exceed a time in the past greater than one year.

Ranges that the CloudFlare web application provides will provide the following period length for each point:

  • Last 30 minutes (-20): 1 minute
  • Last 6 hours (-360): 15 minutes
  • Last 12 hours (-720): 30 minutes
  • Last 24 hours (-1440): 1 hour
  • Last week (-10080): 1 day
  • Last month (-43200): 1 day
"2015-01-01T12:23:00Z"
  • default value: -10080
until
string,integer

The (exclusive) end of the requested time frame. This value can be a negative integer representing the number of minutes in the past relative to time the request is made, or can be an absolute timestamp that conforms to RFC 3339. If omitted, the time of the request is used.

"2015-01-02T12:23:00Z"
  • default value: 0
requests
object

Breakdown of totals for requests

{"all":1234085328,"cached":1234085328,"uncached":13876154,"content_type":{"css":15343,"html":1234213,"javascript":318236,"gif":23178,"jpeg":1982048},"country":{"US":4181364,"AG":37298,"GI":293846},"ssl":{"encrypted":12978361,"unencrypted":781263},"http_status":{"200":13496983,"301":283,"400":187936,"402":1828,"404":1293}}
Show definition »
Name /type Description /example Constraints
all
integer

Total number of requests served

1234085328
cached
integer

Total number of cached requests served

1234085328
uncached
integer

Total number of requests served from the origin

13876154
content_type
object

A variable list of key/value pairs where the key represents the type of content served, and the value is the number of requests.

{"css":15343,"html":1234213,"javascript":318236,"gif":23178,"jpeg":1982048}
country
object

A variable list of key/value pairs where the key is a two-digit country code and the value is the number of requests served to that country

{"US":4181364,"AG":37298,"GI":293846}
ssl
object

A break down of requests served over HTTPS

{"encrypted":12978361,"unencrypted":781263}
Show definition »
Name /type Description /example Constraints
encrypted
integer

The number of requests served over HTTPS

12978361
unencrypted
integer

The number of requests served over HTTP

781263
http_status
object

A variable list of key/value pairs where the key is a HTTP status code and the value is the number of requests with that code served

{"200":13496983,"301":283,"400":187936,"402":1828,"404":1293}
bandwidth
object

Breakdown of totals for bandwidth in the form of bytes

{"all":213867451,"cached":113205063,"uncached":113205063,"content_type":{"css":237421,"html":1231290,"javascript":123245,"gif":1234242,"jpeg":784278},"country":{"US":123145433,"AG":2342483,"GI":984753},"ssl":{"encrypted":37592942,"unencrypted":237654192}}
Show definition »
Name /type Description /example Constraints
all
integer

The total number of bytes served within the time frame

213867451
cached
integer

The number of bytes that were cached (and served) by CloudFlare

113205063
uncached
integer

The number of bytes that were fetched and served from the origin server

113205063
content_type
object

A variable list of key/value pairs where the key represents the type of content served, and the value is the number in bytes served.

{"css":237421,"html":1231290,"javascript":123245,"gif":1234242,"jpeg":784278}
country
object

A variable list of key/value pairs where the key is a two-digit country code and the value is the number of bytes served to that country

{"US":123145433,"AG":2342483,"GI":984753}
ssl
object

A break down of bytes served over HTTPS

{"encrypted":37592942,"unencrypted":237654192}
Show definition »
Name /type Description /example Constraints
encrypted
integer

The number of bytes served over HTTPS

37592942
unencrypted
integer

The number of bytes served over HTTP

237654192
threats
object

Breakdown of totals for threats

{"all":23423873,"country":{"US":123,"CN":523423,"AU":91},"type":{"user.ban.ip":123,"hot.ban.unknown":5324,"macro.chl.captchaErr":1341,"macro.chl.jschlErr":5323}}
Show definition »
Name /type Description /example Constraints
all
integer

The total number of identifiable threats received over the time frame

23423873
country
object

A list of key/value pairs where the key is a two-digit country code and the value is the number of malicious requests received from that country.

{"US":123,"CN":523423,"AU":91}
type
object

The list of key/value pairs where the key is a threat category and the value is the number of requests.

{"user.ban.ip":123,"hot.ban.unknown":5324,"macro.chl.captchaErr":1341,"macro.chl.jschlErr":5323}
pageviews
object

Breakdown of totals for pageviews

{"all":5724723,"search_engines":{"googlebot":35272,"pingdom":13435,"bingbot":5372,"baidubot":1345}}
Show definition »
Name /type Description /example Constraints
all
integer

The total number of pageviews served within the time range

5724723
search_engines
object

A variable list of key/value pairs representing the search engine and number of hits

{"googlebot":35272,"pingdom":13435,"bingbot":5372,"baidubot":1345}
uniques
object
{"all":12343}
Show definition »
Name /type Description /example Constraints
all
object

Total number of unique IP addresses within the time range

12343
timeseries
array

Time deltas containing metadata about each bucket of time. The number of buckets (resolution) is determined by the amount of time between the since and until parameters.

[{"since":"2015-01-01T12:23:00Z","until":"2015-01-02T12:23:00Z","requests":{"all":1234085328,"cached":1234085328,"uncached":13876154,"content_type":{"css":15343,"html":1234213,"javascript":318236,"gif":23178,"jpeg":1982048},"country":{"US":4181364,"AG":37298,"GI":293846},"ssl":{"encrypted":12978361,"unencrypted":781263},"http_status":{"200":13496983,"301":283,"400":187936,"402":1828,"404":1293}},"bandwidth":{"all":213867451,"cached":113205063,"uncached":113205063,"content_type":{"css":237421,"html":1231290,"javascript":123245,"gif":1234242,"jpeg":784278},"country":{"US":123145433,"AG":2342483,"GI":984753},"ssl":{"encrypted":37592942,"unencrypted":237654192}},"threats":{"all":23423873,"country":{"US":123,"CN":523423,"AU":91},"type":{"user.ban.ip":123,"hot.ban.unknown":5324,"macro.chl.captchaErr":1341,"macro.chl.jschlErr":5323}},"pageviews":{"all":5724723,"search_engines":{"googlebot":35272,"pingdom":13435,"bingbot":5372,"baidubot":1345}},"uniques":{"all":12343}}]

GET Dashboard permission needed: #analytics:read

The dashboard view provides both totals and timeseries data for the given zone and time period across the entire CloudFlare network.

GET /zones/:zone_identifier/analytics/dashboard

Optional parameters

Name /type Description /example Constraints
since
string,integer

The (inclusive) beginning of the requested time frame. This value can be a negative integer representing the number of minutes in the past relative to time the request is made, or can be an absolute timestamp that conforms to RFC 3339. At this point in time, it cannot exceed a time in the past greater than one year.

Ranges that the CloudFlare web application provides will provide the following period length for each point:

  • Last 30 minutes (-20): 1 minute
  • Last 6 hours (-360): 15 minutes
  • Last 12 hours (-720): 30 minutes
  • Last 24 hours (-1440): 1 hour
  • Last week (-10080): 1 day
  • Last month (-43200): 1 day
"2015-01-01T12:23:00Z"
  • default value: -10080
until
string,integer

The (exclusive) end of the requested time frame. This value can be a negative integer representing the number of minutes in the past relative to time the request is made, or can be an absolute timestamp that conforms to RFC 3339. If omitted, the time of the request is used.

"2015-01-02T12:23:00Z"
  • default value: 0
exclude_series
boolean

Whether or not to return timeseries data with the result. If specifying false, only totals will be returned

false
  • valid values: (true,false)
continuous
boolean

When set to true, the range returned by the response acts like a sliding window to provide a contiguous time-window. Analytics data is processed and aggregated asynchronously and can sometimes lead to recent data points being incomplete if this value is set to false. If a start date provided is earlier than a date for which data is available, the API will return 0's for those dates until the first available date with data

true
  • default value: true
  • valid values: (true,false)
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/analytics/dashboard?since=2015-01-01T12:23:00Z&until=2015-01-02T12:23:00Z&exclude_series=false&continuous=true" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "totals": { "since": "2015-01-01T12:23:00Z", "until": "2015-01-02T12:23:00Z", "requests": { "all": 1234085328, "cached": 1234085328, "uncached": 13876154, "content_type": { "css": 15343, "html": 1234213, "javascript": 318236, "gif": 23178, "jpeg": 1982048 }, "country": { "US": 4181364, "AG": 37298, "GI": 293846 }, "ssl": { "encrypted": 12978361, "unencrypted": 781263 }, "http_status": { "200": 13496983, "301": 283, "400": 187936, "402": 1828, "404": 1293 } }, "bandwidth": { "all": 213867451, "cached": 113205063, "uncached": 113205063, "content_type": { "css": 237421, "html": 1231290, "javascript": 123245, "gif": 1234242, "jpeg": 784278 }, "country": { "US": 123145433, "AG": 2342483, "GI": 984753 }, "ssl": { "encrypted": 37592942, "unencrypted": 237654192 } }, "threats": { "all": 23423873, "country": { "US": 123, "CN": 523423, "AU": 91 }, "type": { "user.ban.ip": 123, "hot.ban.unknown": 5324, "macro.chl.captchaErr": 1341, "macro.chl.jschlErr": 5323 } }, "pageviews": { "all": 5724723, "search_engines": { "googlebot": 35272, "pingdom": 13435, "bingbot": 5372, "baidubot": 1345 } }, "uniques": { "all": 12343 } }, "timeseries": [ { "since": "2015-01-01T12:23:00Z", "until": "2015-01-02T12:23:00Z", "requests": { "all": 1234085328, "cached": 1234085328, "uncached": 13876154, "content_type": { "css": 15343, "html": 1234213, "javascript": 318236, "gif": 23178, "jpeg": 1982048 }, "country": { "US": 4181364, "AG": 37298, "GI": 293846 }, "ssl": { "encrypted": 12978361, "unencrypted": 781263 }, "http_status": { "200": 13496983, "301": 283, "400": 187936, "402": 1828, "404": 1293 } }, "bandwidth": { "all": 213867451, "cached": 113205063, "uncached": 113205063, "content_type": { "css": 237421, "html": 1231290, "javascript": 123245, "gif": 1234242, "jpeg": 784278 }, "country": { "US": 123145433, "AG": 2342483, "GI": 984753 }, "ssl": { "encrypted": 37592942, "unencrypted": 237654192 } }, "threats": { "all": 23423873, "country": { "US": 123, "CN": 523423, "AU": 91 }, "type": { "user.ban.ip": 123, "hot.ban.unknown": 5324, "macro.chl.captchaErr": 1341, "macro.chl.jschlErr": 5323 } }, "pageviews": { "all": 5724723, "search_engines": { "googlebot": 35272, "pingdom": 13435, "bingbot": 5372, "baidubot": 1345 } }, "uniques": { "all": 12343 } } ] }, "query": { "since": "2015-01-01T12:23:00Z", "until": "2015-01-02T12:23:00Z", "time_delta": 60 } }

GET Analytics by Co-locations permission needed: #analytics:read

This view provides a breakdown of analytics data by datacenter. Note: This is available to Enterprise customers only.

GET /zones/:zone_identifier/analytics/colos

Optional parameters

Name /type Description /example Constraints
since
string,integer

The (inclusive) beginning of the requested time frame. This value can be a negative integer representing the number of minutes in the past relative to time the request is made, or can be an absolute timestamp that conforms to RFC 3339. At this point in time, it cannot exceed a time in the past greater than one year.

Ranges that the CloudFlare web application provides will provide the following period length for each point:

  • Last 30 minutes (-20): 1 minute
  • Last 6 hours (-360): 15 minutes
  • Last 12 hours (-720): 30 minutes
  • Last 24 hours (-1440): 1 hour
  • Last week (-10080): 1 day
  • Last month (-43200): 1 day
"2015-01-01T12:23:00Z"
  • default value: -10080
until
string,integer

The (exclusive) end of the requested time frame. This value can be a negative integer representing the number of minutes in the past relative to time the request is made, or can be an absolute timestamp that conforms to RFC 3339. If omitted, the time of the request is used.

"2015-01-02T12:23:00Z"
  • default value: 0
exclude_series
boolean

Whether or not to return timeseries data with the result. If specifying false, only totals will be returned

false
  • valid values: (true,false)
continuous
boolean

When set to true, the range returned by the response acts like a sliding window to provide a contiguous time-window. Analytics data is processed and aggregated asynchronously and can sometimes lead to recent data points being incomplete if this value is set to false. If a start date provided is earlier than a date for which data is available, the API will return 0's for those dates until the first available date with data

true
  • default value: true
  • valid values: (true,false)
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/analytics/colos?since=2015-01-01T12:23:00Z&until=2015-01-02T12:23:00Z&exclude_series=false&continuous=true" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": [ { "colo_id": "SFO", "timeseries": [ { "since": "2015-01-01T12:23:00Z", "until": "2015-01-02T12:23:00Z", "requests": { "all": 1234085328, "cached": 1234085328, "uncached": 13876154, "content_type": { "css": 15343, "html": 1234213, "javascript": 318236, "gif": 23178, "jpeg": 1982048 }, "country": { "US": 4181364, "AG": 37298, "GI": 293846 }, "ssl": { "encrypted": 12978361, "unencrypted": 781263 }, "http_status": { "200": 13496983, "301": 283, "400": 187936, "402": 1828, "404": 1293 } }, "bandwidth": { "all": 213867451, "cached": 113205063, "uncached": 113205063, "content_type": { "css": 237421, "html": 1231290, "javascript": 123245, "gif": 1234242, "jpeg": 784278 }, "country": { "US": 123145433, "AG": 2342483, "GI": 984753 }, "ssl": { "encrypted": 37592942, "unencrypted": 237654192 } }, "threats": { "all": 23423873, "country": { "US": 123, "CN": 523423, "AU": 91 }, "type": { "user.ban.ip": 123, "hot.ban.unknown": 5324, "macro.chl.captchaErr": 1341, "macro.chl.jschlErr": 5323 } }, "pageviews": { "all": 5724723, "search_engines": { "googlebot": 35272, "pingdom": 13435, "bingbot": 5372, "baidubot": 1345 } }, "uniques": { "all": 12343 } } ] } ], "query": { "since": "2015-01-01T12:23:00Z", "until": "2015-01-02T12:23:00Z", "time_delta": 60 } }

Railgun

CloudFlare Railgun

Object definition

View properties and constraints defined on the object

Show definition

Example object
{ "id": "9a7806061c88ada191ed06f989cc3dac", "name": "My Railgun", "status": "active", "enabled": true, "zones_connected": 2, "build": "b1234", "version": "2.1", "revision": "123", "activation_key": "e4edc00281cb56ebac22c81be9bac8f3", "activated_on": "2014-01-02T02:20:00Z", "created_on": "2014-01-01T05:20:00Z", "modified_on": "2014-01-01T05:20:00Z" }
Name /type Description /example Constraints
id
string

API item identifier tag

"9a7806061c88ada191ed06f989cc3dac"
  • max length: 32
  • read only
name
string

Readable identifier of the railgun

"My Railgun"
  • max length: 160
status
string

Status of the railgun

"active"
  • valid values: (initializing, active)
  • read only
enabled
boolean

Flag to determine if the Railgun is accepting connections

true
  • valid values: (true,false)
zones_connected
number

The number of zones using this railgun

2
  • read only
build
string

The build identifier for the railgun receiver

"b1234"
  • read only
version
string

The version of the railgun receiver

"2.1"
  • read only
revision
string

The revision of the railgun receiver

"123"
  • read only
activation_key
string
"e4edc00281cb56ebac22c81be9bac8f3"
  • max length: 32
  • read only
activated_on
string

When the Railgun was activated

"2014-01-02T02:20:00Z"
  • read only
created_on
string

When the Railgun was created

"2014-01-01T05:20:00Z"
  • read only
modified_on
string

When the Railgun was last modified

"2014-01-01T05:20:00Z"
  • read only
upgrade_info
object

Defined when the Railgun version is out of date from the latest release from CloudFlare

{"latest_version":"1.0.0","download_link":"https://www.cloudflare.com/downloads/railgun"}
Show definition »
Name /type Description /example Constraints
latest_version
string

Latest version of the Railgun receiver available to install

"1.0.0"
download_link
string

An HTTP link to download the latest binary

"https://www.cloudflare.com/downloads/railgun"

POST Create Railgun

POST /railguns

Required parameters

Name /type Description /example Constraints
name
string

Readable identifier of the railgun

"My Railgun"
  • max length: 160
cURL (example)
$ curl -X POST "https://api.cloudflare.com/client/v4/railguns" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json" \ --data '{"name":"My Railgun"}'
Response (example)
{ "success": true, "errors": [], "messages": [], "result": { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "My Railgun", "status": "active", "enabled": true, "zones_connected": 2, "build": "b1234", "version": "2.1", "revision": "123", "activation_key": "e4edc00281cb56ebac22c81be9bac8f3", "activated_on": "2014-01-02T02:20:00Z", "created_on": "2014-01-01T05:20:00Z", "modified_on": "2014-01-01T05:20:00Z" } }

GET List Railguns

List, search, sort and filter your Railguns

GET /railguns

Optional parameters

Name /type Description /example Constraints
page
number

Page number of paginated results

1
  • default value: 1
  • min value: 1
per_page
number

Number of items per page

20
  • default value: 20
  • min value: 5
  • max value: 50
direction
string

Direction to order Railguns

"desc"
  • valid values: (asc, desc)
cURL (example)
$ curl -X GET "https://api.cloudflare.com/client/v4/railguns?page=1&per_page=20&direction=desc" \ -H "X-Auth-Email: user@example.com" \ -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \ -H "Content-Type: application/json"
Response (example)
{ "success": true, "errors": [], "messages": [], "result": [ { "id": "9a7806061c88ada191ed06f989cc3dac", "name": "My Railgun", "status": "active", "enabled": true, "zones_connected": 2, "build": "b1234", "version": "2.1", "revision": "123", "activation_key": "e4edc00281cb56ebac22c81be9bac8f3", "activated_on": "2014-01-02T02:20:00Z", "created_on": "2014-01-01T05:20:00Z", "modified_on": "2014-01-01T05:20:00Z" } ], "result_info": { "page": 1, "per_page": 20, "count":