Cloudflare API documentation v4

Last modified: May 14th, 2019

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.

Cloudflare customers
Cloudflare partners
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.

getting-started-endpoints

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 base URL for all Version 4 HTTPS endpoints is:

https://api.cloudflare.com/client/v4/

getting-started-requests

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. Requests that use X-Auth-User-Service-Key can use that instead of the Auth-Key and Auth-Email headers.

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
User Service Key	X-Auth-User-Service-Key	A special Cloudflare API key good for a restricted set of endpoints. Always begins with "v1.0-", may vary in length.

Example request

Requests are generally formatted as follows:

GET object/:object_id

Auth-Email 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]"

User-Service cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/cd7d0123e3012345da9420df9514dad0" \
     -H "Content-Type:application/json" \
     -H "X-Auth-User-Service-Key:v1.0-e24fd090c02efcfecb4de8f4ff246fd5c75b48946fdf0ce26c59f91d0d90797b-cfa33fe60e8e34073c149323454383fc9005d25c9b4c502c2f063457ef65322eade065975001a0b4b4c591c5e1bd36a6e8f7e2d4fa8a9ec01c64c041e99530c2-07b9efe0acd78c82c8d9c690aacb8656d81c369246d7f996a205fe3c18e9254a"`

Rate limiting

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

Cache-Tag purging has a lower rate limit of up to 2,000 purge API calls in every 24 hour period. You may purge up to 30 tags in one API call.

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

getting-started-responses

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": null,
  "success": false,
  "errors": [{"code":1003,"message":"Invalid or missing zone id."}],
  "messages": []
}

HTTP Content-Type

The response format can be determined from the HTTP Content-Type header. Most API responses are JSON (Content-Type: application/json).

Content-Type	Description
application/json	response is a JSON object
text/plain	response is a textual item
application/x-yaml	response is a YAML object
application/octet-stream	response is a raw data (reserved for later use)

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

getting-started-resource-ids

How to get a Zone ID, User ID, or Organization ID

Nearly every resource in the v4 API (Users, Zones, Settings, Organizations, etc.) may be uniquely identified by a 32-byte string of hex characters ([a-f0-9]). These identifiers may be referred to in the documentation as zone_identifier, user_id, or even just id. Identifier values are usually captured during resource creation (POST requests) or when fetching entire collections (GET requests) of resources. Typically they appear as an id field in the JSON resource.

{
  "result": {
    "id":"2d4d028de3015345da9420df5514dad0",
    "type":"example"
  }
}

You can always find the IDs for API resources by making a GET request to its corresponding collection endpoint. For example, to list all Zone objects, a GET request may be sent to https://api.cloudflare.com/client/v4/zones. All objects listed in the result array will contain an id field; this is also known as zone_identifier.

How to Get a Zone ID

curl -X GET "https://api.cloudflare.com/client/v4/zones" \
    -H "X-Auth-Email: [email protected]" \
    -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
    -H "Content-Type: application/json"

User

The currently logged in/authenticated User

user

Object definition

View properties and constraints defined on the object

Show definition

user-user-details

GET User Details
free
pro
business
enterprise

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": "7c5dae5552338874e5053f2534d2767a",
    "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",
    "two_factor_authentication_enabled": false,
    "suspended": false
  }
}

user-edit-user

PATCH Edit User
free
pro
business
enterprise

Edit part of your user details

PATCH user

Optional parameters

Name /type	Description /example	Constraints
first_name stringnull	User's first name `"John"`	max length: 60
last_name stringnull	User's last name `"Appleseed"`	max length: 60
telephone stringnull	User's telephone number `"+1 123-123-1234"`	max length: 20
country stringnull	The country in which the user lives. `"US"`	max length: 30
zipcode stringnull	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": "7c5dae5552338874e5053f2534d2767a",
    "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",
    "two_factor_authentication_enabled": false,
    "suspended": false
  }
}

User's Account Memberships

A list of memberships of accounts this user can access

user-s-account-memberships

Object definition

View properties and constraints defined on the object

Show definition

user-s-account-memberships-list-memberships

GET List Memberships

List memberships of accounts the user can access

GET memberships

Optional parameters

Name /type	Description /example	Constraints
status string	Status of this membership `"accepted"`	valid values: accepted, pending, rejected
account.name string	Account name `"Demo Account"`	max length: 100
page number	Page number of paginated results `1`	default value: 1 min value:1
per_page number	Number of memberships per page `20`	default value: 20 min value:5 max value:50
order string	Field to order memberships by `"status"`	valid values: id, account.name, status
direction string	Direction to order memberships `"desc"`	valid values: asc, desc

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/memberships?status=accepted&account.name=Demo Account&page=1&per_page=20&order=status&direction=desc" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "4536bcfad5faccb111b47003c79917fa",
      "code": "05dd05cce12bbed97c0d87cd78e89bc2fd41a6cee72f27f6fc84af2e45c0fac0",
      "status": "accepted",
      "account": {
        "id": "01a7362d577a6c3019a474fd6f485823",
        "name": "Demo Account",
        "settings": {
          "enforce_twofactor": false
        }
      },
      "roles": [
        "Account Administrator"
      ],
      "permissions": {
        "analytics": {
          "read": true,
          "write": true
        },
        "billing": {
          "read": true,
          "write": true
        },
        "cache_purge": {
          "read": true,
          "write": true
        },
        "dns": {
          "read": true,
          "write": true
        },
        "dns_records": {
          "read": true,
          "write": true
        },
        "lb": {
          "read": true,
          "write": true
        },
        "logs": {
          "read": true,
          "write": true
        },
        "organization": {
          "read": true,
          "write": true
        },
        "ssl": {
          "read": true,
          "write": true
        },
        "waf": {
          "read": true,
          "write": true
        },
        "zones": {
          "read": true,
          "write": true
        },
        "zone_settings": {
          "read": true,
          "write": true
        }
      }
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

user-s-account-memberships-membership-details

GET Membership Details

Get a specific membership

GET memberships/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/memberships/4536bcfad5faccb111b47003c79917fa" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "4536bcfad5faccb111b47003c79917fa",
    "code": "05dd05cce12bbed97c0d87cd78e89bc2fd41a6cee72f27f6fc84af2e45c0fac0",
    "status": "accepted",
    "account": {
      "id": "01a7362d577a6c3019a474fd6f485823",
      "name": "Demo Account",
      "settings": {
        "enforce_twofactor": false
      }
    },
    "roles": [
      "Account Administrator"
    ],
    "permissions": {
      "analytics": {
        "read": true,
        "write": true
      },
      "billing": {
        "read": true,
        "write": true
      },
      "cache_purge": {
        "read": true,
        "write": true
      },
      "dns": {
        "read": true,
        "write": true
      },
      "dns_records": {
        "read": true,
        "write": true
      },
      "lb": {
        "read": true,
        "write": true
      },
      "logs": {
        "read": true,
        "write": true
      },
      "organization": {
        "read": true,
        "write": true
      },
      "ssl": {
        "read": true,
        "write": true
      },
      "waf": {
        "read": true,
        "write": true
      },
      "zones": {
        "read": true,
        "write": true
      },
      "zone_settings": {
        "read": true,
        "write": true
      }
    }
  }
}

user-s-account-memberships-update-membership

PUT Update Membership

Accept or reject this account invitation

PUT memberships/:identifier

Required parameters

Name /type	Description /example	Constraints
status string	Whether to accept or reject this account invitation `"accepted"`	valid values: accepted, rejected

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/memberships/4536bcfad5faccb111b47003c79917fa" \
     -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": "4536bcfad5faccb111b47003c79917fa",
    "code": "05dd05cce12bbed97c0d87cd78e89bc2fd41a6cee72f27f6fc84af2e45c0fac0",
    "status": "accepted",
    "account": {
      "id": "01a7362d577a6c3019a474fd6f485823",
      "name": "Demo Account",
      "settings": {
        "enforce_twofactor": false
      }
    },
    "roles": [
      "Account Administrator"
    ],
    "permissions": {
      "analytics": {
        "read": true,
        "write": true
      },
      "billing": {
        "read": true,
        "write": true
      },
      "cache_purge": {
        "read": true,
        "write": true
      },
      "dns": {
        "read": true,
        "write": true
      },
      "dns_records": {
        "read": true,
        "write": true
      },
      "lb": {
        "read": true,
        "write": true
      },
      "logs": {
        "read": true,
        "write": true
      },
      "organization": {
        "read": true,
        "write": true
      },
      "ssl": {
        "read": true,
        "write": true
      },
      "waf": {
        "read": true,
        "write": true
      },
      "zones": {
        "read": true,
        "write": true
      },
      "zone_settings": {
        "read": true,
        "write": true
      }
    }
  }
}

user-s-account-memberships-delete-membership

DELETE Delete Membership

Remove the associated member from an account

DELETE memberships/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/memberships/4536bcfad5faccb111b47003c79917fa" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "4536bcfad5faccb111b47003c79917fa"
  }
}

User's Account Memberships error codes

Code	Description
1000	An unknown error(<CODE>) has occurred
1001	Invalid request
1002	Forbidden
1003	Membership not found

Accounts

An Account is the root object which owns other resources such as zones, load balancers and billing details.

accounts

Object definition

View properties and constraints defined on the object

Show definition

accounts-list-accounts

GET List Accounts permission needed: #organization:read
free
pro
business
enterprise

List all accounts you have ownership or verified access to

GET accounts

Optional parameters

Name /type	Description /example	Constraints
page number	Page number of paginated results `1`	default value: 1 min value:1
per_page number	Maximum number of results per page `20`	default value: 20 min value:5 max value:50
direction string	Direction to order results `"desc"`	valid values: asc, desc

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts?page=1&per_page=20&direction=desc" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "01a7362d577a6c3019a474fd6f485823",
      "name": "Demo Account",
      "settings": {
        "enforce_twofactor": false
      }
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

accounts-account-details

GET Account Details permission needed: #organization:read
free
pro
business
enterprise

Get information about a specific account that you are a member of

GET accounts/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "01a7362d577a6c3019a474fd6f485823",
    "name": "Demo Account",
    "settings": {
      "enforce_twofactor": false
    }
  }
}

accounts-update-account

PUT Update Account permission needed: #organization:edit
free
pro
business
enterprise

Update an existing Account

PUT accounts/:identifier

Optional parameters

Name /type	Description /example	Constraints
id string	Account identifier tag `"01a7362d577a6c3019a474fd6f485823"`	max length: 32 read only
name string	Account name `"Demo Account"`	max length: 100
settings object	Account settings `{ "enforce_twofactor": false }` An object with the following properties: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"01a7362d577a6c3019a474fd6f485823","name":"Demo Account","settings":{"enforce_twofactor":false}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "01a7362d577a6c3019a474fd6f485823",
    "name": "Demo Account",
    "settings": {
      "enforce_twofactor": false
    }
  }
}

Accounts error codes

Code	Description
1000	An unknown error(<CODE>) has occurred
1001	Invalid request
1002	Forbidden
1003	Account not found

Account Members

An association between a Cloudflare user and an account

account-members

Object definition

View properties and constraints defined on the object

Show definition

account-members-list-members

GET List Members permission needed: #organization:read
free
pro
business
enterprise

List all members of an account

GET accounts/:account_identifier/members

Optional parameters

Name /type	Description /example	Constraints
page number	Page number of paginated results `1`	default value: 1 min value:1
per_page number	Maximum number of results per page `20`	default value: 20 min value:5 max value:50
direction string	Direction to order results `"desc"`	valid values: asc, desc

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/members?page=1&per_page=20&direction=desc" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "4536bcfad5faccb111b47003c79917fa",
      "code": "05dd05cce12bbed97c0d87cd78e89bc2fd41a6cee72f27f6fc84af2e45c0fac0",
      "user": {
        "id": "7c5dae5552338874e5053f2534d2767a",
        "first_name": "John",
        "last_name": "Appleseed",
        "email": "[email protected]",
        "two_factor_authentication_enabled": false
      },
      "status": "accepted",
      "roles": [
        {
          "id": "3536bcfad5faccb999b47003c79917fb",
          "name": "Account Administrator",
          "description": "Administrative access to the entire Account",
          "permissions": {
            "analytics": {
              "read": true,
              "write": true
            },
            "billing": {
              "read": true,
              "write": true
            },
            "cache_purge": {
              "read": true,
              "write": true
            },
            "dns": {
              "read": true,
              "write": true
            },
            "dns_records": {
              "read": true,
              "write": true
            },
            "lb": {
              "read": true,
              "write": true
            },
            "logs": {
              "read": true,
              "write": true
            },
            "organization": {
              "read": true,
              "write": true
            },
            "ssl": {
              "read": true,
              "write": true
            },
            "waf": {
              "read": true,
              "write": true
            },
            "zones": {
              "read": true,
              "write": true
            },
            "zone_settings": {
              "read": true,
              "write": true
            }
          }
        }
      ]
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

account-members-add-member

POST Add Member permission needed: #organization:edit
free
pro
business
enterprise

Add a user to the list of members for this account

POST accounts/:account_identifier/members

Required parameters

Name /type	Description /example	Constraints
email string	Your contact email address `"[email protected]"`	max length: 90
roles array	Array of roles associated with this member `[ "3536bcfad5faccb999b47003c79917fb" ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
status string	A member's status in the account `"accepted"`	default value: pending valid values: accepted, pending

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/members" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"email":"[email protected]","status":"accepted","roles":["3536bcfad5faccb999b47003c79917fb"]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "4536bcfad5faccb111b47003c79917fa",
    "code": "05dd05cce12bbed97c0d87cd78e89bc2fd41a6cee72f27f6fc84af2e45c0fac0",
    "user": {
      "id": "7c5dae5552338874e5053f2534d2767a",
      "first_name": "John",
      "last_name": "Appleseed",
      "email": "[email protected]",
      "two_factor_authentication_enabled": false
    },
    "status": "accepted",
    "roles": [
      {
        "id": "3536bcfad5faccb999b47003c79917fb",
        "name": "Account Administrator",
        "description": "Administrative access to the entire Account",
        "permissions": {
          "analytics": {
            "read": true,
            "write": true
          },
          "billing": {
            "read": true,
            "write": true
          },
          "cache_purge": {
            "read": true,
            "write": true
          },
          "dns": {
            "read": true,
            "write": true
          },
          "dns_records": {
            "read": true,
            "write": true
          },
          "lb": {
            "read": true,
            "write": true
          },
          "logs": {
            "read": true,
            "write": true
          },
          "organization": {
            "read": true,
            "write": true
          },
          "ssl": {
            "read": true,
            "write": true
          },
          "waf": {
            "read": true,
            "write": true
          },
          "zones": {
            "read": true,
            "write": true
          },
          "zone_settings": {
            "read": true,
            "write": true
          }
        }
      }
    ]
  }
}

account-members-member-details

GET Member Details permission needed: #organization:read
free
pro
business
enterprise

Get information about a specific member of an account

GET accounts/:account_identifier/members/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/members/4536bcfad5faccb111b47003c79917fa" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "4536bcfad5faccb111b47003c79917fa",
    "code": "05dd05cce12bbed97c0d87cd78e89bc2fd41a6cee72f27f6fc84af2e45c0fac0",
    "user": {
      "id": "7c5dae5552338874e5053f2534d2767a",
      "first_name": "John",
      "last_name": "Appleseed",
      "email": "[email protected]",
      "two_factor_authentication_enabled": false
    },
    "status": "accepted",
    "roles": [
      {
        "id": "3536bcfad5faccb999b47003c79917fb",
        "name": "Account Administrator",
        "description": "Administrative access to the entire Account",
        "permissions": {
          "analytics": {
            "read": true,
            "write": true
          },
          "billing": {
            "read": true,
            "write": true
          },
          "cache_purge": {
            "read": true,
            "write": true
          },
          "dns": {
            "read": true,
            "write": true
          },
          "dns_records": {
            "read": true,
            "write": true
          },
          "lb": {
            "read": true,
            "write": true
          },
          "logs": {
            "read": true,
            "write": true
          },
          "organization": {
            "read": true,
            "write": true
          },
          "ssl": {
            "read": true,
            "write": true
          },
          "waf": {
            "read": true,
            "write": true
          },
          "zones": {
            "read": true,
            "write": true
          },
          "zone_settings": {
            "read": true,
            "write": true
          }
        }
      }
    ]
  }
}

account-members-update-member

PUT Update Member permission needed: #organization:edit
free
pro
business
enterprise

Modify an account member

PUT accounts/:account_identifier/members/:identifier

Optional parameters

Name /type	Description /example	Constraints
id string	Membership identifier tag `"4536bcfad5faccb111b47003c79917fa"`	max length: 32 read only
code string	The unique activation code for the account membership `"05dd05cce12bbed97c0d87cd78e89bc2fd41a6cee72f27f6fc84af2e45c0fac0"`	max length: 64 read only
user object	`{ "id": "7c5dae5552338874e5053f2534d2767a", "first_name": "John", "last_name": "Appleseed", "email": "[email protected]", "two_factor_authentication_enabled": false }` An object with the following properties: Show definition »	read only
status string	A member's status in the account `"accepted"`	valid values: accepted, pending, rejected read only
roles array	Roles assigned to this member [ { "id": "3536bcfad5faccb999b47003c79917fb", "name": "Account Administrator", "description": "Administrative access to the entire Account", "permissions": { "analytics": { "read": true, "write": true }, "billing": { "read": true, "write": true }, "cache_purge": { "read": true, "write": true }, "dns": { "read": true, "write": true }, "dns_records": { "read": true, "write": true }, "lb": { "read": true, "write": true }, "logs": { "read": true, "write": true }, "organization": { "read": true, "write": true }, "ssl": { "read": true, "write": true }, "waf": { "read": true, "write": true }, "zones": { "read": true, "write": true }, "zone_settings": { "read": true, "write": true } } } ] An array with items in the following form: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/members/4536bcfad5faccb111b47003c79917fa" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"4536bcfad5faccb111b47003c79917fa","code":"05dd05cce12bbed97c0d87cd78e89bc2fd41a6cee72f27f6fc84af2e45c0fac0","user":{"id":"7c5dae5552338874e5053f2534d2767a","first_name":"John","last_name":"Appleseed","email":"[email protected]","two_factor_authentication_enabled":false},"status":"accepted","roles":[{"id":"3536bcfad5faccb999b47003c79917fb","name":"Account Administrator","description":"Administrative access to the entire Account","permissions":{"analytics":{"read":true,"write":true},"billing":{"read":true,"write":true},"cache_purge":{"read":true,"write":true},"dns":{"read":true,"write":true},"dns_records":{"read":true,"write":true},"lb":{"read":true,"write":true},"logs":{"read":true,"write":true},"organization":{"read":true,"write":true},"ssl":{"read":true,"write":true},"waf":{"read":true,"write":true},"zones":{"read":true,"write":true},"zone_settings":{"read":true,"write":true}}}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "4536bcfad5faccb111b47003c79917fa",
    "code": "05dd05cce12bbed97c0d87cd78e89bc2fd41a6cee72f27f6fc84af2e45c0fac0",
    "user": {
      "id": "7c5dae5552338874e5053f2534d2767a",
      "first_name": "John",
      "last_name": "Appleseed",
      "email": "[email protected]",
      "two_factor_authentication_enabled": false
    },
    "status": "accepted",
    "roles": [
      {
        "id": "3536bcfad5faccb999b47003c79917fb",
        "name": "Account Administrator",
        "description": "Administrative access to the entire Account",
        "permissions": {
          "analytics": {
            "read": true,
            "write": true
          },
          "billing": {
            "read": true,
            "write": true
          },
          "cache_purge": {
            "read": true,
            "write": true
          },
          "dns": {
            "read": true,
            "write": true
          },
          "dns_records": {
            "read": true,
            "write": true
          },
          "lb": {
            "read": true,
            "write": true
          },
          "logs": {
            "read": true,
            "write": true
          },
          "organization": {
            "read": true,
            "write": true
          },
          "ssl": {
            "read": true,
            "write": true
          },
          "waf": {
            "read": true,
            "write": true
          },
          "zones": {
            "read": true,
            "write": true
          },
          "zone_settings": {
            "read": true,
            "write": true
          }
        }
      }
    ]
  }
}

account-members-remove-member

DELETE Remove Member permission needed: #organization:edit
free
pro
business
enterprise

Remove a member from an account

DELETE accounts/:account_identifier/members/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/members/4536bcfad5faccb111b47003c79917fa" \
     -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"
  }
}

Account Roles

A Role defines what permissions a Member of an Account has.

account-roles

Object definition

View properties and constraints defined on the object

Show definition

account-roles-list-roles

GET List Roles permission needed: #organization:read

Get all available roles for an account

GET accounts/:account_identifier/roles

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/roles" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "3536bcfad5faccb999b47003c79917fb",
      "name": "Account Administrator",
      "description": "Administrative access to the entire Account",
      "permissions": {
        "analytics": {
          "read": true,
          "write": true
        },
        "billing": {
          "read": true,
          "write": true
        },
        "cache_purge": {
          "read": true,
          "write": true
        },
        "dns": {
          "read": true,
          "write": true
        },
        "dns_records": {
          "read": true,
          "write": true
        },
        "lb": {
          "read": true,
          "write": true
        },
        "logs": {
          "read": true,
          "write": true
        },
        "organization": {
          "read": true,
          "write": true
        },
        "ssl": {
          "read": true,
          "write": true
        },
        "waf": {
          "read": true,
          "write": true
        },
        "zones": {
          "read": true,
          "write": true
        },
        "zone_settings": {
          "read": true,
          "write": true
        }
      }
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

account-roles-role-details

GET Role Details permission needed: #organization:read

Get information about a specific role for an account

GET accounts/:account_identifier/roles/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/roles/3536bcfad5faccb999b47003c79917fb" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "3536bcfad5faccb999b47003c79917fb",
    "name": "Account Administrator",
    "description": "Administrative access to the entire Account",
    "permissions": {
      "analytics": {
        "read": true,
        "write": true
      },
      "billing": {
        "read": true,
        "write": true
      },
      "cache_purge": {
        "read": true,
        "write": true
      },
      "dns": {
        "read": true,
        "write": true
      },
      "dns_records": {
        "read": true,
        "write": true
      },
      "lb": {
        "read": true,
        "write": true
      },
      "logs": {
        "read": true,
        "write": true
      },
      "organization": {
        "read": true,
        "write": true
      },
      "ssl": {
        "read": true,
        "write": true
      },
      "waf": {
        "read": true,
        "write": true
      },
      "zones": {
        "read": true,
        "write": true
      },
      "zone_settings": {
        "read": true,
        "write": true
      }
    }
  }
}

Account Subscriptions

Listing of an account's subscriptions

account-subscriptions

Object definition

View properties and constraints defined on the object

Show definition

account-subscriptions-list-subscriptions

GET List Subscriptions permission needed: #billing:read
free
pro
business
enterprise

Lists all an account's subscriptions

GET accounts/:account_identifier/subscriptions

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/subscriptions" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "app": {
        "install_id": null
      },
      "id": "506e3185e9c882d175a2d0cb0093d9f2",
      "state": "Paid",
      "price": 20,
      "currency": "USD",
      "component_values": [
        {
          "name": "page_rules",
          "value": 20,
          "default": 5,
          "price": 5
        }
      ],
      "zone": {
        "id": "023e105f4ecef8ad9ca31a8372d0c353",
        "name": "example.com"
      },
      "frequency": "monthly",
      "rate_plan": {
        "id": "free",
        "public_name": "Business Plan",
        "currency": "USD",
        "scope": "zone",
        "sets": [
          {}
        ],
        "is_contract": false,
        "externally_managed": false
      },
      "current_period_end": "2014-03-31T12:20:00Z",
      "current_period_start": "2014-05-11T12:20:00Z"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

account-subscriptions-create-subscription

POST Create Subscription permission needed: #billing:read#billing:edit
free
pro
business
enterprise

Create an account subscription.

POST accounts/:account_identifier/subscriptions

Optional parameters

Name /type	Description /example	Constraints
app	`{ "install_id": null }` An object with the following properties: Show definition »
current_period_end string (date-time)	The end of the current period, and also when the next billing is due `"2014-03-31T12:20:00Z"`	read only
component_values array	The list of add-ons subscribed to `[ { "name": "page_rules", "value": 20, "default": 5, "price": 5 } ]` An array with items in the following form: Show definition »
rate_plan object	The rate plan applied to the subscription `{ "id": "free", "public_name": "Business Plan", "currency": "USD", "scope": "zone", "sets": [ {} ], "is_contract": false, "externally_managed": false }` An object with the following properties: Show definition »
price number	The price of the subscription that will be billed, in US dollars `20`	read only
current_period_start string (date-time)	When the current billing period started, may be the same as InitialPeriodStart if this is the first period `"2014-05-11T12:20:00Z"`	read only
zone object	A simple zone object. May have null properties if not a zone subscription. `{ "id": "023e105f4ecef8ad9ca31a8372d0c353", "name": "example.com" }` An object with the following properties: Show definition »
currency string	The monetary unit in which pricing information is displayed `"USD"`	read only
state string	The state that the subscription is in `"Paid"`	valid values: Trial, Provisioned, Paid, AwaitingPayment, Cancelled, Failed, Expired read only
id string	Subscription identifier tag `"506e3185e9c882d175a2d0cb0093d9f2"`	max length: 32 read only
frequency string	How often the subscription is renewed automatically `"monthly"`	valid values: weekly, monthly, quarterly, yearly

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/subscriptions" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"app":{"install_id":null},"id":"506e3185e9c882d175a2d0cb0093d9f2","state":"Paid","price":20,"currency":"USD","component_values":[{"name":"page_rules","value":20,"default":5,"price":5}],"zone":{"id":"023e105f4ecef8ad9ca31a8372d0c353","name":"example.com"},"frequency":"monthly","rate_plan":{"id":"free","public_name":"Business Plan","currency":"USD","scope":"zone","sets":[{}],"is_contract":false,"externally_managed":false},"current_period_end":"2014-03-31T12:20:00Z","current_period_start":"2014-05-11T12:20:00Z"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "app": {
      "install_id": null
    },
    "id": "506e3185e9c882d175a2d0cb0093d9f2",
    "state": "Paid",
    "price": 20,
    "currency": "USD",
    "component_values": [
      {
        "name": "page_rules",
        "value": 20,
        "default": 5,
        "price": 5
      }
    ],
    "zone": {
      "id": "023e105f4ecef8ad9ca31a8372d0c353",
      "name": "example.com"
    },
    "frequency": "monthly",
    "rate_plan": {
      "id": "free",
      "public_name": "Business Plan",
      "currency": "USD",
      "scope": "zone",
      "sets": [
        {}
      ],
      "is_contract": false,
      "externally_managed": false
    },
    "current_period_end": "2014-03-31T12:20:00Z",
    "current_period_start": "2014-05-11T12:20:00Z"
  }
}

account-subscriptions-update-subscription

PUT Update Subscription permission needed: #billing:read#billing:edit
free
pro
business
enterprise

Update an account subscriptions.

PUT accounts/:account_identifier/subscriptions/:subscription_identifier

Optional parameters

Name /type	Description /example	Constraints
app	`{ "install_id": null }` An object with the following properties: Show definition »
current_period_end string (date-time)	The end of the current period, and also when the next billing is due `"2014-03-31T12:20:00Z"`	read only
component_values array	The list of add-ons subscribed to `[ { "name": "page_rules", "value": 20, "default": 5, "price": 5 } ]` An array with items in the following form: Show definition »
rate_plan object	The rate plan applied to the subscription `{ "id": "free", "public_name": "Business Plan", "currency": "USD", "scope": "zone", "sets": [ {} ], "is_contract": false, "externally_managed": false }` An object with the following properties: Show definition »
price number	The price of the subscription that will be billed, in US dollars `20`	read only
current_period_start string (date-time)	When the current billing period started, may be the same as InitialPeriodStart if this is the first period `"2014-05-11T12:20:00Z"`	read only
zone object	A simple zone object. May have null properties if not a zone subscription. `{ "id": "023e105f4ecef8ad9ca31a8372d0c353", "name": "example.com" }` An object with the following properties: Show definition »
currency string	The monetary unit in which pricing information is displayed `"USD"`	read only
state string	The state that the subscription is in `"Paid"`	valid values: Trial, Provisioned, Paid, AwaitingPayment, Cancelled, Failed, Expired read only
id string	Subscription identifier tag `"506e3185e9c882d175a2d0cb0093d9f2"`	max length: 32 read only
frequency string	How often the subscription is renewed automatically `"monthly"`	valid values: weekly, monthly, quarterly, yearly

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/subscriptions/506e3185e9c882d175a2d0cb0093d9f2" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"app":{"install_id":null},"id":"506e3185e9c882d175a2d0cb0093d9f2","state":"Paid","price":20,"currency":"USD","component_values":[{"name":"page_rules","value":20,"default":5,"price":5}],"zone":{"id":"023e105f4ecef8ad9ca31a8372d0c353","name":"example.com"},"frequency":"monthly","rate_plan":{"id":"free","public_name":"Business Plan","currency":"USD","scope":"zone","sets":[{}],"is_contract":false,"externally_managed":false},"current_period_end":"2014-03-31T12:20:00Z","current_period_start":"2014-05-11T12:20:00Z"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "app": {
      "install_id": null
    },
    "id": "506e3185e9c882d175a2d0cb0093d9f2",
    "state": "Paid",
    "price": 20,
    "currency": "USD",
    "component_values": [
      {
        "name": "page_rules",
        "value": 20,
        "default": 5,
        "price": 5
      }
    ],
    "zone": {
      "id": "023e105f4ecef8ad9ca31a8372d0c353",
      "name": "example.com"
    },
    "frequency": "monthly",
    "rate_plan": {
      "id": "free",
      "public_name": "Business Plan",
      "currency": "USD",
      "scope": "zone",
      "sets": [
        {}
      ],
      "is_contract": false,
      "externally_managed": false
    },
    "current_period_end": "2014-03-31T12:20:00Z",
    "current_period_start": "2014-05-11T12:20:00Z"
  }
}

account-subscriptions-delete-subscription

DELETE Delete Subscription permission needed: #billing:edit

Deletes an account's subscription

DELETE accounts/:account_identifier/subscriptions/:subscription_identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/subscriptions/506e3185e9c882d175a2d0cb0093d9f2" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "subscription_id": "506e3185e9c882d175a2d0cb0093d9f2"
  }
}

Organizations

An Organization is an entity which holds a set of zones for multiple users to interact with.

NOTE: This API is deprecated, please use equivalent /accounts API endpoints where possible. Account APIs provide a broader range of features, and are backwards-compatible to organization APIs.

organizations

Object definition

View properties and constraints defined on the object

Show definition

organizations-organization-details

GET Organization Details permission needed: #organization:read
free
pro
business
enterprise

Get information about a specific organization that you are a member of

GET organizations/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "01a7362d577a6c3019a474fd6f485823",
    "name": "Cloudflare, Inc.",
    "members": [
      {
        "id": "7c5dae5552338874e5053f2534d2767a",
        "name": "John Smith",
        "email": "[email protected]",
        "status": "accepted",
        "roles": [
          {
            "id": "3536bcfad5faccb999b47003c79917fb",
            "name": "Organization Admin",
            "description": "Administrative access to the entire Organization",
            "permissions": [
              "#zones:read"
            ]
          }
        ]
      }
    ],
    "invites": [
      {
        "id": "4f5f0c14a2a41d5063dd301b2f829f04",
        "invited_member_id": "5a7805061c76ada191ed06f989cc3dac",
        "invited_member_email": "[email protected]",
        "organization_id": "5a7805061c76ada191ed06f989cc3dac",
        "organization_name": "Cloudflare, Inc.",
        "roles": [
          {
            "id": "3536bcfad5faccb999b47003c79917fb",
            "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",
        "organization_is_enforcing_twofactor": true,
        "status": "accepted"
      }
    ],
    "roles": [
      {
        "id": "3536bcfad5faccb999b47003c79917fb",
        "name": "Organization Admin",
        "description": "Administrative access to the entire Organization",
        "permissions": [
          "#zones:read"
        ]
      }
    ]
  }
}

organizations-edit-organization

PATCH Edit Organization permission needed: #organization:edit
free
pro
business
enterprise

Update an existing Organization

PATCH organizations/:identifier

Optional parameters

Name /type	Description /example	Constraints
name string	Organization Name `"Cloudflare, Inc."`	max length: 100

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Cloudflare, Inc."}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "01a7362d577a6c3019a474fd6f485823",
    "name": "Cloudflare, Inc.",
    "members": [
      {
        "id": "7c5dae5552338874e5053f2534d2767a",
        "name": "John Smith",
        "email": "[email protected]",
        "status": "accepted",
        "roles": [
          {
            "id": "3536bcfad5faccb999b47003c79917fb",
            "name": "Organization Admin",
            "description": "Administrative access to the entire Organization",
            "permissions": [
              "#zones:read"
            ]
          }
        ]
      }
    ],
    "invites": [
      {
        "id": "4f5f0c14a2a41d5063dd301b2f829f04",
        "invited_member_id": "5a7805061c76ada191ed06f989cc3dac",
        "invited_member_email": "[email protected]",
        "organization_id": "5a7805061c76ada191ed06f989cc3dac",
        "organization_name": "Cloudflare, Inc.",
        "roles": [
          {
            "id": "3536bcfad5faccb999b47003c79917fb",
            "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",
        "organization_is_enforcing_twofactor": true,
        "status": "accepted"
      }
    ],
    "roles": [
      {
        "id": "3536bcfad5faccb999b47003c79917fb",
        "name": "Organization Admin",
        "description": "Administrative access to the entire Organization",
        "permissions": [
          "#zones:read"
        ]
      }
    ]
  }
}

Organization Invites

Invitations to potential members that this organization has created

organization-invites

Object definition

View properties and constraints defined on the object

Show definition

organization-invites-list-invitations

GET List Invitations permission needed: #organization:read
free
pro
business
enterprise

List all invitations associated with an organization

GET organizations/:organization_identifier/invites

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/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": "4f5f0c14a2a41d5063dd301b2f829f04",
      "invited_member_id": "5a7805061c76ada191ed06f989cc3dac",
      "invited_member_email": "[email protected]",
      "organization_id": "5a7805061c76ada191ed06f989cc3dac",
      "organization_name": "Cloudflare, Inc.",
      "roles": [
        {
          "id": "3536bcfad5faccb999b47003c79917fb",
          "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",
      "organization_is_enforcing_twofactor": true,
      "status": "accepted"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

organization-invites-create-invitation

POST Create Invitation permission needed: #organization:edit
free
pro
business
enterprise

Invite a User to become a Member of an Organization

POST organizations/:organization_identifier/invites

Required parameters

Name /type	Description /example	Constraints
invited_member_email string	Email address of the user to be added to the Organization `"[email protected]"`	max length: 90
roles array	Array of Roles associated with the invited user `[ { "id": "5a7805061c76ada191ed06f989cc3dac" }, { "id": "9a7806061c88ada191ed06f989cc3dac" } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
auto_accept boolean	When present and set to true, allows for the invited user to be automatically accepted to the organization. No invitation is sent. `true`	default value: false valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/invites" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"invited_member_email":"[email protected]","roles":[{"id":"5a7805061c76ada191ed06f989cc3dac"},{"id":"9a7806061c88ada191ed06f989cc3dac"}],"auto_accept":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "4f5f0c14a2a41d5063dd301b2f829f04",
    "invited_member_id": "5a7805061c76ada191ed06f989cc3dac",
    "invited_member_email": "[email protected]",
    "organization_id": "5a7805061c76ada191ed06f989cc3dac",
    "organization_name": "Cloudflare, Inc.",
    "roles": [
      {
        "id": "3536bcfad5faccb999b47003c79917fb",
        "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",
    "organization_is_enforcing_twofactor": true,
    "status": "accepted"
  }
}

organization-invites-invitation-details

GET Invitation Details permission needed: #organization:read
free
pro
business
enterprise

Get the details of an invitation

GET organizations/:organization_identifier/invites/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/invites/4f5f0c14a2a41d5063dd301b2f829f04" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "4f5f0c14a2a41d5063dd301b2f829f04",
    "invited_member_id": "5a7805061c76ada191ed06f989cc3dac",
    "invited_member_email": "[email protected]",
    "organization_id": "5a7805061c76ada191ed06f989cc3dac",
    "organization_name": "Cloudflare, Inc.",
    "roles": [
      {
        "id": "3536bcfad5faccb999b47003c79917fb",
        "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",
    "organization_is_enforcing_twofactor": true,
    "status": "accepted"
  }
}

organization-invites-edit-invitation-roles

PATCH Edit Invitation Roles permission needed: #organization:edit
free
pro
business
enterprise

Change the Roles of a Pending Invite

PATCH organizations/:organization_identifier/invites/:identifier

Optional parameters

Name /type	Description /example	Constraints
roles array	Array of Roles associated with the invited user `[ "3536bcfad5faccb999b47003c79917fb" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/invites/4f5f0c14a2a41d5063dd301b2f829f04" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"roles":["3536bcfad5faccb999b47003c79917fb"]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "4f5f0c14a2a41d5063dd301b2f829f04",
    "invited_member_id": "5a7805061c76ada191ed06f989cc3dac",
    "invited_member_email": "[email protected]",
    "organization_id": "5a7805061c76ada191ed06f989cc3dac",
    "organization_name": "Cloudflare, Inc.",
    "roles": [
      {
        "id": "3536bcfad5faccb999b47003c79917fb",
        "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",
    "organization_is_enforcing_twofactor": true,
    "status": "accepted"
  }
}

organization-invites-cancel-invitation

DELETE Cancel Invitation permission needed: #organization:edit
free
pro
business
enterprise

Cancel an existing invitation

DELETE organizations/:organization_identifier/invites/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/invites/4f5f0c14a2a41d5063dd301b2f829f04" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "id": "4f5f0c14a2a41d5063dd301b2f829f04"
}

Organization Members

A member is the association of a Cloudflare user with an Organization.

organization-members

Object definition

View properties and constraints defined on the object

Show definition

organization-members-list-members

GET List Members permission needed: #organization:read
free
pro
business
enterprise

List all members of a organization

GET organizations/:organization_identifier/members

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/members" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "7c5dae5552338874e5053f2534d2767a",
      "name": "John Smith",
      "email": "[email protected]",
      "status": "accepted",
      "roles": [
        {
          "id": "3536bcfad5faccb999b47003c79917fb",
          "name": "Organization Admin",
          "description": "Administrative access to the entire Organization",
          "permissions": [
            "#zones:read"
          ]
        }
      ]
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

organization-members-member-details

GET Member Details permission needed: #organization:read
free
pro
business
enterprise

Get information about a specific member of an organization

GET organizations/:organization_identifier/members/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/members/7c5dae5552338874e5053f2534d2767a" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "7c5dae5552338874e5053f2534d2767a",
    "name": "John Smith",
    "email": "[email protected]",
    "status": "accepted",
    "roles": [
      {
        "id": "3536bcfad5faccb999b47003c79917fb",
        "name": "Organization Admin",
        "description": "Administrative access to the entire Organization",
        "permissions": [
          "#zones:read"
        ]
      }
    ]
  }
}

organization-members-edit-member-roles

PATCH Edit Member Roles permission needed: #organization:edit
free
pro
business
enterprise

Change the Roles of an Organization's Member

PATCH organizations/:organization_identifier/members/:identifier

Optional parameters

Name /type	Description /example	Constraints
roles array	Array of Roles associated with this Member `[ "3536bcfad5faccb999b47003c79917fb" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/members/7c5dae5552338874e5053f2534d2767a" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"roles":["3536bcfad5faccb999b47003c79917fb"]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "7c5dae5552338874e5053f2534d2767a",
    "name": "John Smith",
    "email": "[email protected]",
    "status": "accepted",
    "roles": [
      {
        "id": "3536bcfad5faccb999b47003c79917fb",
        "name": "Organization Admin",
        "description": "Administrative access to the entire Organization",
        "permissions": [
          "#zones:read"
        ]
      }
    ]
  }
}

organization-members-remove-member

DELETE Remove Member permission needed: #organization:edit
free
pro
business
enterprise

Remove a member from an organization

DELETE organizations/:organization_identifier/members/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/members/7c5dae5552338874e5053f2534d2767a" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "id": "7c5dae5552338874e5053f2534d2767a"
}

Organization Roles

A role defines what permissions a Member of an Organization has.

organization-roles

Object definition

View properties and constraints defined on the object

Show definition

organization-roles-list-roles

GET List Roles permission needed: #organization:read
free
pro
business
enterprise

Get all available roles for an organization

GET organizations/:organization_identifier/roles

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/roles" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "3536bcfad5faccb999b47003c79917fb",
      "name": "Organization Admin",
      "description": "Administrative access to the entire Organization",
      "permissions": [
        "#zones:read"
      ]
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

organization-roles-role-details

GET Role Details permission needed: #organization:read
free
pro
business
enterprise

Get information about a specific role for an organization

GET organizations/:organization_identifier/roles/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/roles/3536bcfad5faccb999b47003c79917fb" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "3536bcfad5faccb999b47003c79917fb",
    "name": "Organization Admin",
    "description": "Administrative access to the entire Organization",
    "permissions": [
      "#zones:read"
    ]
  }
}

User's Invites

Your pending invitations to organizations

user-s-invites

Object definition

View properties and constraints defined on the object

Show definition

user-s-invites-list-invitations

GET List Invitations
free
pro
business
enterprise

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": "4f5f0c14a2a41d5063dd301b2f829f04",
      "invited_member_id": "5a7805061c76ada191ed06f989cc3dac",
      "invited_member_email": "[email protected]",
      "organization_id": "5a7805061c76ada191ed06f989cc3dac",
      "organization_name": "Cloudflare, Inc.",
      "roles": [
        {
          "id": "3536bcfad5faccb999b47003c79917fb",
          "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
  }
}

user-s-invites-invitation-details

GET Invitation Details
free
pro
business
enterprise

Get the details of an invitation

GET user/invites/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/user/invites/4f5f0c14a2a41d5063dd301b2f829f04" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "4f5f0c14a2a41d5063dd301b2f829f04",
    "invited_member_id": "5a7805061c76ada191ed06f989cc3dac",
    "invited_member_email": "[email protected]",
    "organization_id": "5a7805061c76ada191ed06f989cc3dac",
    "organization_name": "Cloudflare, Inc.",
    "roles": [
      {
        "id": "3536bcfad5faccb999b47003c79917fb",
        "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"
  }
}

user-s-invites-respond-to-invitation

PATCH Respond to Invitation
free
pro
business
enterprise

Respond to an invitation

PATCH user/invites/:identifier

Required parameters

Name /type	Description /example	Constraints
status	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/4f5f0c14a2a41d5063dd301b2f829f04" \
     -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": "4f5f0c14a2a41d5063dd301b2f829f04",
    "invited_member_id": "5a7805061c76ada191ed06f989cc3dac",
    "invited_member_email": "[email protected]",
    "organization_id": "5a7805061c76ada191ed06f989cc3dac",
    "organization_name": "Cloudflare, Inc.",
    "roles": [
      {
        "id": "3536bcfad5faccb999b47003c79917fb",
        "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"
  }
}

User's Organizations

A list of organizations this user is a member of

user-s-organizations

Object definition

View properties and constraints defined on the object

Show definition

user-s-organizations-list-organizations

GET List Organizations
free
pro
business
enterprise

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": "01a7362d577a6c3019a474fd6f485823",
      "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
  }
}

user-s-organizations-organization-details

GET Organization Details
free
pro
business
enterprise

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/01a7362d577a6c3019a474fd6f485823" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "01a7362d577a6c3019a474fd6f485823",
    "name": "Cloudflare, Inc.",
    "status": "member",
    "permissions": [
      "#zones:read"
    ],
    "roles": [
      "All Privileges - Super Administrator"
    ]
  }
}

user-s-organizations-leave-organization

DELETE Leave Organization
free
pro
business
enterprise

Remove association to an organization

DELETE user/organizations/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/user/organizations/01a7362d577a6c3019a474fd6f485823" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "id": "01a7362d577a6c3019a474fd6f485823"
}

User Billing Profile

A user billing profile

user-billing-profile

Object definition

View properties and constraints defined on the object

Show definition

user-billing-profile-billing-profile-details

GET Billing Profile Details permission needed: #billing:read
free
pro
business
enterprise

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": {
    "id": "0020c268dbf54e975e7fe8563df49d52",
    "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 History

A user billing history

user-billing-history

Object definition

View properties and constraints defined on the object

Show definition

user-billing-history-billing-history-details

GET Billing History Details permission needed: #billing:read
free
pro
business
enterprise

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 (date-time)	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": "b69a9f3492637782896352daae219e7d",
      "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
  }
}

User Subscription

Listing of a user's subscriptions

user-subscription

Object definition

View properties and constraints defined on the object

Show definition

user-subscription-get-user-subscriptions

GET Get User Subscriptions permission needed: #billing:read

Lists all a user's subscriptions

GET user/subscriptions

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/user/subscriptions" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "app": {
        "install_id": null
      },
      "id": "506e3185e9c882d175a2d0cb0093d9f2",
      "state": "Paid",
      "price": 20,
      "currency": "USD",
      "component_values": [
        {
          "name": "page_rules",
          "value": 20,
          "default": 5,
          "price": 5
        }
      ],
      "zone": {
        "id": "023e105f4ecef8ad9ca31a8372d0c353",
        "name": "example.com"
      },
      "frequency": "monthly",
      "rate_plan": {
        "id": "free",
        "public_name": "Business Plan",
        "currency": "USD",
        "scope": "zone",
        "sets": [
          {}
        ],
        "is_contract": false,
        "externally_managed": false
      },
      "current_period_end": "2014-03-31T12:20:00Z",
      "current_period_start": "2014-05-11T12:20:00Z"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

user-subscription-update-user-subscription

PUT Update User Subscription permission needed: #billing:read#billing:edit
free
pro
business
enterprise

Update a user subscriptions.

PUT user/subscriptions/:identifier

Optional parameters

Name /type	Description /example	Constraints
app	`{ "install_id": null }` An object with the following properties: Show definition »
current_period_end string (date-time)	The end of the current period, and also when the next billing is due `"2014-03-31T12:20:00Z"`	read only
component_values array	The list of add-ons subscribed to `[ { "name": "page_rules", "value": 20, "default": 5, "price": 5 } ]` An array with items in the following form: Show definition »
rate_plan object	The rate plan applied to the subscription `{ "id": "free", "public_name": "Business Plan", "currency": "USD", "scope": "zone", "sets": [ {} ], "is_contract": false, "externally_managed": false }` An object with the following properties: Show definition »
price number	The price of the subscription that will be billed, in US dollars `20`	read only
current_period_start string (date-time)	When the current billing period started, may be the same as InitialPeriodStart if this is the first period `"2014-05-11T12:20:00Z"`	read only
zone object	A simple zone object. May have null properties if not a zone subscription. `{ "id": "023e105f4ecef8ad9ca31a8372d0c353", "name": "example.com" }` An object with the following properties: Show definition »
currency string	The monetary unit in which pricing information is displayed `"USD"`	read only
state string	The state that the subscription is in `"Paid"`	valid values: Trial, Provisioned, Paid, AwaitingPayment, Cancelled, Failed, Expired read only
id string	Subscription identifier tag `"506e3185e9c882d175a2d0cb0093d9f2"`	max length: 32 read only
frequency string	How often the subscription is renewed automatically `"monthly"`	valid values: weekly, monthly, quarterly, yearly

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/user/subscriptions/506e3185e9c882d175a2d0cb0093d9f2" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"app":{"install_id":null},"id":"506e3185e9c882d175a2d0cb0093d9f2","state":"Paid","price":20,"currency":"USD","component_values":[{"name":"page_rules","value":20,"default":5,"price":5}],"zone":{"id":"023e105f4ecef8ad9ca31a8372d0c353","name":"example.com"},"frequency":"monthly","rate_plan":{"id":"free","public_name":"Business Plan","currency":"USD","scope":"zone","sets":[{}],"is_contract":false,"externally_managed":false},"current_period_end":"2014-03-31T12:20:00Z","current_period_start":"2014-05-11T12:20:00Z"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "app": {
      "install_id": null
    },
    "id": "506e3185e9c882d175a2d0cb0093d9f2",
    "state": "Paid",
    "price": 20,
    "currency": "USD",
    "component_values": [
      {
        "name": "page_rules",
        "value": 20,
        "default": 5,
        "price": 5
      }
    ],
    "zone": {
      "id": "023e105f4ecef8ad9ca31a8372d0c353",
      "name": "example.com"
    },
    "frequency": "monthly",
    "rate_plan": {
      "id": "free",
      "public_name": "Business Plan",
      "currency": "USD",
      "scope": "zone",
      "sets": [
        {}
      ],
      "is_contract": false,
      "externally_managed": false
    },
    "current_period_end": "2014-03-31T12:20:00Z",
    "current_period_start": "2014-05-11T12:20:00Z"
  }
}

user-subscription-delete-user-subscription

DELETE Delete User Subscription permission needed: #billing:edit

Deletes a user's subscription

DELETE user/subscriptions/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/user/subscriptions/506e3185e9c882d175a2d0cb0093d9f2" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "subscription_id": "506e3185e9c882d175a2d0cb0093d9f2"
}

Account Billing Profile

Account's billing profile

account-billing-profile

Object definition

View properties and constraints defined on the object

Show definition

account-billing-profile-billing-profile-details

GET Billing Profile Details permission needed: #billing:read
free
pro
business
enterprise

Get the current billing profile for the account

GET accounts/:account_identifier/billing/profile

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/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": {
    "id": "0020c268dbf54e975e7fe8563df49d52",
    "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"
  }
}

Zone Rate Plan

A zone rate plan from the billing service

zone-rate-plan

Object definition

View properties and constraints defined on the object

Show definition

zone-rate-plan-list-available-rate-plans

GET List Available Rate Plans permission needed: #billing:read
free
pro
business
enterprise

List all rate plans the zone can subscribe to.

GET zones/:zone_identifier/available_rate_plans

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/available_rate_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": "free",
      "name": "Free Plan",
      "currency": "USD",
      "duration": 1,
      "frequency": "monthly",
      "components": [
        {
          "name": "page_rules",
          "default": 5,
          "unit_price": 1
        }
      ]
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

zone-rate-plan-list-available-plans

GET List Available Plans permission needed: #billing:read
free
pro
business
enterprise

List available plans the zone can subscribe to.

GET zones/:zone_identifier/available_plans

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/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": "Free Plan",
      "currency": "USD",
      "frequency": "monthly",
      "price": 0,
      "is_subscribed": false,
      "can_subscribe": true,
      "legacy_id": "free",
      "legacy_discount": false,
      "externally_managed": false
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

zone-rate-plan-available-plan-details

GET Available Plan Details permission needed: #billing:read
free
pro
business
enterprise

Details of an available plan that the zone can subscribe to.

GET zones/:zone_identifier/available_plans/:plan_identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/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": "Free Plan",
    "currency": "USD",
    "frequency": "monthly",
    "price": 0,
    "is_subscribed": false,
    "can_subscribe": true,
    "legacy_id": "free",
    "legacy_discount": false,
    "externally_managed": false
  }
}

Zone Subscription

A subscription associated with a zone containing plan and add-ons

zone-subscription

Object definition

View properties and constraints defined on the object

Show definition

zone-subscription-zone-subscription-details

GET Zone Subscription Details permission needed: #billing:read
free
pro
business
enterprise

Zone subscription details

GET zones/:identifier/subscription

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/506e3185e9c882d175a2d0cb0093d9f2/subscription" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "app": {
      "install_id": null
    },
    "id": "506e3185e9c882d175a2d0cb0093d9f2",
    "state": "Paid",
    "price": 20,
    "currency": "USD",
    "component_values": [
      {
        "name": "page_rules",
        "value": 20,
        "default": 5,
        "price": 5
      }
    ],
    "zone": {
      "id": "023e105f4ecef8ad9ca31a8372d0c353",
      "name": "example.com"
    },
    "frequency": "monthly",
    "rate_plan": {
      "id": "free",
      "public_name": "Business Plan",
      "currency": "USD",
      "scope": "zone",
      "sets": [
        {}
      ],
      "is_contract": false,
      "externally_managed": false
    },
    "current_period_end": "2014-03-31T12:20:00Z",
    "current_period_start": "2014-05-11T12:20:00Z"
  }
}

zone-subscription-update-zone-subscription

PUT Update Zone Subscription permission needed: #billing:read#billing:edit
free
pro
business
enterprise

Update Zone subscriptions. Either plan and add-ons

PUT zones/:identifier/subscription

Optional parameters

Name /type	Description /example	Constraints
app	`{ "install_id": null }` An object with the following properties: Show definition »
current_period_end string (date-time)	The end of the current period, and also when the next billing is due `"2014-03-31T12:20:00Z"`	read only
component_values array	The list of add-ons subscribed to `[ { "name": "page_rules", "value": 20, "default": 5, "price": 5 } ]` An array with items in the following form: Show definition »
rate_plan object	The rate plan applied to the subscription `{ "id": "free", "public_name": "Business Plan", "currency": "USD", "scope": "zone", "sets": [ {} ], "is_contract": false, "externally_managed": false }` An object with the following properties: Show definition »
price number	The price of the subscription that will be billed, in US dollars `20`	read only
current_period_start string (date-time)	When the current billing period started, may be the same as InitialPeriodStart if this is the first period `"2014-05-11T12:20:00Z"`	read only
zone object	A simple zone object. May have null properties if not a zone subscription. `{ "id": "023e105f4ecef8ad9ca31a8372d0c353", "name": "example.com" }` An object with the following properties: Show definition »
currency string	The monetary unit in which pricing information is displayed `"USD"`	read only
state string	The state that the subscription is in `"Paid"`	valid values: Trial, Provisioned, Paid, AwaitingPayment, Cancelled, Failed, Expired read only
id string	Subscription identifier tag `"506e3185e9c882d175a2d0cb0093d9f2"`	max length: 32 read only
frequency string	How often the subscription is renewed automatically `"monthly"`	valid values: weekly, monthly, quarterly, yearly

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/506e3185e9c882d175a2d0cb0093d9f2/subscription" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"app":{"install_id":null},"id":"506e3185e9c882d175a2d0cb0093d9f2","state":"Paid","price":20,"currency":"USD","component_values":[{"name":"page_rules","value":20,"default":5,"price":5}],"zone":{"id":"023e105f4ecef8ad9ca31a8372d0c353","name":"example.com"},"frequency":"monthly","rate_plan":{"id":"free","public_name":"Business Plan","currency":"USD","scope":"zone","sets":[{}],"is_contract":false,"externally_managed":false},"current_period_end":"2014-03-31T12:20:00Z","current_period_start":"2014-05-11T12:20:00Z"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "app": {
      "install_id": null
    },
    "id": "506e3185e9c882d175a2d0cb0093d9f2",
    "state": "Paid",
    "price": 20,
    "currency": "USD",
    "component_values": [
      {
        "name": "page_rules",
        "value": 20,
        "default": 5,
        "price": 5
      }
    ],
    "zone": {
      "id": "023e105f4ecef8ad9ca31a8372d0c353",
      "name": "example.com"
    },
    "frequency": "monthly",
    "rate_plan": {
      "id": "free",
      "public_name": "Business Plan",
      "currency": "USD",
      "scope": "zone",
      "sets": [
        {}
      ],
      "is_contract": false,
      "externally_managed": false
    },
    "current_period_end": "2014-03-31T12:20:00Z",
    "current_period_start": "2014-05-11T12:20:00Z"
  }
}

zone-subscription-create-zone-subscription

POST Create Zone Subscription permission needed: #billing:read#billing:edit
free
pro
business
enterprise

Create a Zone subscriptions. Either plan or add-ons

POST zones/:identifier/subscription

Optional parameters

Name /type	Description /example	Constraints
app	`{ "install_id": null }` An object with the following properties: Show definition »
current_period_end string (date-time)	The end of the current period, and also when the next billing is due `"2014-03-31T12:20:00Z"`	read only
component_values array	The list of add-ons subscribed to `[ { "name": "page_rules", "value": 20, "default": 5, "price": 5 } ]` An array with items in the following form: Show definition »
rate_plan object	The rate plan applied to the subscription `{ "id": "free", "public_name": "Business Plan", "currency": "USD", "scope": "zone", "sets": [ {} ], "is_contract": false, "externally_managed": false }` An object with the following properties: Show definition »
price number	The price of the subscription that will be billed, in US dollars `20`	read only
current_period_start string (date-time)	When the current billing period started, may be the same as InitialPeriodStart if this is the first period `"2014-05-11T12:20:00Z"`	read only
zone object	A simple zone object. May have null properties if not a zone subscription. `{ "id": "023e105f4ecef8ad9ca31a8372d0c353", "name": "example.com" }` An object with the following properties: Show definition »
currency string	The monetary unit in which pricing information is displayed `"USD"`	read only
state string	The state that the subscription is in `"Paid"`	valid values: Trial, Provisioned, Paid, AwaitingPayment, Cancelled, Failed, Expired read only
id string	Subscription identifier tag `"506e3185e9c882d175a2d0cb0093d9f2"`	max length: 32 read only
frequency string	How often the subscription is renewed automatically `"monthly"`	valid values: weekly, monthly, quarterly, yearly

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/506e3185e9c882d175a2d0cb0093d9f2/subscription" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"app":{"install_id":null},"id":"506e3185e9c882d175a2d0cb0093d9f2","state":"Paid","price":20,"currency":"USD","component_values":[{"name":"page_rules","value":20,"default":5,"price":5}],"zone":{"id":"023e105f4ecef8ad9ca31a8372d0c353","name":"example.com"},"frequency":"monthly","rate_plan":{"id":"free","public_name":"Business Plan","currency":"USD","scope":"zone","sets":[{}],"is_contract":false,"externally_managed":false},"current_period_end":"2014-03-31T12:20:00Z","current_period_start":"2014-05-11T12:20:00Z"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "app": {
      "install_id": null
    },
    "id": "506e3185e9c882d175a2d0cb0093d9f2",
    "state": "Paid",
    "price": 20,
    "currency": "USD",
    "component_values": [
      {
        "name": "page_rules",
        "value": 20,
        "default": 5,
        "price": 5
      }
    ],
    "zone": {
      "id": "023e105f4ecef8ad9ca31a8372d0c353",
      "name": "example.com"
    },
    "frequency": "monthly",
    "rate_plan": {
      "id": "free",
      "public_name": "Business Plan",
      "currency": "USD",
      "scope": "zone",
      "sets": [
        {}
      ],
      "is_contract": false,
      "externally_managed": false
    },
    "current_period_end": "2014-03-31T12:20:00Z",
    "current_period_start": "2014-05-11T12:20:00Z"
  }
}

Audit Logs

A log of changes made to your Cloudflare account

audit-logs

Object definition

View properties and constraints defined on the object

Show definition

audit-logs-list-user-audit-logs

GET List User Audit Logs
free
pro
business
enterprise

Get audit logs for a user account, filter by who made the change, which zone was the change was made on, and the timeframe of the change

GET user/audit_logs

Optional parameters

Name /type	Description /example	Constraints
actor.ip string	Filter by the IP address of the request that made the change by specific IP address or valid CIDR Range `"17.168.228.63"`
actor.email string (email)	Filter by the email address of the actor that made the change `"[email protected]"`
zone.name string	Filter by the name of the zone associated to the change. `"example.com"`
page number	Which page of results to return. `50`	default value: 1 min value:1
per_page number	How many results to return per page. `25`	default value: 100 min value:1 max value:1000
action.type string	Filter by the action type. `"add"`
export boolean	Indicates that this request is an export of logs in CSV format `"true"`	valid values: (true,false)
since string (date-time)	Limit the returned results to logs newer than the specified date. This can be a date string `2019-04-30` or an absolute timestamp that conforms to RFC3339 `"2019-04-30T01:12:20Z"`
id string	Find a specific log by its ID. `"f174be97-19b1-40d6-954d-70cd5fbd52db"`
direction string	Change the direction of the chronological sorting. `"desc"`	default value: desc valid values: desc, asc
before string (date-time)	Limit the returned results to logs older than the specified date. This can be a date string `2019-04-30` or an absolute timestamp that conforms to RFC3339 `"2019-04-30T01:12:20Z"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/user/audit_logs?id=f174be97-19b1-40d6-954d-70cd5fbd52db&export=true&action.type=add&actor.ip=17.168.228.63&[email protected]&since=2019-04-30T01:12:20Z&before=2019-04-30T01:12:20Z&zone.name=example.com&direction=desc&per_page=25&page=50" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": null,
  "messages": [],
  "result": [
    {
      "id": "d5b0f326-1232-4452-8858-1089bd7168ef",
      "action": {
        "type": "change_setting",
        "result": true
      },
      "actor": {
        "id": "f6b5de0326bb5182b8a4840ee01ec774",
        "email": "[email protected]",
        "type": "user",
        "ip": "198.41.129.166"
      },
      "newValue": "low",
      "oldValue": "high",
      "owner": {
        "id": "7c5dae5552338874e5053f2534d2767a"
      },
      "resource": {
        "type": "zone",
        "id": "023e105f4ecef8ad9ca31a8372d0c353"
      },
      "interface": "API",
      "metadata": {
        "zone_name": "example.com",
        "type": "firewall",
        "name": "security_level",
        "value": "high"
      },
      "when": "2017-04-26T17:31:07Z"
    }
  ]
}

audit-logs-list-organization-audit-logs

GET List Organization Audit Logs
free
pro
business
enterprise

Get audit logs for an organization, filter by who made the change, which zone was the change was made on, and the timeframe of the change

GET organizations/:organization_identifier/audit_logs

Optional parameters

Name /type	Description /example	Constraints
actor.ip string	Filter by the IP address of the request that made the change by specific IP address or valid CIDR Range `"17.168.228.63"`
actor.email string (email)	Filter by the email address of the actor that made the change `"[email protected]"`
zone.name string	Filter by the name of the zone associated to the change. `"example.com"`
page number	Which page of results to return. `50`	default value: 1 min value:1
per_page number	How many results to return per page. `25`	default value: 100 min value:1 max value:1000
action.type string	Filter by the action type. `"add"`
export boolean	Indicates that this request is an export of logs in CSV format `"true"`	valid values: (true,false)
since string (date-time)	Limit the returned results to logs newer than the specified date. This can be a date string `2019-04-30` or an absolute timestamp that conforms to RFC3339 `"2019-04-30T01:12:20Z"`
id string	Find a specific log by its ID. `"f174be97-19b1-40d6-954d-70cd5fbd52db"`
direction string	Change the direction of the chronological sorting. `"desc"`	default value: desc valid values: desc, asc
before string (date-time)	Limit the returned results to logs older than the specified date. This can be a date string `2019-04-30` or an absolute timestamp that conforms to RFC3339 `"2019-04-30T01:12:20Z"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/audit_logs?id=f174be97-19b1-40d6-954d-70cd5fbd52db&export=true&action.type=add&actor.ip=17.168.228.63&[email protected]&since=2019-04-30T01:12:20Z&before=2019-04-30T01:12:20Z&zone.name=example.com&direction=desc&per_page=25&page=50" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": null,
  "messages": [],
  "result": [
    {
      "id": "d5b0f326-1232-4452-8858-1089bd7168ef",
      "action": {
        "type": "change_setting",
        "result": true
      },
      "actor": {
        "id": "f6b5de0326bb5182b8a4840ee01ec774",
        "email": "[email protected]",
        "type": "user",
        "ip": "198.41.129.166"
      },
      "newValue": "low",
      "oldValue": "high",
      "owner": {
        "id": "7c5dae5552338874e5053f2534d2767a"
      },
      "resource": {
        "type": "zone",
        "id": "023e105f4ecef8ad9ca31a8372d0c353"
      },
      "interface": "API",
      "metadata": {
        "zone_name": "example.com",
        "type": "firewall",
        "name": "security_level",
        "value": "high"
      },
      "when": "2017-04-26T17:31:07Z"
    }
  ]
}

Argo Smart Routing

Query, enable and disable Argo smart routing for a zone.

argo-smart-routing

Object definition

View properties and constraints defined on the object

Show definition

argo-smart-routing-get-argo-smart-routing-setting

GET Get Argo Smart Routing setting permission needed: #argo:read
free
pro
business
enterprise

GET zones/:zone_identifier/argo/smart_routing

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/argo/smart_routing" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "smart_routing",
    "value": "on",
    "editable": true,
    "modified_on": "2019-02-20T22:37:07.107449Z"
  }
}

argo-smart-routing-patch-argo-smart-routing-setting

PATCH Patch Argo Smart Routing setting permission needed: #argo:read#argo:edit
free
pro
business
enterprise

PATCH zones/:zone_identifier/argo/smart_routing

Required parameters

Name /type	Description /example	Constraints
value string	Enablement of Argo smart routing `"on"`	valid values: on, off

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/argo/smart_routing" \
     -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": "smart_routing",
    "value": "on",
    "editable": true,
    "modified_on": "2019-02-20T22:37:07.107449Z"
  }
}

Argo Analytics for Zone

Argo Smart Routing Analytics for a zone

argo-analytics-for-zone

Object definition

View properties and constraints defined on the object

Show definition

argo-analytics-for-zone-argo-analytics-for-a-zone

GET Argo Analytics for a zone permission needed: #analytics:read
free
pro
business
enterprise

GET zones/:zone_identifier/analytics/latency

Optional parameters

Name /type	Description /example	Constraints
bins integer	Number of buckets latency is split into `3`	min value:1 max value:1000

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/analytics/latency?bins=3" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "bins": 3,
    "range": {
      "min": 0,
      "max": 2500
    },
    "time_range": {
      "since": "2019-03-04T22:05:00Z",
      "until": "2019-03-06T22:05:00Z"
    },
    "data": {
      "labels": [
        "without_argo",
        "with_argo"
      ],
      "counts": [
        [
          3306,
          362,
          1267
        ],
        [
          30685,
          11775,
          42169
        ]
      ],
      "averages": [
        192,
        120
      ],
      "percent_smart_routed": 42.5
    }
  }
}

Argo Analytics for Geolocation

Argo Smart Routing Analytics for a zone at different PoPs

argo-analytics-for-geolocation

Object definition

View properties and constraints defined on the object

Show definition

argo-analytics-for-geolocation-argo-analytics-for-a-zone-at-differnt-pops

GET Argo Analytics for a zone at differnt PoPs permission needed: #analytics:read
free
pro
business
enterprise

GET zones/:zone_identifier/analytics/latency/colos

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/analytics/latency/colos" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "FeatureCollection",
    "features": [
      {
        "properties": {
          "code": "ATL",
          "argo_req_count": 15644,
          "pct_avg_change": -0.38009502863254624,
          "no_argo_avg": 319.0564263322884,
          "argo_avg": 197.78466483011937
        },
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -84.44403,
            33.640068
          ]
        }
      }
    ]
  }
}

Zone

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

zone

Object definition

View properties and constraints defined on the object

Show definition

zone-list-zones

GET List Zones permission needed: #zone:read
free
pro
business
enterprise

List, search, sort, and filter your zones

GET zones

Optional parameters

Name /type	Description /example	Constraints
match string	Whether to match all search requirements or at least one (any) `"all"`	default value: all valid values: any, all
name string (hostname)	A domain name `"example.com"`	max length: 253
account.name string	Account name `"Demo Account"`	max length: 100
order string	Field to order zones by `"status"`	valid values: name, status, account.id, account.name
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
status string	Status of the zone `"active"`	valid values: active, pending, initializing, moved, deleted, deactivated read only
account.id string	Account identifier tag `"01a7362d577a6c3019a474fd6f485823"`	max length: 32 read only
direction string	Direction to order zones `"desc"`	valid values: asc, desc

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones?name=example.com&status=active&account.id=01a7362d577a6c3019a474fd6f485823&account.name=Demo Account&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": "023e105f4ecef8ad9ca31a8372d0c353",
      "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",
      "activated_on": "2014-01-02T00:01:00.12345Z",
      "owner": {
        "id": {},
        "email": {},
        "type": "user"
      },
      "account": {
        "id": "01a7362d577a6c3019a474fd6f485823",
        "name": "Demo Account"
      },
      "permissions": [
        "#zone:read",
        "#zone:edit"
      ],
      "plan": {
        "id": "e592fd9519420ba7405e1307bff33214",
        "name": "Pro Plan",
        "price": 20,
        "currency": "USD",
        "frequency": "monthly",
        "legacy_id": "pro",
        "is_subscribed": true,
        "can_subscribe": true
      },
      "plan_pending": {
        "id": "e592fd9519420ba7405e1307bff33214",
        "name": "Pro Plan",
        "price": 20,
        "currency": "USD",
        "frequency": "monthly",
        "legacy_id": "pro",
        "is_subscribed": true,
        "can_subscribe": true
      },
      "status": "active",
      "paused": false,
      "type": "full",
      "name_servers": [
        "tony.ns.cloudflare.com",
        "woz.ns.cloudflare.com"
      ]
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

zone-create-zone

POST Create Zone permission needed: #zone:edit
free
pro
business
enterprise

POST zones

Required parameters

Name /type	Description /example	Constraints
name string	The domain name `"example.com"`	max length: 253 read only pattern: ^([a-zA-Z0-9][\-a-zA-Z0-9]*\.)+[\-a-zA-Z0-9]{2,20}$
account object	Information about the account the zone belongs to `{ "id": "01a7362d577a6c3019a474fd6f485823", "name": "Demo Account" }` An object with the following properties: Show definition »

Optional parameters

Name /type	Description /example	Constraints
jump_start boolean	Automatically attempt to fetch existing DNS records `true`	default value: false valid values: (true,false)
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

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","account":{"id":"01a7362d577a6c3019a474fd6f485823","name":"Demo Account"},"jump_start":true,"type":"full"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "023e105f4ecef8ad9ca31a8372d0c353",
    "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",
    "activated_on": "2014-01-02T00:01:00.12345Z",
    "owner": {
      "id": {},
      "email": {},
      "type": "user"
    },
    "account": {
      "id": "01a7362d577a6c3019a474fd6f485823",
      "name": "Demo Account"
    },
    "permissions": [
      "#zone:read",
      "#zone:edit"
    ],
    "plan": {
      "id": "e592fd9519420ba7405e1307bff33214",
      "name": "Pro Plan",
      "price": 20,
      "currency": "USD",
      "frequency": "monthly",
      "legacy_id": "pro",
      "is_subscribed": true,
      "can_subscribe": true
    },
    "plan_pending": {
      "id": "e592fd9519420ba7405e1307bff33214",
      "name": "Pro Plan",
      "price": 20,
      "currency": "USD",
      "frequency": "monthly",
      "legacy_id": "pro",
      "is_subscribed": true,
      "can_subscribe": true
    },
    "status": "active",
    "paused": false,
    "type": "full",
    "name_servers": [
      "tony.ns.cloudflare.com",
      "woz.ns.cloudflare.com"
    ]
  }
}

zone-zone-details

GET Zone Details permission needed: #zone:read
free
pro
business
enterprise

GET zones/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "023e105f4ecef8ad9ca31a8372d0c353",
    "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",
    "activated_on": "2014-01-02T00:01:00.12345Z",
    "owner": {
      "id": {},
      "email": {},
      "type": "user"
    },
    "account": {
      "id": "01a7362d577a6c3019a474fd6f485823",
      "name": "Demo Account"
    },
    "permissions": [
      "#zone:read",
      "#zone:edit"
    ],
    "plan": {
      "id": "e592fd9519420ba7405e1307bff33214",
      "name": "Pro Plan",
      "price": 20,
      "currency": "USD",
      "frequency": "monthly",
      "legacy_id": "pro",
      "is_subscribed": true,
      "can_subscribe": true
    },
    "plan_pending": {
      "id": "e592fd9519420ba7405e1307bff33214",
      "name": "Pro Plan",
      "price": 20,
      "currency": "USD",
      "frequency": "monthly",
      "legacy_id": "pro",
      "is_subscribed": true,
      "can_subscribe": true
    },
    "status": "active",
    "paused": false,
    "type": "full",
    "name_servers": [
      "tony.ns.cloudflare.com",
      "woz.ns.cloudflare.com"
    ]
  }
}

zone-edit-zone

PATCH Edit Zone
free
pro
business
enterprise

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`	default value: 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" ]` An array with items in the following form: Show definition »
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": "e592fd9519420ba7405e1307bff33214" }` An object with the following properties: Show definition »

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"paused":false,"vanity_name_servers":["ns1.example.com","ns2.example.com"],"plan":{"id":"e592fd9519420ba7405e1307bff33214"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "023e105f4ecef8ad9ca31a8372d0c353",
    "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",
    "activated_on": "2014-01-02T00:01:00.12345Z",
    "owner": {
      "id": {},
      "email": {},
      "type": "user"
    },
    "account": {
      "id": "01a7362d577a6c3019a474fd6f485823",
      "name": "Demo Account"
    },
    "permissions": [
      "#zone:read",
      "#zone:edit"
    ],
    "plan": {
      "id": "e592fd9519420ba7405e1307bff33214",
      "name": "Pro Plan",
      "price": 20,
      "currency": "USD",
      "frequency": "monthly",
      "legacy_id": "pro",
      "is_subscribed": true,
      "can_subscribe": true
    },
    "plan_pending": {
      "id": "e592fd9519420ba7405e1307bff33214",
      "name": "Pro Plan",
      "price": 20,
      "currency": "USD",
      "frequency": "monthly",
      "legacy_id": "pro",
      "is_subscribed": true,
      "can_subscribe": true
    },
    "status": "active",
    "paused": false,
    "type": "full",
    "name_servers": [
      "tony.ns.cloudflare.com",
      "woz.ns.cloudflare.com"
    ]
  }
}

zone-delete-zone

DELETE Delete Zone permission needed: #zone:edit
free
pro
business
enterprise

Delete an existing zone.

DELETE zones/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353" \
     -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-zone-activation-check

PUT Zone Activation Check permission needed: #zone:edit
free
pro
business
enterprise

Initiate another zone activation check

PUT zones/:identifier/activation_check

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-purge-all-files

POST Purge All Files permission needed: #zone:edit
free
pro
business
enterprise

Remove ALL files from Cloudflare's cache

POST zones/:identifier/purge_cache

Required parameters

Name /type	Description /example	Constraints
purge_everything	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 POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-purge-files-by-url

POST Purge Files by URL permission needed: #zone:edit
free
pro
business
enterprise

Granularly remove one or more files from Cloudflare's cache either by specifying URLs. All tiers can purge by URL.

To purge files with custom cache keys, include the headers used to compute the cache key as in the example. To purge files with ${geo} or ${devicetype} in their cache keys, include the CF-Device-Type or CF-IPCountry headers.

POST zones/:identifier/purge_cache

Optional 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", { "url": "http://www.example.com/cat_picture.jpg", "headers": { "Origin": "cloudflare.com", "CF-IPCountry": "US", "CF-Device-Type": "desktop" } } ]` An array with items in the following form: Show definition »	max length: 30

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/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",{"url":"http://www.example.com/cat_picture.jpg","headers":{"Origin":"cloudflare.com","CF-IPCountry":"US","CF-Device-Type":"desktop"}}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac"
  }
}

zone-purge-files-by-cache-tags-or-host

POST Purge Files by Cache-Tags or Host permission needed: #zone:edit
free
pro
business
enterprise

Granularly remove one or more files from Cloudflare's cache either by specifying the host or the associated Cache-Tag.

NB: Cache-Tag and host purging each have a rate limit of 30,000 purge API calls in every 24 hour period. You may purge up to 30 tags or hosts in one API call. This rate limit can be raised for customers who need to purge at higher volume.

POST zones/:identifier/purge_cache

Optional parameters

Name /type	Description /example	Constraints
tags array	Any assets served with a Cache-Tag header that matches one of the provided values will be purged from the Cloudflare cache `[ "some-tag", "another-tag" ]` An array with items in the following form: Show definition »	max length: 30
hosts array	Any assets at URLs with a host that matches one of the provided values will be purged from the Cloudflare cache `[ "www.example.com", "images.example.com" ]` An array with items in the following form: Show definition »	max length: 30

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/purge_cache" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"tags":["some-tag","another-tag"],"hosts":["www.example.com","images.example.com"]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac"
  }
}

Zone error codes

Code	Description
1000	Invalid or missing user
1001	Invalid zone identifier
1002	Invalid domain
1003	'jump_start' must be boolean
1006	Invalid or missing zone
1008	Invalid or missing Zone id
1010	Bulk deal limit reached
1012	Request must contain one of 'purge_everything', 'files', 'tags', or 'hosts'
1013	'purge_everything' must be true
1014	'files', 'tags', or 'hosts' must be an array
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
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
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
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.
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
1088	Invalid/Missing Zone plan ID
1089	Invalid/Missing Zone plan ID
1092	Request cannot contain 'purge_everything' and any of 'files', 'tags', or 'hosts'
1094	Exceeded maximum amount of 500 files that can be purged on a single request
1095	Sorry, you do not have access to purge cache for that zone id or that zone id is invalid
1096	This action is not available as your zone has been deactivated for a possible Terms of Service violation
1097	This zone is banned and cannot be added to Cloudflare at this time, please contact Cloudflare Support
1098	This zone is temporarily banned and cannot be added to Cloudflare at this time, please contact Cloudflare Support
1099	We were unable to identify <domain> as a registered domain. Please ensure you are providing the root domain and not any subdomains (e.g., example.com, not subdomain.example.com)
1100	Tag exceeds maximum length of 1024 characters
1101	Exceeded maximum amount of 30 tags that can be purged on a single request
1102	Unable to purge by tag, rate limit reached. Please wait if you need to perform more
1104	Partial zone signup not allowed
1105	This zone is temporarily banned and cannot be added to Cloudflare at this time, please contact Cloudflare Support
1106	Sorry, you are not allowed to create new zones. Please contact support.
1107	Only enterprise zones can purge by tag.
1108	Unable to update domain subscription. Please contact support for assistance.
1109	Unable to update domain subscription. Please contact support for assistance.
1110	Failed to lookup registrar and hosting information of <domain> at this time. Please contact Cloudflare Support or try again later.
1111	Exceeded maximum amount of 30 hosts that can be purged on a single request
1112	Only enterprise zones can purge by host
1113	Unable to purge by host, rate limit reached. Please wait if you need to perform more operations.
1114	Host exceeds maximum length of 200 characters
1115	Invalid host

Zone Settings

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

zone-settings

Object definitions

View properties and constraints defined on the object

Show definitions

zone-settings-get-all-zone-settings

GET Get all Zone settings permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/settings" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

zone-settings-get-advanced-ddos-setting

GET Get Advanced DDOS setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-always-online-setting

GET Get Always Online setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-always-use-https-setting

GET Get Always Use HTTPS setting permission needed: #zone_settings:read
free
pro
business
enterprise

Reply to all requests for URLs that use "http" with a 301 redirect to the equivalent "https" URL. If you only want to redirect for a subset of requests, consider creating an "Always use HTTPS" page rule.

GET zones/:zone_identifier/settings/always_use_https

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/always_use_https" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": "off"
}

zone-settings-get-opportunistic-onion-setting

GET Get Opportunistic Onion setting permission needed: #zone_settings:read
free
pro
business
enterprise

Add an Alt-Svc header to all legitimate requests from Tor, allowing the connection to use our onion services instead of exit nodes.

GET zones/:zone_identifier/settings/opportunistic_onion

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/opportunistic_onion" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": "off"
}

zone-settings-get-automatic-https-rewrites-setting

GET Get Automatic HTTPS Rewrites setting permission needed: #zone_settings:edit
free
pro
business
enterprise

Enable the Automatic HTTPS Rewrites feature for this zone.

GET zones/:zone_identifier/settings/automatic_https_rewrites

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/automatic_https_rewrites" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": "off"
}

zone-settings-get-browser-cache-ttl-setting

GET Get Browser Cache TTL setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-browser-check-setting

GET Get Browser Check setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-cache-level-setting

GET Get Cache Level setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-challenge-ttl-setting

GET Get Challenge TTL setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-development-mode-setting

GET Get Development Mode setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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
  }
}

zone-settings-get-email-obfuscation-setting

GET Get Email Obfuscation setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-hotlink-protection-setting

GET Get Hotlink Protection setting permission needed: #zone_settings:read
free
pro
business
enterprise

When enabled, the Hotlink Protection option ensures that other sites cannot suck up your bandwidth by building pages that use images hosted on your site. Anytime a request for an image on your site hits Cloudflare, we check to ensure that it's not another site requesting them. People will still be able to download and view images from your page, but other sites won't be able to steal them for use on their own pages. (https://support.cloudflare.com/hc/en-us/articles/200170026)

GET zones/:zone_identifier/settings/hotlink_protection

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/hotlink_protection" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "hotlink_protection",
    "value": "off",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-get-ip-geolocation-setting

GET Get IP Geolocation setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-ipv6-setting

GET Get IPv6 setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-minify-setting

GET Get Minify setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-mobile-redirect-setting

GET Get Mobile Redirect setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-mirage-setting

GET Get Mirage setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-enable-error-pages-on-setting

GET Get Enable Error Pages On setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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": "off"
}

zone-settings-get-opportunistic-encryption-setting

GET Get Opportunistic Encryption setting permission needed: #zone_settings:edit
free
pro
business
enterprise

Enable the Opportunistic Encryption feature for this zone.

GET zones/:zone_identifier/settings/opportunistic_encryption

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/opportunistic_encryption" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "opportunistic_encryption",
    "value": "on",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-get-polish-setting

GET Get Polish setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-webp-setting

GET Get WebP setting permission needed: #zone_settings:read
free
pro
business
enterprise

When the client requesting the image supports the WebP image codec, Cloudflare will serve a WebP version of the image when WebP offers a performance advantage over the original image format.

GET zones/:zone_identifier/settings/webp

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/webp" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "webp",
    "value": "off",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-get-brotli-setting

GET Get Brotli setting permission needed: #zone_settings:read
free
pro
business
enterprise

When the client requesting an asset supports the brotli compression algorithm, Cloudflare will serve a brotli compressed version of the asset.

GET zones/:zone_identifier/settings/brotli

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/brotli" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "brotli",
    "value": "off",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-get-prefetch-preload-setting

GET Get Prefetch Preload setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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": "off"
}

zone-settings-get-privacy-pass-setting

GET Get Privacy Pass setting permission needed: #zone_settings:read
free
pro
business
enterprise

Privacy Pass is a browser extension developed by the Privacy Pass Team to improve the browsing experience for your visitors. Enabling Privacy Pass will reduce the number of CAPTCHAs shown to your visitors. (https://support.cloudflare.com/hc/en-us/articles/115001992652-Privacy-Pass)

GET zones/:zone_identifier/settings/privacy_pass

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/privacy_pass" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "privacy_pass",
    "value": "on",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-get-response-buffering-setting

GET Get Response Buffering setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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": "off"
}

zone-settings-get-rocket-loader-setting

GET Get Rocket Loader setting permission needed: #zone_settings:read
free
pro
business
enterprise

Rocket Loader is a general-purpose asynchronous JavaScript optimisation which prioritises the rendering of your content while loading your site's Javascript asynchronously. Turning on Rocket Loader will immediately improve a web page's rendering time sometimes measured as Time to First Paint (TTFP) and also the window.onload time (assuming there is JavaScript on the page), which can have a positive impact on your Google search ranking. When turned on, Rocket Loader will automatically defer the loading of all Javascript referenced in your HTML, with no configuration required. (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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-security-header-hsts-setting

GET Get Security Header (HSTS) setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-security-level-setting

GET Get Security Level setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-server-side-exclude-setting

GET Get Server Side Exclude setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-enable-query-string-sort-setting

GET Get Enable Query String Sort setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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": "off"
}

zone-settings-get-ssl-setting

GET Get SSL setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-minimum-tls-version-setting

GET Get Minimum TLS Version setting permission needed: #zone_settings:edit
free
pro
business
enterprise

Only accept HTTPS requests that use at least the TLS protocol version specified. For example, if TLS 1.1 is selected, TLS 1.0 connections will be rejected, while 1.1, 1.2, and 1.3 (if enabled) will be permitted.

GET zones/:zone_identifier/settings/min_tls_version

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/min_tls_version" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": "1.0"
}

zone-settings-get-zone-enable-tls-1.3-setting

GET Get Zone Enable TLS 1.3 setting permission needed: #zone_settings:edit
free
pro
business
enterprise

Enable Crypto TLS 1.3 feature for this zone.

GET zones/:zone_identifier/settings/tls_1_3

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/tls_1_3" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": "off"
}

zone-settings-get-tls-client-auth-setting

GET Get TLS Client Auth setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-true-client-ip-setting

GET Get True Client IP setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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": "off"
}

zone-settings-get-web-application-firewall-waf-setting

GET Get Web Application Firewall (WAF) setting permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-get-http2-setting

GET Get HTTP2 setting permission needed: #zone_settings:read
free
pro
business
enterprise

Value of the HTTP2 setting

GET zones/:zone_identifier/settings/http2

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/http2" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "http2",
    "value": "off",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-get-pseudo-ipv4-setting

GET Get Pseudo IPv4 setting permission needed: #zone_settings:read
free
pro
business
enterprise

Value of the Pseudo IPv4 setting

GET zones/:zone_identifier/settings/pseudo_ipv4

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/pseudo_ipv4" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "pseudo_ipv4",
    "value": "off",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-get-websockets-setting

GET Get WebSockets setting permission needed: #zone_settings:read
free
pro
business
enterprise

WebSockets are open connections sustained between the client and the origin server. Inside a WebSockets connection, the client and the origin can pass data back and forth without having to reestablish sessions. This makes exchanging data within a WebSockets connection fast. WebSockets are often used for real-time applications such as live chat and gaming. (https://support.cloudflare.com/hc/en-us/articles/200169466-Can-I-use-Cloudflare-with-WebSockets-)

GET zones/:zone_identifier/settings/websockets

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/websockets" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "websockets",
    "value": "off",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-get-image-resizing-setting

GET Get Image Resizing setting permission needed: #zone_settings:read
free
pro
business
enterprise

Image Resizing provides on-demand resizing, conversion and optimisation for images served through Cloudflare's network. (https://developers.cloudflare.com/images/)

GET zones/:zone_identifier/settings/image_resizing

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/image_resizing" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "image_resizing",
    "value": "off",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-get-http/2-edge-prioritization-setting

GET Get HTTP/2 Edge Prioritization setting permission needed: #zone_settings:read
free
pro
business
enterprise

HTTP/2 Edge Prioritization optimises the delivery of resources served through HTTP/2 to improve page load performance. It also supports fine control of content delivery when used in conjunction with Workers.

GET zones/:zone_identifier/settings/h2_prioritization

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/h2_prioritization" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "h2_prioritization",
    "value": "off",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-edit-zone-settings-info

PATCH Edit zone settings info permission needed: #zone_settings:edit
free
pro
business
enterprise

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" } ]` An array with items in the following form: Show definition »	min items: 1

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/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_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

zone-settings-change-always-online-setting

PATCH Change Always Online setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-change-always-use-https-setting

PATCH Change Always Use HTTPS setting permission needed: #zone_settings:edit
free
pro
business
enterprise

PATCH zones/:zone_identifier/settings/always_use_https

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/023e105f4ecef8ad9ca31a8372d0c353/settings/always_use_https" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": "off"
}

zone-settings-change-opportunistic-onion-setting

PATCH Change Opportunistic Onion setting permission needed: #zone_settings:edit
free
pro
business
enterprise

Add an Alt-Svc header to all legitimate requests from Tor, allowing the connection to use our onion services instead of exit nodes.

PATCH zones/:zone_identifier/settings/opportunistic_onion

Required parameters

Name /type	Description /example	Constraints
value string	Value of the zone setting `"off"`	default value: off valid values: on, off notes: Default value depends on the zone's plan level.

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/opportunistic_onion" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": "off"
}

zone-settings-change-automatic-https-rewrites-setting

PATCH Change Automatic HTTPS Rewrites setting permission needed: #zone_settings:edit
free
pro
business
enterprise

Enable the Automatic HTTPS Rewrites feature for this zone.

PATCH zones/:zone_identifier/settings/automatic_https_rewrites

Required parameters

Name /type	Description /example	Constraints
value string	Value of the zone setting `"on"`	default value: on valid values: on, off notes: Default value depends on the zone's plan level.

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/automatic_https_rewrites" \
     -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": "off"
}

zone-settings-change-browser-cache-ttl-setting

PATCH Change Browser Cache TTL setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-change-browser-check-setting

PATCH Change Browser Check setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-change-cache-level-setting

PATCH Change Cache Level setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/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"
  }
}

zone-settings-change-challenge-ttl-setting

PATCH Change Challenge TTL setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/settings/challenge_ttl" \
     -H "X-Auth-Email: [email protected]" \
     -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"
  }
}

zone-settings-change-development-mode-setting

PATCH Change Development Mode setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/settings/development_mode" \
     -H "X-Auth-Email: [email protected]" \
     -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
  }
}

zone-settings-change-email-obfuscation-setting

PATCH Change Email Obfuscation setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/settings/email_obfuscation" \
     -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": "email_obfuscation",
    "value": "on",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-change-enable-error-pages-on-setting

PATCH Change Enable Error Pages On setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/settings/origin_error_page_pass_thru" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": "off"
}

zone-settings-change-enable-query-string-sort-setting

PATCH Change Enable Query String Sort setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/settings/sort_query_string_for_cache" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": "off"
}

zone-settings-change-hotlink-protection-setting

PATCH Change Hotlink Protection setting permission needed: #zone_settings:edit
free
pro
business
enterprise

PATCH zones/:zone_identifier/settings/hotlink_protection

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/023e105f4ecef8ad9ca31a8372d0c353/settings/hotlink_protection" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "hotlink_protection",
    "value": "off",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-change-ip-geolocation-setting

PATCH Change IP Geolocation setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/settings/ip_geolocation" \
     -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": "ip_geolocation",
    "value": "on",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-change-ipv6-setting

PATCH Change IPv6 setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/ipv6" \
     -H "X-Auth-Email: [email protected]" \
     -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"
  }
}

zone-settings-change-minify-setting

PATCH Change Minify setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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" }` An object with the following properties: Show definition »

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/minify" \
     -H "X-Auth-Email: [email protected]" \
     -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"
  }
}

zone-settings-change-mobile-redirect-setting

PATCH Change Mobile Redirect setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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 }` An object with the following properties: Show definition »

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/mobile_redirect" \
     -H "X-Auth-Email: [email protected]" \
     -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"
  }
}

zone-settings-change-mirage-setting

PATCH Change Mirage setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/settings/mirage" \
     -H "X-Auth-Email: [email protected]" \
     -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"
  }
}

zone-settings-change-opportunistic-encryption-setting

PATCH Change Opportunistic Encryption setting permission needed: #zone_settings:edit
free
pro
business
enterprise

Enable the Opportunistic Encryption feature for this zone.

PATCH zones/:zone_identifier/settings/opportunistic_encryption

Required parameters

Name /type	Description /example	Constraints
value string	Value of the zone setting `"on"`	default value: on valid values: on, off notes: Default value depends on the zone's plan level.

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/opportunistic_encryption" \
     -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": "opportunistic_encryption",
    "value": "on",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-change-polish-setting

PATCH Change Polish setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/settings/polish" \
     -H "X-Auth-Email: [email protected]" \
     -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"
  }
}

zone-settings-change-webp-setting

PATCH Change WebP setting permission needed: #zone_settings:edit
free
pro
business
enterprise

When the client requesting the image supports the WebP image codec, Cloudflare will serve a WebP version of the image when WebP offers a performance advantage over the original image format.

PATCH zones/:zone_identifier/settings/webp

Required parameters

Name /type	Description /example	Constraints
value string	Value of the zone setting `"off"`	default value: off valid values: off, on

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/webp" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "webp",
    "value": "off",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-change-brotli-setting

PATCH Change Brotli setting permission needed: #zone_settings:edit
free
pro
business
enterprise

When the client requesting an asset supports the brotli compression algorithm, Cloudflare will serve a brotli compressed version of the asset.

PATCH zones/:zone_identifier/settings/brotli

Required parameters

Name /type	Description /example	Constraints
value string	Value of the zone setting `"off"`	default value: off valid values: off, on

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/brotli" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "brotli",
    "value": "off",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-change-prefetch-preload-setting

PATCH Change Prefetch Preload setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/settings/prefetch_preload" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": "off"
}

zone-settings-change-privacy-pass-setting

PATCH Change Privacy Pass setting permission needed: #zone_settings:edit
free
pro
business
enterprise

PATCH zones/:zone_identifier/settings/privacy_pass

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/023e105f4ecef8ad9ca31a8372d0c353/settings/privacy_pass" \
     -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": "privacy_pass",
    "value": "on",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-change-response-buffering-setting

PATCH Change Response Buffering setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/settings/response_buffering" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": "off"
}

zone-settings-change-rocket-loader-setting

PATCH Change Rocket Loader setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/rocket_loader" \
     -H "X-Auth-Email: [email protected]" \
     -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"
  }
}

zone-settings-change-security-header-hsts-setting

PATCH Change Security Header (HSTS) setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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 } }` An object with the following properties: Show definition »

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/security_header" \
     -H "X-Auth-Email: [email protected]" \
     -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"
  }
}

zone-settings-change-security-level-setting

PATCH Change Security Level setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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: off, essentially_off, low, medium, high, under_attack

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/security_level" \
     -H "X-Auth-Email: [email protected]" \
     -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"
  }
}

zone-settings-change-server-side-exclude-setting

PATCH Change Server Side Exclude setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/settings/server_side_exclude" \
     -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": "server_side_exclude",
    "value": "on",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-change-ssl-setting

PATCH Change SSL setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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, strict notes: Depends on the zone's plan level

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/ssl" \
     -H "X-Auth-Email: [email protected]" \
     -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"
  }
}

zone-settings-change-tls-client-auth-setting

PATCH Change TLS Client Auth setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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 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/023e105f4ecef8ad9ca31a8372d0c353/settings/tls_client_auth" \
     -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": "tls_client_auth",
    "value": "on",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-change-true-client-ip-setting

PATCH Change True Client IP setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/settings/true_client_ip_header" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": "off"
}

zone-settings-change-minimum-tls-version-setting

PATCH Change Minimum TLS Version setting permission needed: #zone_settings:edit
free
pro
business
enterprise

PATCH zones/:zone_identifier/settings/min_tls_version

Required parameters

Name /type	Description /example	Constraints
value string	Value of the zone setting `"1.0"`	default value: 1.0 valid values: 1.0, 1.1, 1.2, 1.3

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/min_tls_version" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"1.0"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": "1.0"
}

zone-settings-change-tls-1.3-setting

PATCH Change TLS 1.3 setting permission needed: #zone_settings:edit
free
pro
business
enterprise

Enable Crypto TLS 1.3 feature for this zone.

PATCH zones/:zone_identifier/settings/tls_1_3

Required parameters

Name /type	Description /example	Constraints
value string	Value of the zone setting `"off"`	default value: off valid values: on, off, zrt notes: Default value depends on the zone's plan level.

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/tls_1_3" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": "off"
}

zone-settings-change-web-application-firewall-waf-setting

PATCH Change Web Application Firewall (WAF) setting permission needed: #zone_settings:edit
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/settings/waf" \
     -H "X-Auth-Email: [email protected]" \
     -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"
  }
}

zone-settings-change-http2-setting

PATCH Change HTTP2 setting permission needed: #zone_settings:edit
free
pro
business
enterprise

Value of the HTTP2 setting

PATCH zones/:zone_identifier/settings/http2

Required parameters

Name /type	Description /example	Constraints
value string	Value of the HTTP2 setting `"off"`	default value: off valid values: on, off

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/http2" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "http2",
    "value": "off",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-change-pseudo-ipv4-setting

PATCH Change Pseudo IPv4 setting permission needed: #zone_settings:edit
free
pro
business
enterprise

Value of the Pseudo IPv4 setting

PATCH zones/:zone_identifier/settings/pseudo_ipv4

Required parameters

Name /type	Description /example	Constraints
value string	Value of the Pseudo IPv4 setting `"off"`	default value: off valid values: off, add_header, overwrite_header

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/pseudo_ipv4" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "pseudo_ipv4",
    "value": "off",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-change-websockets-setting

PATCH Change WebSockets setting permission needed: #zone_settings:edit
free
pro
business
enterprise

PATCH zones/:zone_identifier/settings/websockets

Required parameters

Name /type	Description /example	Constraints
value string	Value of the zone setting `"off"`	default value: off valid values: off, on

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/websockets" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "websockets",
    "value": "off",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-change-image-resizing-setting

PATCH Change Image Resizing setting permission needed: #zone_settings:edit
free
pro
business
enterprise

Image Resizing provides on-demand resizing, conversion and optimisation for images served through Cloudflare's network. (https://developers.cloudflare.com/images/)

PATCH zones/:zone_identifier/settings/image_resizing

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/023e105f4ecef8ad9ca31a8372d0c353/settings/image_resizing" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "image_resizing",
    "value": "off",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

zone-settings-change-http/2-edge-prioritization-setting

PATCH Change HTTP/2 Edge Prioritization setting permission needed: #zone_settings:edit
free
pro
business
enterprise

PATCH zones/:zone_identifier/settings/h2_prioritization

Required parameters

Name /type	Description /example	Constraints
value string	Value of the zone setting `"off"`	default value: off valid values: on, off, custom

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/h2_prioritization" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "h2_prioritization",
    "value": "off",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

Zone Analytics

Analytics data for a zone

zone-analytics

Object definitions

View properties and constraints defined on the object

Show definitions

zone-analytics-dashboard

GET Dashboard permission needed: #analytics:read
free
pro
business
enterprise

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 stringinteger	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 60 minutes (from -59 to -1): 1 minute resolution Last 7 hours (from -419 to -60): 15 minutes resolution Last 15 hours (from -899 to -420): 30 minutes resolution Last 72 hours (from -4320 to -900): 1 hour resolution Older than 3 days (-525600 to -4320): 1 day resolution `"2015-01-01T12:23:00Z"`	default value: -10080
until stringinteger	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
continuous boolean	When set to true, the API will move the requested time window backward, until it finds a region with completely aggregated data. The API response may not represent the requested time window. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/analytics/dashboard?since=2015-01-01T12:23:00Z&until=2015-01-02T12:23:00Z&continuous=true" \
     -H "X-Auth-Email: [email protected]" \
     -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
        },
        "ssl_protocols": {
          "TLSv1": 398232,
          "TLSv1.1": 12532236,
          "TLSv1.2": 2447136,
          "TLSv1.3": 10483332,
          "none": 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
        },
        "ssl_protocols": {
          "TLSv1": 398232,
          "TLSv1.1": 12532236,
          "TLSv1.2": 2447136,
          "TLSv1.3": 10483332,
          "none": 781263
        }
      },
      "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_engine": {
          "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
          },
          "ssl_protocols": {
            "TLSv1": 398232,
            "TLSv1.1": 12532236,
            "TLSv1.2": 2447136,
            "TLSv1.3": 10483332,
            "none": 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
          },
          "ssl_protocols": {
            "TLSv1": 398232,
            "TLSv1.1": 12532236,
            "TLSv1.2": 2447136,
            "TLSv1.3": 10483332,
            "none": 781263
          }
        },
        "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_engine": {
            "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
  }
}

zone-analytics-analytics-by-co-locations

GET Analytics by Co-locations permission needed: #analytics:read
free
pro
business
enterprise

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 stringinteger	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 60 minutes (from -59 to -1): 1 minute resolution Last 7 hours (from -419 to -60): 15 minutes resolution Last 15 hours (from -899 to -420): 30 minutes resolution Last 72 hours (from -4320 to -900): 1 hour resolution Older than 3 days (-525600 to -4320): 1 day resolution `"2015-01-01T12:23:00Z"`	default value: -10080
until stringinteger	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
continuous boolean	When set to true, the API will move the requested time window backward, until it finds a region with completely aggregated data. The API response may not represent the requested time window. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/analytics/colos?since=2015-01-01T12:23:00Z&until=2015-01-02T12:23:00Z&continuous=true" \
     -H "X-Auth-Email: [email protected]" \
     -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,
            "country": {
              "US": 4181364,
              "AG": 37298,
              "GI": 293846
            },
            "http_status": {
              "200": 13496983,
              "301": 283,
              "400": 187936,
              "402": 1828,
              "404": 1293
            }
          },
          "bandwidth": {
            "all": 213867451,
            "cached": 113205063,
            "uncached": 113205063
          },
          "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
            }
          }
        }
      ],
      "totals": {
        "since": "2015-01-01T12:23:00Z",
        "until": "2015-01-02T12:23:00Z",
        "requests": {
          "all": 1234085328,
          "cached": 1234085328,
          "uncached": 13876154,
          "country": {
            "US": 4181364,
            "AG": 37298,
            "GI": 293846
          },
          "http_status": {
            "200": 13496983,
            "301": 283,
            "400": 187936,
            "402": 1828,
            "404": 1293
          }
        },
        "bandwidth": {
          "all": 213867451,
          "cached": 113205063,
          "uncached": 113205063
        },
        "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
          }
        }
      }
    }
  ],
  "query": {
    "since": "2015-01-01T12:23:00Z",
    "until": "2015-01-02T12:23:00Z",
    "time_delta": 60
  }
}

Logs Received

Edge http logs received

logs-received

Object definitions

View properties and constraints defined on the object

Show definitions

logs-received-logs-received

GET Logs Received permission needed: #logs:read
free
pro
business
enterprise

The /received api route allows customers to retrieve their edge http logs. The basic access pattern is "give me all the logs for zone Z for minute M" where the minute M refers to the time records were received at Cloudflare's central data center. start is inclusive, and end is exclusive. Because of that, to get all data, at minutely cadence, starting at 10AM, the proper values are: start=2018-05-20T10:00:00Z&end=2018-05-20T10:01:00Z, then start=2018-05-20T10:01:00Z&end=2018-05-20T10:02:00Z and so on; the "overlap" will be handled properly.

GET zones/:zone_identifier/logs/received

Required parameters

Name /type	Description /example	Constraints
start stringinteger	The (inclusive) beginning of the requested time frame. This can be a unix timestamp (in seconds or nanoseconds), or an absolute timestamp that conforms to RFC 3339. At this point in time, it cannot exceed a time in the past greater than 7 days. `"2018-05-20T10:00:00Z"`
end stringinteger	The (exclusive) end of the requested time frame. This can be a unix timestamp (in seconds or nanoseconds), or an absolute timestamp that conforms to RFC 3339. `end` must be at least 5 minutes earlier than now and must be later than `start`. Difference between `start` and `end` must be not greater than 1h. `"2018-05-20T10:01:00Z"`

Optional parameters

Name /type	Description /example	Constraints
count integer	When `?count=` is provided, the response will contain up to `count` results. Since results are not sorted, you are likely to get different data for repeated requests. `count` must be an integer > 0. `7`	min value:1
sample number	When `?sample=` is provided, a sample of matching records is returned. If `sample=0.1` then 10% of records will be returned. Sampling is random: repeated calls will not only return different records, but likely will also vary slightly in number of returned records. When `?count=` is also specified, `count` is applied to the number of returned records, not the sampled records. So, with `sample=0.05` and `count=7`, when there is a total of 100 records available, approximately 5 will be returned. When there are 1000 records, 7 will be returned. When there are 10,000 records, 7 will be returned. `"0.1"`	min value:0 max value:1
fields string	The `/received` route by default returns a limited set of fields, and allows customers to override the default field set by specifying individual fields. The reasons for this are: 1. most customers require only a small subset of fields, but that subset varies from customer to customer; 2. flat schema is much easier to work with downstream (importing into BigTable etc); 3. performance (time to process, file size). If `?fields=` is not specified, default field set is returned. This default field set may change at any time. When `?fields=` is provided, each record is returned with the specified fields. `fields` must be specified as a comma separated list without any whitespaces, and all fields must exist. The order in which fields are specified doesn't matter, and the order of fields in the response is not specified. `"ClientIP,RayID,EdgeStartTimestamp"`
timestamps string	By default timestamps in responses are returned as Unix nanosecond integers. The `?timestamps=` argument can be set to change the format in which response timestamps are returned. Possible values are: `unix`, `unixnano`, `rfc3339`. Note: `unix` and `unixnano` return timestamps as integers; `rfc3339` returns timestamps as strings. `"unixnano"`	default value: unixnano valid values: unix, unixnano, rfc3339

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/logs/received?start=2018-05-20T10:00:00Z&end=2018-05-20T10:01:00Z&count=7&sample=0.1&fields=ClientIP,RayID,EdgeStartTimestamp&timestamps=unixnano" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{"ClientIP":"192.0.2.1","RayID":"41ddf1740f67442d","EdgeStartTimestamp":,1526810289280000000}
{"ClientIP":"192.0.2.1","RayID":"41ddf1740f67442d","EdgeStartTimestamp":,1526810289280000000}
{"ClientIP":"192.0.2.1","RayID":"41ddf1740f67442d","EdgeStartTimestamp":,1526810289280000000}

logs-received-logs-rayids

GET Logs RayIDs permission needed: #logs:read
free
pro
business
enterprise

The /rayids api route allows lookups by specific rayid. The rayids route will return 0, 1, or more records (ray ids are not unique).

GET zones/:zone_identifier/logs/rayids/:ray_identifier

Optional parameters

Name /type	Description /example	Constraints
fields string	The `/received` route by default returns a limited set of fields, and allows customers to override the default field set by specifying individual fields. The reasons for this are: 1. most customers require only a small subset of fields, but that subset varies from customer to customer; 2. flat schema is much easier to work with downstream (importing into BigTable etc); 3. performance (time to process, file size). If `?fields=` is not specified, default field set is returned. This default field set may change at any time. When `?fields=` is provided, each record is returned with the specified fields. `fields` must be specified as a comma separated list without any whitespaces, and all fields must exist. The order in which fields are specified doesn't matter, and the order of fields in the response is not specified. `"ClientIP,RayID,EdgeStartTimestamp"`
timestamps string	By default timestamps in responses are returned as Unix nanosecond integers. The `?timestamps=` argument can be set to change the format in which response timestamps are returned. Possible values are: `unix`, `unixnano`, `rfc3339`. Note: `unix` and `unixnano` return timestamps as integers; `rfc3339` returns timestamps as strings. `"unixnano"`	default value: unixnano valid values: unix, unixnano, rfc3339

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/logs/rayids/41ddf1740f67442d?fields=ClientIP,RayID,EdgeStartTimestamp&timestamps=unixnano" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{"ClientIP":"192.0.2.1","RayID":"41ddf1740f67442d","EdgeStartTimestamp":,1526810289280000000}
{"ClientIP":"192.0.2.1","RayID":"41ddf1740f67442d","EdgeStartTimestamp":,1526810289280000000}
{"ClientIP":"192.0.2.1","RayID":"41ddf1740f67442d","EdgeStartTimestamp":,1526810289280000000}

logs-received-fields

GET Fields permission needed: #logs:read
free
pro
business
enterprise

The list of all fields available. The response is json object with key-value pairs where keys are field names, and values are descriptions.

GET zones/:zone_identifier/logs/received/fields

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/logs/received/fields" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "key": "value"
}

Logs Received Notes

If there is an error processing the request before any data has been sent to the client, appropriate status code will be set and error message will be sent in the response body. If there is an error after the response started then an error message will be appended to the response body and the response will be aborted (connection will be closed).

Logpush Jobs

Logpush jobs

logpush-jobs

Object definition

View properties and constraints defined on the object

Show definition

logpush-jobs-list-logpush-jobs

GET List Logpush Jobs permission needed: #logs:edit
free
pro
business
enterprise

List Logpush Jobs for a zone

GET zones/:zone_identifier/logpush/jobs

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/logpush/jobs" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": 1,
      "enabled": false,
      "name": "example.com",
      "logpull_options": "fields=RayID,ClientIP,EdgeStartTimestamp&timestamps=rfc3339",
      "destination_conf": "s3://mybucket/logs?region=us-west-2",
      "last_complete": null,
      "last_error": null,
      "error_message": null
    }
  ]
}

logpush-jobs-get-ownership-challenge

POST Get Ownership Challenge permission needed: #logs:edit
free
pro
business
enterprise

Get a new ownership challenge sent to your destination

POST zones/:zone_identifier/logpush/ownership

Required parameters

Name /type	Description /example	Constraints
destination_conf string (uri)	Uniquely identifies a resource (such as an s3 bucket) where data will be pushed. Additional configuration parameters supported by the destination may be included. `"s3://mybucket/logs?region=us-west-2"`	max length: 4096

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/logpush/ownership" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"destination_conf":"s3://mybucket/logs?region=us-west-2"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "filename": "logs/challenge-filename.txt",
    "valid": true,
    "message": ""
  }
}

logpush-jobs-validate-ownership-challenge

POST Validate Ownership Challenge permission needed: #logs:edit
free
pro
business
enterprise

Validate ownership challenge of the destination

POST zones/:zone_identifier/logpush/ownership/validate

Required parameters

Name /type	Description /example	Constraints
destination_conf string (uri)	Uniquely identifies a resource (such as an s3 bucket) where data will be pushed. Additional configuration parameters supported by the destination may be included. `"s3://mybucket/logs?region=us-west-2"`	max length: 4096
ownership_challenge string	Ownership challenge token to prove destination ownership. `"00000000000000000000"`	max length: 4096 pattern: ^[a-zA-Z0-9/\+\.\-_]*$

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/logpush/ownership/validate" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"destination_conf":"s3://mybucket/logs?region=us-west-2","ownership_challenge":"00000000000000000000"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "valid": true
  }
}

logpush-jobs-validate-origin

POST Validate Origin permission needed: #logs:edit
free
pro
business
enterprise

Validate logpull origin with logpull_options

POST zones/:zone_identifier/logpush/validate/origin

Required parameters

Name /type	Description /example	Constraints
logpull_options stringnull (uri)	Configuration string for the logshare api. It specifies things like requested fields and timestamp formats. Copy the url (full url or just the query string) of your call to the logshare api here, and logpush will keep on making this call for you, setting start and end times appropriately. `"fields=RayID,ClientIP,EdgeStartTimestamp&timestamps=rfc3339"`	max length: 4096

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/logpush/validate/origin" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"logpull_options":"fields=RayID,ClientIP,EdgeStartTimestamp&timestamps=rfc3339"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "valid": true,
    "message": ""
  }
}

logpush-jobs-create-logpush-job

POST Create Logpush Job permission needed: #logs:edit
free
pro
business
enterprise

Create a new Logpush Job for a zone

POST zones/:zone_identifier/logpush/jobs

Required parameters

Name /type	Description /example	Constraints
destination_conf string (uri)	Uniquely identifies a resource (such as an s3 bucket) where data will be pushed. Additional configuration parameters supported by the destination may be included. `"s3://mybucket/logs?region=us-west-2"`	max length: 4096
ownership_challenge string	Ownership challenge token to prove destination ownership. `"00000000000000000000"`	max length: 4096 pattern: ^[a-zA-Z0-9/\+\.\-_]*$

Optional parameters

Name /type	Description /example	Constraints
name string	Human readable job name. Not unique. Makes it easier for humans to identify a job. Suggest that it include the zone name. `"example.com"`	max length: 512 pattern: ^[a-zA-Z0-9\-\.]*$
enabled boolean	`false`	valid values: (true,false)
logpull_options stringnull (uri)	Configuration string for the logshare api. It specifies things like requested fields and timestamp formats. Copy the url (full url or just the query string) of your call to the logshare api here, and logpush will keep on making this call for you, setting start and end times appropriately. `"fields=RayID,ClientIP,EdgeStartTimestamp&timestamps=rfc3339"`	max length: 4096

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/logpush/jobs" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"example.com","enabled":false,"logpull_options":"fields=RayID,ClientIP,EdgeStartTimestamp&timestamps=rfc3339","destination_conf":"s3://mybucket/logs?region=us-west-2","ownership_challenge":"00000000000000000000"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": 1,
    "enabled": false,
    "name": "example.com",
    "logpull_options": "fields=RayID,ClientIP,EdgeStartTimestamp&timestamps=rfc3339",
    "destination_conf": "s3://mybucket/logs?region=us-west-2",
    "last_complete": null,
    "last_error": null,
    "error_message": null
  }
}

logpush-jobs-logpush-job-details

GET Logpush Job Details permission needed: #logs:edit
free
pro
business
enterprise

Get the details of a Logpush Job

GET zones/:zone_identifier/logpush/jobs/:job_identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/logpush/jobs/1" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": 1,
    "enabled": false,
    "name": "example.com",
    "logpull_options": "fields=RayID,ClientIP,EdgeStartTimestamp&timestamps=rfc3339",
    "destination_conf": "s3://mybucket/logs?region=us-west-2",
    "last_complete": null,
    "last_error": null,
    "error_message": null
  }
}

logpush-jobs-update-logpush-job

PUT Update Logpush Job permission needed: #logs:edit
free
pro
business
enterprise

Update a Logpush Job

PUT zones/:zone_identifier/logpush/jobs/:job_identifier

Optional parameters

Name /type	Description /example	Constraints
enabled boolean	`false`	valid values: (true,false)
logpull_options stringnull (uri)	Configuration string for the logshare api. It specifies things like requested fields and timestamp formats. Copy the url (full url or just the query string) of your call to the logshare api here, and logpush will keep on making this call for you, setting start and end times appropriately. `"fields=RayID,ClientIP,EdgeStartTimestamp&timestamps=rfc3339"`	max length: 4096
destination_conf string (uri)	Uniquely identifies a resource (such as an s3 bucket) where data will be pushed. Additional configuration parameters supported by the destination may be included. `"s3://mybucket/logs?region=us-west-2"`	max length: 4096
ownership_challenge string	Ownership challenge token to prove destination ownership. `"00000000000000000000"`	max length: 4096 pattern: ^[a-zA-Z0-9/\+\.\-_]*$

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/logpush/jobs/1" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"enabled":false,"logpull_options":"fields=RayID,ClientIP,EdgeStartTimestamp&timestamps=rfc3339","destination_conf":"s3://mybucket/logs?region=us-west-2","ownership_challenge":"00000000000000000000"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": 1,
    "enabled": false,
    "name": "example.com",
    "logpull_options": "fields=RayID,ClientIP,EdgeStartTimestamp&timestamps=rfc3339",
    "destination_conf": "s3://mybucket/logs?region=us-west-2",
    "last_complete": null,
    "last_error": null,
    "error_message": null
  }
}

logpush-jobs-delete-logpush-job

DELETE Delete Logpush Job permission needed: #logs:edit
free
pro
business
enterprise

Delete a Logpush Job

DELETE zones/:zone_identifier/logpush/jobs/:job_identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/logpush/jobs/1" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {}
}

logpush-jobs-check-destination-exists

POST Check Destination Exists permission needed: #logs:edit
free
pro
business
enterprise

Check if there is an existing job with a destination

POST zones/:zone_identifier/logpush/validate/destination/exists

Required parameters

Name /type	Description /example	Constraints
destination_conf string (uri)	Uniquely identifies a resource (such as an s3 bucket) where data will be pushed. Additional configuration parameters supported by the destination may be included. `"s3://mybucket/logs?region=us-west-2"`	max length: 4096

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/logpush/validate/destination/exists" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"destination_conf":"s3://mybucket/logs?region=us-west-2"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "exists": false
  }
}

DNS Records for a Zone

Documentation for Cloudflare DNS records

dns-records-for-a-zone

Object definitions

View properties and constraints defined on the object

Show definitions

dns-records-for-a-zone-list-dns-records

GET List DNS Records permission needed: #dns_records:read
free
pro
business
enterprise

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, CERT, DNSKEY, DS, NAPTR, SMIMEA, SSHFP, TLSA, URI 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/023e105f4ecef8ad9ca31a8372d0c353/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: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "372e67954025e0ba6aaa6d586b9e0b59",
      "type": "A",
      "name": "example.com",
      "content": "198.51.100.4",
      "proxiable": true,
      "proxied": false,
      "ttl": {},
      "locked": false,
      "zone_id": "023e105f4ecef8ad9ca31a8372d0c353",
      "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
  }
}

dns-records-for-a-zone-create-dns-record

POST Create DNS Record permission needed: #dns_records:edit
free
pro
business
enterprise

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, CERT, DNSKEY, DS, NAPTR, SMIMEA, SSHFP, TLSA, URI 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' `{}` One of the following: Show definition » Show definition »
priority number	Used with some records like MX and SRV to determine priority. If you do not supply a priority for an MX record, a default value of 0 will be set `10`	min value:0 max value:65535
proxied boolean	Whether the record is receiving the performance and security benefits of Cloudflare `false`	valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/dns_records" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"A","name":"example.com","content":"127.0.0.1","ttl":{},"priority":10,"proxied":false}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b59",
    "type": "A",
    "name": "example.com",
    "content": "198.51.100.4",
    "proxiable": true,
    "proxied": false,
    "ttl": {},
    "locked": false,
    "zone_id": "023e105f4ecef8ad9ca31a8372d0c353",
    "zone_name": "example.com",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "data": {}
  }
}

dns-records-for-a-zone-dns-record-details

GET DNS Record Details permission needed: #dns_records:read
free
pro
business
enterprise

GET zones/:zone_identifier/dns_records/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/dns_records/372e67954025e0ba6aaa6d586b9e0b59" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b59",
    "type": "A",
    "name": "example.com",
    "content": "198.51.100.4",
    "proxiable": true,
    "proxied": false,
    "ttl": {},
    "locked": false,
    "zone_id": "023e105f4ecef8ad9ca31a8372d0c353",
    "zone_name": "example.com",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "data": {}
  }
}

dns-records-for-a-zone-update-dns-record

PUT Update DNS Record permission needed: #dns_records:edit
free
pro
business
enterprise

PUT zones/:zone_identifier/dns_records/:identifier

Required parameters

Name /type	Description /example	Constraints
type string	DNS record type `"A"`	valid values: A, AAAA, CNAME, TXT, SRV, LOC, MX, NS, SPF, CERT, DNSKEY, DS, NAPTR, SMIMEA, SSHFP, TLSA, URI 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' `{}` One of the following: Show definition » Show definition »
proxied boolean	Whether the record is receiving the performance and security benefits of Cloudflare `false`	valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/dns_records/372e67954025e0ba6aaa6d586b9e0b59" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"A","name":"example.com","content":"127.0.0.1","ttl":{},"proxied":false}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b59",
    "type": "A",
    "name": "example.com",
    "content": "198.51.100.4",
    "proxiable": true,
    "proxied": false,
    "ttl": {},
    "locked": false,
    "zone_id": "023e105f4ecef8ad9ca31a8372d0c353",
    "zone_name": "example.com",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "data": {}
  }
}

dns-records-for-a-zone-delete-dns-record

DELETE Delete DNS Record permission needed: #dns_records:edit
free
pro
business
enterprise

DELETE zones/:zone_identifier/dns_records/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/dns_records/372e67954025e0ba6aaa6d586b9e0b59" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b59"
  }
}

dns-records-for-a-zone-import-dns-records

POST Import DNS Records permission needed: #dns_records:edit
free
pro
business
enterprise

You can upload your BIND config through this endpoint. It assumes that cURL is called from a location with bind_config.txt (valid BIND config) present.

POST zones/:zone_identifier/dns_records/import

Required parameters

Name /type	Description /example	Constraints
file string	BIND config to upload `"@bind_config.txt"`

Optional parameters

Name /type	Description /example	Constraints
proxied boolean	Whether or not proxiable records should receive the performance and security benefits of Cloudflare `false`	valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/dns_records/import" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     --form "[email protected]_config.txt;proxied=false"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "recs_added": 5,
    "total_records_parsed": 5
  },
  "timing": {
    "start_time": "2014-03-01T12:20:00Z",
    "end_time": "2014-03-01T12:20:01Z",
    "process_time": 1
  }
}

dns-records-for-a-zone-export-dns-records

GET Export DNS Records permission needed: #dns_records:read
free
pro
business
enterprise

You can export your BIND config through this endpoint.

GET zones/:zone_identifier/dns_records/export

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/dns_records/export" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{}

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

DNS Analytics

Analytics data for a zone.

$dns-analytics

Metrics

A metric is a numerical value that is based on an attribute of the data, for example a query count.

In API requests, metrics are set in the metrics parameter. If you need to list multiple metrics, separate them with commas.

Metric	Name	Example	Unit
queryCount	Query count	1000	Count
uncachedCount	Uncached query count	1	Count
staleCount	Stale query count	1	Count
responseTimeAvg	Average response time	1.0	Time in milliseconds.
responseTimeMedian	Median response time	1.0	Time in milliseconds.
responseTime90th	90th percentile response time	1.0	Time in milliseconds.
responseTime99th	99th percentile response time	1.0	Time in milliseconds.

Dimensions

Dimensions can be used to break down the data by given attributes.

In API requests, dimensions are set in the dimensions parameter. If you need to list multiple dimensions, separate them with commas.

Dimension	Name	Example	Notes
queryName	Query Name	`example.com`
queryType	Query Type	`AAAA`	Types defined by IANA, unknown types are empty.
responseCode	Response Code	`NOERROR`	Response codes defined by IANA (always uppercase).
responseCached	Response Cached	`Cached`	Either `Cached` or `Uncached`.
coloName	Colo Name	SJC	PoP code.
origin	Origin	`2001:db8::1`	Origin used to resolve the query (empty if N/A or if the query was answered from cache).
dayOfWeek	Day Of Week	`1`	Break down by day of week, (Monday is 1, and Sunday is 7).
tcp	TCP	`1`	Either `1` or `0` depending on the protocol used.
ipVersion	IP Version	`6`	IP protocol version used (currently `4` or `6`).
querySizeBucket	Query Size Bucket	`16-31`	Query size bucket by multiples of 16.
responseSizeBucket	Response Size Bucket	`16-31`	Response size bucket by multiples of 16.

Filters

A filter uses the form: dimension operator expression

In this syntax:

name — the name of the dimension or metric to filter on. For example: queryName
operator — defines the type of filter match to use. Operators are specific to either dimensions or metrics.
expression — states the values to be included in or excluded from the results. Expressions use regular expression syntax

Filter Operators

Operator	Name	Example	Notes	URL Encoded
`==`	Equals	`queryName==example.com`	Return results where queryName is exactly `example.com`	`%3D%3D`
`!=`	Does not equal	`responseCode!=NOERROR`	Return results where response code is different from `NOERROR`.	`!%3D`
`>`	Greater than	`queryCount>1000`	Return results where query count is higher than `1000`	`%3E`
`<`	Less than	`queryCount<1000`	Return results where query count is lower than `1000`	`%3C`
`>=`	Greater than or equal to	`queryCount>=1000`	Return results where query count is higher than or equal to `1000`	`%3E%3D`
`<=`	Less than or equal to	`queryCount<=1000`	Return results where query count is lower than or equal to `1000`	`%3C%3D`

Combining Filters

Filters can be combined using OR and AND boolean logic. AND takes precedence over OR in all the expressions.

OR

The OR operator is defined using a comma (,) or OR keyword surrounded by whitespace.

Examples:

Response code is either NOERROR or NXDOMAIN: responseCode==NOERROR,responseCode==NXDOMAIN
Queries in either SJC or LAX: coloName==SJC OR coloName==LAX

AND

The AND operator is defined using a semicolon (;) or AND keyword surrounded by whitespace.

Examples:

Response code is NOERROR and query type is AAAA: responseCode==NOERROR;queryType==AAAA
AAAA queries in SJC: queryType==AAAA AND coloName==SJC

dns-analytics-table

GET Table

Retrieves a list of summarised aggregate metrics over a given time period.

GET zones/:identifier/dns_analytics/report

Required parameters

Name /type	Description /example	Constraints
dimensions array	Array of dimensions `[ "responseCode", "queryName" ]` An array with items in the following form: Show definition »
metrics array	Array of metrics `[ "queryCount", "responseTimeAvg" ]` An array with items in the following form: Show definition »
since string (date-time)	Start date and time of requesting data period in the ISO8601 format `"2016-11-11T12:00:00Z"`
until string (date-time)	End date and time of requesting data period in the ISO8601 format `"2016-11-11T13:00:00Z"`

Optional parameters

Name /type	Description /example	Constraints
sort array	Array of dimensions to sort by, each dimension may be prefixed by - (descending) or + (ascending) `[ "+responseCode", "-queryName" ]` An array with items in the following form: Show definition »
filters string	Segmentation filter in 'attribute operator value' format `"responseCode==NOERROR"`
limit integer	Limit number of returned metrics, default is 100 `100`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/dns_analytics/report?dimensions=responseCode,queryName&metrics=queryCount,responseTimeAvg&sort=+responseCode,-queryName&filters=responseCode==NOERROR&since=2016-11-11T12:00:00Z&until=2016-11-11T13:00:00Z&limit=100" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "rows": 100,
    "totals": {
      "queryCount": 1000,
      "responseTimeAvg": 1
    },
    "min": {
      "queryCount": 1000,
      "responseTimeAvg": 1
    },
    "max": {
      "queryCount": 1000,
      "responseTimeAvg": 1
    },
    "data_lag": 60
  }
}

dns-analytics-by-time

GET By Time

Retrieves a list of aggregate metrics grouped by time interval.

GET zones/:identifier/dns_analytics/report/bytime

Optional parameters

Name /type	Description /example	Constraints
dimensions array	Array of dimensions `[ "responseCode", "queryName" ]` An array with items in the following form: Show definition »
metrics array	Array of metrics `[ "queryCount", "responseTimeAvg" ]` An array with items in the following form: Show definition »
sort array	Array of dimensions to sort by, each dimension may be prefixed by - (descending) or + (ascending) `[ "+responseCode", "-queryName" ]` An array with items in the following form: Show definition »
filters string	Segmentation filter in 'attribute operator value' format `"responseCode==NOERROR"`
since string (date-time)	Start date and time of requesting data period in the ISO8601 format `"2016-11-11T12:00:00Z"`
until string (date-time)	End date and time of requesting data period in the ISO8601 format `"2016-11-11T13:00:00Z"`
limit integer	Limit number of returned metrics, default is 100 `100`
time_delta	Unit of time to group data by `"hour"`	valid values: all, auto, year, quarter, month, week, day, hour, dekaminute, minute

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/dns_analytics/report/bytime?dimensions=responseCode,queryName&metrics=queryCount,responseTimeAvg&sort=+responseCode,-queryName&filters=responseCode==NOERROR&since=2016-11-11T12:00:00Z&until=2016-11-11T13:00:00Z&limit=100&time_delta=hour" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "rows": 100,
    "totals": {
      "queryCount": 1000,
      "responseTimeAvg": 1
    },
    "min": {
      "queryCount": 1000,
      "responseTimeAvg": 1
    },
    "max": {
      "queryCount": 1000,
      "responseTimeAvg": 1
    },
    "data_lag": 60
  }
}

DNS Firewall (Users)

User-level DNS Firewall Management

dns-firewall-users-

Object definition

View properties and constraints defined on the object

Show definition

DNS Firewall (Organizations)

Organization-level DNS Firewall Management

dns-firewall-organizations-

Object definition

View properties and constraints defined on the object

Show definition

dns-firewall-organizations--list-dns-firewall-clusters

GET List DNS Firewall Clusters permission needed: #dns_records:read
free
pro
business
enterprise

List configured DNS Firewall clusters for a user

GET organizations/:organization_identifier/virtual_dns

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/virtual_dns" \
     -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": "My Awesome DNS Firewall cluster",
      "origin_ips": [
        "192.0.2.1",
        "198.51.100.1",
        "2001:DB8:100::CF"
      ],
      "virtual_dns_ips": [
        "203.0.113.1",
        "203.0.113.254",
        "2001:DB8:AB::CF",
        "2001:DB8:CD::CF"
      ],
      "minimum_cache_ttl": 60,
      "maximum_cache_ttl": 900,
      "deprecate_any_requests": true,
      "ecs_fallback": false,
      "ratelimit": 600,
      "modified_on": "2014-01-01T05:20:00.12345Z"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

dns-firewall-organizations--create-dns-firewall-cluster

POST Create DNS Firewall Cluster permission needed: #dns_records:edit
free
pro
business
enterprise

Create a configured DNS Firewall Cluster

POST organizations/:organization_identifier/virtual_dns

Required parameters

Name /type	Description /example	Constraints
name string	DNS Firewall Cluster Name `"My Awesome DNS Firewall cluster"`	max length: 160
origin_ips array	`[ "192.0.2.1", "198.51.100.1", "2001:DB8:100::CF" ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
minimum_cache_ttl number	Minimum DNS Cache TTL `60`	default value: 60 min value:30 max value:36000
maximum_cache_ttl number	Maximum DNS Cache TTL `900`	default value: 900 min value:30 max value:36000
deprecate_any_requests boolean	Deprecate the response to ANY requests `true`	valid values: (true,false)
ecs_fallback boolean	Forward client IP (resolver) subnet if no EDNS Client Subnet is sent `false`	valid values: (true,false)
ratelimit number	Ratelimit in queries per second. `600`	min value:100 max value:100000000 notes: A ratelimit of 0 turns off the ratelimit. Otherwise the minimum is 10

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/virtual_dns" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"My Awesome DNS Firewall cluster","origin_ips":["192.0.2.1","198.51.100.1","2001:DB8:100::CF"],"minimum_cache_ttl":60,"maximum_cache_ttl":900,"deprecate_any_requests":true,"ecs_fallback":false,"ratelimit":600}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "name": "My Awesome DNS Firewall cluster",
    "origin_ips": [
      "192.0.2.1",
      "198.51.100.1",
      "2001:DB8:100::CF"
    ],
    "virtual_dns_ips": [
      "203.0.113.1",
      "203.0.113.254",
      "2001:DB8:AB::CF",
      "2001:DB8:CD::CF"
    ],
    "minimum_cache_ttl": 60,
    "maximum_cache_ttl": 900,
    "deprecate_any_requests": true,
    "ecs_fallback": false,
    "ratelimit": 600,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

dns-firewall-organizations--dns-firewall-cluster-details

GET DNS Firewall Cluster Details permission needed: #dns_records:read
free
pro
business
enterprise

List a single configured DNS Firewall clusters for a user

GET organizations/:organization_identifier/virtual_dns/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/virtual_dns/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": "My Awesome DNS Firewall cluster",
    "origin_ips": [
      "192.0.2.1",
      "198.51.100.1",
      "2001:DB8:100::CF"
    ],
    "virtual_dns_ips": [
      "203.0.113.1",
      "203.0.113.254",
      "2001:DB8:AB::CF",
      "2001:DB8:CD::CF"
    ],
    "minimum_cache_ttl": 60,
    "maximum_cache_ttl": 900,
    "deprecate_any_requests": true,
    "ecs_fallback": false,
    "ratelimit": 600,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

dns-firewall-organizations--edit-dns-firewall-cluster

PATCH Edit DNS Firewall Cluster permission needed: #dns_records:edit
free
pro
business
enterprise

Edit a DNS Firewall Cluster configuration

PATCH organizations/:organization_identifier/virtual_dns/:identifier

Optional parameters

Name /type	Description /example	Constraints
name string	DNS Firewall Cluster Name `"My Awesome DNS Firewall cluster"`	max length: 160
origin_ips array	`[ "192.0.2.1", "198.51.100.1", "2001:DB8:100::CF" ]` An array with items in the following form: Show definition »
minimum_cache_ttl number	Minimum DNS Cache TTL `60`	default value: 60 min value:30 max value:36000
maximum_cache_ttl number	Maximum DNS Cache TTL `900`	default value: 900 min value:30 max value:36000
deprecate_any_requests boolean	Deprecate the response to ANY requests `true`	valid values: (true,false)
ecs_fallback boolean	Forward client IP (resolver) subnet if no EDNS Client Subnet is sent `false`	valid values: (true,false)
ratelimit number	Ratelimit in queries per second. `600`	min value:100 max value:100000000 notes: A ratelimit of 0 turns off the ratelimit. Otherwise the minimum is 10

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/virtual_dns/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"My Awesome DNS Firewall cluster","origin_ips":["192.0.2.1","198.51.100.1","2001:DB8:100::CF"],"minimum_cache_ttl":60,"maximum_cache_ttl":900,"deprecate_any_requests":true,"ecs_fallback":false,"ratelimit":600}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "name": "My Awesome DNS Firewall cluster",
    "origin_ips": [
      "192.0.2.1",
      "198.51.100.1",
      "2001:DB8:100::CF"
    ],
    "virtual_dns_ips": [
      "203.0.113.1",
      "203.0.113.254",
      "2001:DB8:AB::CF",
      "2001:DB8:CD::CF"
    ],
    "minimum_cache_ttl": 60,
    "maximum_cache_ttl": 900,
    "deprecate_any_requests": true,
    "ecs_fallback": false,
    "ratelimit": 600,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

dns-firewall-organizations--delete-dns-firewall-cluster

DELETE Delete DNS Firewall Cluster permission needed: #dns_records:edit
free
pro
business
enterprise

Delete a configured DNS Firewall Cluster

DELETE organizations/:organization_identifier/virtual_dns/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/virtual_dns/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"
  }
}

DNS Firewall (Accounts)

Account-level DNS Firewall Management

dns-firewall-accounts-

Object definition

View properties and constraints defined on the object

Show definition

dns-firewall-accounts--list-dns-firewall-clusters

GET List DNS Firewall Clusters permission needed: #dns_records:read
free
pro
business
enterprise

List configured DNS Firewall clusters for an account

GET accounts/:account_identifier/virtual_dns

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/virtual_dns" \
     -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": "My Awesome DNS Firewall cluster",
      "origin_ips": [
        "192.0.2.1",
        "198.51.100.1",
        "2001:DB8:100::CF"
      ],
      "virtual_dns_ips": [
        "203.0.113.1",
        "203.0.113.254",
        "2001:DB8:AB::CF",
        "2001:DB8:CD::CF"
      ],
      "minimum_cache_ttl": 60,
      "maximum_cache_ttl": 900,
      "deprecate_any_requests": true,
      "ecs_fallback": false,
      "ratelimit": 600,
      "modified_on": "2014-01-01T05:20:00.12345Z"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

dns-firewall-accounts--dns-firewall-cluster-details

GET DNS Firewall Cluster Details permission needed: #dns_records:read
free
pro
business
enterprise

List a single configured DNS Firewall clusters for an account

GET accounts/:account_identifier/virtual_dns/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/virtual_dns/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": "My Awesome DNS Firewall cluster",
    "origin_ips": [
      "192.0.2.1",
      "198.51.100.1",
      "2001:DB8:100::CF"
    ],
    "virtual_dns_ips": [
      "203.0.113.1",
      "203.0.113.254",
      "2001:DB8:AB::CF",
      "2001:DB8:CD::CF"
    ],
    "minimum_cache_ttl": 60,
    "maximum_cache_ttl": 900,
    "deprecate_any_requests": true,
    "ecs_fallback": false,
    "ratelimit": 600,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

dns-firewall-accounts--update-dns-firewall-cluster

PUT Update DNS Firewall Cluster permission needed: #dns_records:edit
free
pro
business
enterprise

Modify a DNS Firewall Cluster configuration

PUT accounts/:account_identifier/virtual_dns/:identifier

Optional parameters

Name /type	Description /example	Constraints
virtual_dns_ips array	`[ "203.0.113.1", "203.0.113.254", "2001:DB8:AB::CF", "2001:DB8:CD::CF" ]` An array with items in the following form: Show definition »
deprecate_any_requests boolean	Deprecate the response to ANY requests `true`	valid values: (true,false)
name string	DNS Firewall Cluster Name `"My Awesome DNS Firewall cluster"`	max length: 160
ecs_fallback boolean	Forward client IP (resolver) subnet if no EDNS Client Subnet is sent `false`	valid values: (true,false)
maximum_cache_ttl number	Maximum DNS Cache TTL `900`	default value: 900 min value:30 max value:36000
origin_ips array	`[ "192.0.2.1", "198.51.100.1", "2001:DB8:100::CF" ]` An array with items in the following form: Show definition »
modified_on string (date-time)	Last modification of DNS Firewall cluster `"2014-01-01T05:20:00.12345Z"`	read only
id string	API item identifier tag `"9a7806061c88ada191ed06f989cc3dac"`	max length: 32 read only
ratelimit number	Ratelimit in queries per second. `600`	min value:100 max value:100000000 notes: A ratelimit of 0 turns off the ratelimit. Otherwise the minimum is 10
minimum_cache_ttl number	Minimum DNS Cache TTL `60`	default value: 60 min value:30 max value:36000

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/virtual_dns/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"9a7806061c88ada191ed06f989cc3dac","name":"My Awesome DNS Firewall cluster","origin_ips":["192.0.2.1","198.51.100.1","2001:DB8:100::CF"],"virtual_dns_ips":["203.0.113.1","203.0.113.254","2001:DB8:AB::CF","2001:DB8:CD::CF"],"minimum_cache_ttl":60,"maximum_cache_ttl":900,"deprecate_any_requests":true,"ecs_fallback":false,"ratelimit":600,"modified_on":"2014-01-01T05:20:00.12345Z"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "name": "My Awesome DNS Firewall cluster",
    "origin_ips": [
      "192.0.2.1",
      "198.51.100.1",
      "2001:DB8:100::CF"
    ],
    "virtual_dns_ips": [
      "203.0.113.1",
      "203.0.113.254",
      "2001:DB8:AB::CF",
      "2001:DB8:CD::CF"
    ],
    "minimum_cache_ttl": 60,
    "maximum_cache_ttl": 900,
    "deprecate_any_requests": true,
    "ecs_fallback": false,
    "ratelimit": 600,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

dns-firewall-accounts--delete-dns-firewall-cluster

DELETE Delete DNS Firewall Cluster permission needed: #dns_records:edit
free
pro
business
enterprise

Delete a configured DNS Firewall Cluster

DELETE accounts/:account_identifier/virtual_dns/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/virtual_dns/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"
  }
}

dns-firewall-accounts--create-dns-firewall-cluster

POST Create DNS Firewall Cluster permission needed: #dns_records:edit
free
pro
business
enterprise

Create a configured DNS Firewall Cluster

POST accounts/:account_identifier/virtual_dns

Required parameters

Name /type	Description /example	Constraints
name string	DNS Firewall Cluster Name `"My Awesome DNS Firewall cluster"`	max length: 160
origin_ips array	`[ "192.0.2.1", "198.51.100.1", "2001:DB8:100::CF" ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
minimum_cache_ttl number	Minimum DNS Cache TTL `60`	default value: 60 min value:30 max value:36000
maximum_cache_ttl number	Maximum DNS Cache TTL `900`	default value: 900 min value:30 max value:36000
deprecate_any_requests boolean	Deprecate the response to ANY requests `true`	valid values: (true,false)
ecs_fallback boolean	Forward client IP (resolver) subnet if no EDNS Client Subnet is sent `false`	valid values: (true,false)
ratelimit number	Ratelimit in queries per second. `600`	min value:100 max value:100000000 notes: A ratelimit of 0 turns off the ratelimit. Otherwise the minimum is 10

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/virtual_dns" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"My Awesome DNS Firewall cluster","origin_ips":["192.0.2.1","198.51.100.1","2001:DB8:100::CF"],"minimum_cache_ttl":60,"maximum_cache_ttl":900,"deprecate_any_requests":true,"ecs_fallback":false,"ratelimit":600}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "name": "My Awesome DNS Firewall cluster",
    "origin_ips": [
      "192.0.2.1",
      "198.51.100.1",
      "2001:DB8:100::CF"
    ],
    "virtual_dns_ips": [
      "203.0.113.1",
      "203.0.113.254",
      "2001:DB8:AB::CF",
      "2001:DB8:CD::CF"
    ],
    "minimum_cache_ttl": 60,
    "maximum_cache_ttl": 900,
    "deprecate_any_requests": true,
    "ecs_fallback": false,
    "ratelimit": 600,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

DNS Firewall Analytics (Users)

Analytics data for a DNS Firewall cluster.

dns-firewall-analytics-users-

Object definition

View properties and constraints defined on the object

Show definition

DNS Firewall Analytics (Organizations)

Analytics data for a DNS Firewall cluster.

dns-firewall-analytics-organizations-

Object definition

View properties and constraints defined on the object

Show definition

dns-firewall-analytics-organizations--table

GET Table

Retrieves a list of summarised aggregate metrics over a given time period.

GET organizations/:organization_identifier/virtual_dns/:identifier/dns_analytics/report

Required parameters

Name /type	Description /example	Constraints
dimensions array	Array of dimensions `[ "responseCode", "queryName" ]` An array with items in the following form: Show definition »
metrics array	Array of metrics `[ "queryCount", "responseTimeAvg" ]` An array with items in the following form: Show definition »
since string (date-time)	Start date and time of requesting data period in the ISO8601 format `"2016-11-11T12:00:00Z"`
until string (date-time)	End date and time of requesting data period in the ISO8601 format `"2016-11-11T13:00:00Z"`

Optional parameters

Name /type	Description /example	Constraints
sort array	Array of dimensions to sort by, each dimension may be prefixed by - (descending) or + (ascending) `[ "+responseCode", "-queryName" ]` An array with items in the following form: Show definition »
filters string	Segmentation filter in 'attribute operator value' format `"responseCode==NOERROR"`
limit integer	Limit number of returned metrics, default is 100 `100`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/9a7806061c88ada191ed06f989cc3dac/virtual_dns/9a7806061c88ada191ed06f989cc3dac/dns_analytics/report?dimensions=responseCode,queryName&metrics=queryCount,responseTimeAvg&sort=+responseCode,-queryName&filters=responseCode==NOERROR&since=2016-11-11T12:00:00Z&until=2016-11-11T13:00:00Z&limit=100" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "rows": 100,
    "totals": {
      "queryCount": 1000,
      "responseTimeAvg": 1
    },
    "min": {
      "queryCount": 1000,
      "responseTimeAvg": 1
    },
    "max": {
      "queryCount": 1000,
      "responseTimeAvg": 1
    },
    "data_lag": 60
  }
}

dns-firewall-analytics-organizations--by-time

GET By Time

Retrieves a list of aggregate metrics grouped by time interval.

GET organizations/:organization_identifier/virtual_dns/:identifier/dns_analytics/report/bytime

Optional parameters

Name /type	Description /example	Constraints
dimensions array	Array of dimensions `[ "responseCode", "queryName" ]` An array with items in the following form: Show definition »
metrics array	Array of metrics `[ "queryCount", "responseTimeAvg" ]` An array with items in the following form: Show definition »
sort array	Array of dimensions to sort by, each dimension may be prefixed by - (descending) or + (ascending) `[ "+responseCode", "-queryName" ]` An array with items in the following form: Show definition »
filters string	Segmentation filter in 'attribute operator value' format `"responseCode==NOERROR"`
since string (date-time)	Start date and time of requesting data period in the ISO8601 format `"2016-11-11T12:00:00Z"`
until string (date-time)	End date and time of requesting data period in the ISO8601 format `"2016-11-11T13:00:00Z"`
limit integer	Limit number of returned metrics, default is 100 `100`
time_delta	Unit of time to group data by `"hour"`	valid values: all, auto, year, quarter, month, week, day, hour, dekaminute, minute

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/9a7806061c88ada191ed06f989cc3dac/virtual_dns/9a7806061c88ada191ed06f989cc3dac/dns_analytics/report/bytime?dimensions=responseCode,queryName&metrics=queryCount,responseTimeAvg&sort=+responseCode,-queryName&filters=responseCode==NOERROR&since=2016-11-11T12:00:00Z&until=2016-11-11T13:00:00Z&limit=100&time_delta=hour" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "rows": 100,
    "totals": {
      "queryCount": 1000,
      "responseTimeAvg": 1
    },
    "min": {
      "queryCount": 1000,
      "responseTimeAvg": 1
    },
    "max": {
      "queryCount": 1000,
      "responseTimeAvg": 1
    },
    "data_lag": 60
  }
}

DNS Firewall Analytics (Accounts)

Analytics data for a DNS Firewall cluster.

dns-firewall-analytics-accounts-

Object definition

View properties and constraints defined on the object

Show definition

dns-firewall-analytics-accounts--table

GET Table

Retrieves a list of summarised aggregate metrics over a given time period.

GET accounts/:account_identifier/virtual_dns/:identifier/dns_analytics/report

Required parameters

Name /type	Description /example	Constraints
dimensions array	Array of dimensions `[ "responseCode", "queryName" ]` An array with items in the following form: Show definition »
metrics array	Array of metrics `[ "queryCount", "responseTimeAvg" ]` An array with items in the following form: Show definition »
since string (date-time)	Start date and time of requesting data period in the ISO8601 format `"2016-11-11T12:00:00Z"`
until string (date-time)	End date and time of requesting data period in the ISO8601 format `"2016-11-11T13:00:00Z"`

Optional parameters

Name /type	Description /example	Constraints
sort array	Array of dimensions to sort by, each dimension may be prefixed by - (descending) or + (ascending) `[ "+responseCode", "-queryName" ]` An array with items in the following form: Show definition »
filters string	Segmentation filter in 'attribute operator value' format `"responseCode==NOERROR"`
limit integer	Limit number of returned metrics, default is 100 `100`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/virtual_dns/9a7806061c88ada191ed06f989cc3dac/dns_analytics/report?dimensions=responseCode,queryName&metrics=queryCount,responseTimeAvg&sort=+responseCode,-queryName&filters=responseCode==NOERROR&since=2016-11-11T12:00:00Z&until=2016-11-11T13:00:00Z&limit=100" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "rows": 100,
    "totals": {
      "queryCount": 1000,
      "responseTimeAvg": 1
    },
    "min": {
      "queryCount": 1000,
      "responseTimeAvg": 1
    },
    "max": {
      "queryCount": 1000,
      "responseTimeAvg": 1
    },
    "data_lag": 60
  }
}

dns-firewall-analytics-accounts--by-time

GET By Time

Retrieves a list of aggregate metrics grouped by time interval.

GET accounts/:account_identifier/virtual_dns/:identifier/dns_analytics/report/bytime

Optional parameters

Name /type	Description /example	Constraints
dimensions array	Array of dimensions `[ "responseCode", "queryName" ]` An array with items in the following form: Show definition »
metrics array	Array of metrics `[ "queryCount", "responseTimeAvg" ]` An array with items in the following form: Show definition »
sort array	Array of dimensions to sort by, each dimension may be prefixed by - (descending) or + (ascending) `[ "+responseCode", "-queryName" ]` An array with items in the following form: Show definition »
filters string	Segmentation filter in 'attribute operator value' format `"responseCode==NOERROR"`
since string (date-time)	Start date and time of requesting data period in the ISO8601 format `"2016-11-11T12:00:00Z"`
until string (date-time)	End date and time of requesting data period in the ISO8601 format `"2016-11-11T13:00:00Z"`
limit integer	Limit number of returned metrics, default is 100 `100`
time_delta	Unit of time to group data by `"hour"`	valid values: all, auto, year, quarter, month, week, day, hour, dekaminute, minute

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/virtual_dns/9a7806061c88ada191ed06f989cc3dac/dns_analytics/report/bytime?dimensions=responseCode,queryName&metrics=queryCount,responseTimeAvg&sort=+responseCode,-queryName&filters=responseCode==NOERROR&since=2016-11-11T12:00:00Z&until=2016-11-11T13:00:00Z&limit=100&time_delta=hour" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "rows": 100,
    "totals": {
      "queryCount": 1000,
      "responseTimeAvg": 1
    },
    "min": {
      "queryCount": 1000,
      "responseTimeAvg": 1
    },
    "max": {
      "queryCount": 1000,
      "responseTimeAvg": 1
    },
    "data_lag": 60
  }
}

Secondary DNS

Secondary DNS Zone

secondary-dns

Object definition

View properties and constraints defined on the object

Show definition

secondary-dns-secondary-zone-configuration-details

GET Secondary Zone Configuration Details
free
pro
business
enterprise

Get secondary zone configuration

GET zones/:identifier/secondary_dns

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/269d8f4853475ca241c4e730be286b20/secondary_dns" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "269d8f4853475ca241c4e730be286b20",
    "name": "www.example.com.",
    "masters": [
      "23ff594956f20c2a721606e94745a8aa",
      "00920f38ce07c2e2f4df50b1f61d4194"
    ],
    "auto_refresh_seconds": 30
  }
}

secondary-dns-update-secondary-zone-configuration

PUT Update Secondary Zone Configuration
free
pro
business
enterprise

Update secondary zone configuration

PUT zones/:identifier/secondary_dns

Required parameters

Name /type	Description /example	Constraints
id string	API item identifier tag `"269d8f4853475ca241c4e730be286b20"`	max length: 32 read only
name string	zone name `"www.example.com."`
masters array	A list of master tags `[ "23ff594956f20c2a721606e94745a8aa", "00920f38ce07c2e2f4df50b1f61d4194" ]`
auto_refresh_seconds number	How often should it auto refresh `30`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/269d8f4853475ca241c4e730be286b20/secondary_dns" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"269d8f4853475ca241c4e730be286b20","name":"www.example.com.","masters":["23ff594956f20c2a721606e94745a8aa","00920f38ce07c2e2f4df50b1f61d4194"],"auto_refresh_seconds":30}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "269d8f4853475ca241c4e730be286b20",
    "name": "www.example.com.",
    "masters": [
      "23ff594956f20c2a721606e94745a8aa",
      "00920f38ce07c2e2f4df50b1f61d4194"
    ],
    "auto_refresh_seconds": 30
  }
}

secondary-dns-delete-secondary-zone-configuration

DELETE Delete Secondary Zone Configuration
free
pro
business
enterprise

Delete secondary zone configuration

DELETE zones/:identifier/secondary_dns

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/269d8f4853475ca241c4e730be286b20/secondary_dns" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "269d8f4853475ca241c4e730be286b20"
  }
}

secondary-dns-create-secondary-zone-configuration

POST Create Secondary Zone Configuration
free
pro
business
enterprise

Create secondary zone configuration

POST zones/:identifier/secondary_dns

Required parameters

Name /type	Description /example	Constraints
id string	API item identifier tag `"269d8f4853475ca241c4e730be286b20"`	max length: 32 read only
name string	zone name `"www.example.com."`
masters array	A list of master tags `[ "23ff594956f20c2a721606e94745a8aa", "00920f38ce07c2e2f4df50b1f61d4194" ]`
auto_refresh_seconds number	How often should it auto refresh `30`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/269d8f4853475ca241c4e730be286b20/secondary_dns" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"269d8f4853475ca241c4e730be286b20","name":"www.example.com.","masters":["23ff594956f20c2a721606e94745a8aa","00920f38ce07c2e2f4df50b1f61d4194"],"auto_refresh_seconds":30}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "269d8f4853475ca241c4e730be286b20",
    "name": "www.example.com.",
    "masters": [
      "23ff594956f20c2a721606e94745a8aa",
      "00920f38ce07c2e2f4df50b1f61d4194"
    ],
    "auto_refresh_seconds": 30
  }
}

Secondary DNS (TSIG)

TSIG key management for secondary DNS

secondary-dns-tsig-

Object definition

View properties and constraints defined on the object

Show definition

secondary-dns-tsig--list-tsigs

GET List TSIGs
free
pro
business
enterprise

List TSIGs

GET accounts/:account_identifier/secondary_dns/tsigs

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/secondary_dns/tsigs" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "69cd1e104af3e6ed3cb344f263fd0d5a",
      "name": "tsig.customer.cf.",
      "secret": "caf79a7804b04337c9c66ccd7bef9190a1e1679b5dd03d8aa10f7ad45e1a9dab92b417896c15d4d007c7c14194538d2a5d0feffdecc5a7f0e1c570cfa700837c",
      "algo": "hmac-sha512."
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

secondary-dns-tsig--tsig-details

GET TSIG Details
free
pro
business
enterprise

Get TSIG

GET accounts/:account_identifier/secondary_dns/tsigs/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/secondary_dns/tsigs/69cd1e104af3e6ed3cb344f263fd0d5a" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "69cd1e104af3e6ed3cb344f263fd0d5a",
    "name": "tsig.customer.cf.",
    "secret": "caf79a7804b04337c9c66ccd7bef9190a1e1679b5dd03d8aa10f7ad45e1a9dab92b417896c15d4d007c7c14194538d2a5d0feffdecc5a7f0e1c570cfa700837c",
    "algo": "hmac-sha512."
  }
}

secondary-dns-tsig--update-tsig

PUT Update TSIG
free
pro
business
enterprise

Modify TSIG

PUT accounts/:account_identifier/secondary_dns/tsigs/:identifier

Required parameters

Name /type	Description /example	Constraints
id string	API item identifier tag `"69cd1e104af3e6ed3cb344f263fd0d5a"`	max length: 32 read only
name string	TSIG key name `"tsig.customer.cf."`
secret string	TSIG secret `"caf79a7804b04337c9c66ccd7bef9190a1e1679b5dd03d8aa10f7ad45e1a9dab92b417896c15d4d007c7c14194538d2a5d0feffdecc5a7f0e1c570cfa700837c"`
algo string	TSIG algorithm `"hmac-sha512."`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/secondary_dns/tsigs/69cd1e104af3e6ed3cb344f263fd0d5a" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"69cd1e104af3e6ed3cb344f263fd0d5a","name":"tsig.customer.cf.","secret":"caf79a7804b04337c9c66ccd7bef9190a1e1679b5dd03d8aa10f7ad45e1a9dab92b417896c15d4d007c7c14194538d2a5d0feffdecc5a7f0e1c570cfa700837c","algo":"hmac-sha512."}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "69cd1e104af3e6ed3cb344f263fd0d5a",
    "name": "tsig.customer.cf.",
    "secret": "caf79a7804b04337c9c66ccd7bef9190a1e1679b5dd03d8aa10f7ad45e1a9dab92b417896c15d4d007c7c14194538d2a5d0feffdecc5a7f0e1c570cfa700837c",
    "algo": "hmac-sha512."
  }
}

secondary-dns-tsig--delete-tsig

DELETE Delete TSIG
free
pro
business
enterprise

Delete TSIG

DELETE accounts/:account_identifier/secondary_dns/tsigs/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/secondary_dns/tsigs/69cd1e104af3e6ed3cb344f263fd0d5a" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "69cd1e104af3e6ed3cb344f263fd0d5a"
  }
}

secondary-dns-tsig--create-tsig

POST Create TSIG
free
pro
business
enterprise

Create TSIG

POST accounts/:account_identifier/secondary_dns/tsigs

Required parameters

Name /type	Description /example	Constraints
name string	TSIG key name `"tsig.customer.cf."`
secret string	TSIG secret `"caf79a7804b04337c9c66ccd7bef9190a1e1679b5dd03d8aa10f7ad45e1a9dab92b417896c15d4d007c7c14194538d2a5d0feffdecc5a7f0e1c570cfa700837c"`
algo string	TSIG algorithm `"hmac-sha512."`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/secondary_dns/tsigs" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"tsig.customer.cf.","secret":"caf79a7804b04337c9c66ccd7bef9190a1e1679b5dd03d8aa10f7ad45e1a9dab92b417896c15d4d007c7c14194538d2a5d0feffdecc5a7f0e1c570cfa700837c","algo":"hmac-sha512."}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "69cd1e104af3e6ed3cb344f263fd0d5a",
    "name": "tsig.customer.cf.",
    "secret": "caf79a7804b04337c9c66ccd7bef9190a1e1679b5dd03d8aa10f7ad45e1a9dab92b417896c15d4d007c7c14194538d2a5d0feffdecc5a7f0e1c570cfa700837c",
    "algo": "hmac-sha512."
  }
}

Secondary DNS (Master)

Master nameservers for secondary DNS

secondary-dns-master-

Object definition

View properties and constraints defined on the object

Show definition

secondary-dns-master--list-masters

GET List Masters
free
pro
business
enterprise

List Masters

GET accounts/:account_identifier/secondary_dns/masters

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/secondary_dns/masters" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "23ff594956f20c2a721606e94745a8aa",
      "ip": "192.0.2.53",
      "port": 53,
      "ixfr_enable": false,
      "tsig_id": "69cd1e104af3e6ed3cb344f263fd0d5a"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

secondary-dns-master--master-details

GET Master Details
free
pro
business
enterprise

Get Master

GET accounts/:account_identifier/secondary_dns/masters/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/secondary_dns/masters/23ff594956f20c2a721606e94745a8aa" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "23ff594956f20c2a721606e94745a8aa",
    "ip": "192.0.2.53",
    "port": 53,
    "ixfr_enable": false,
    "tsig_id": "69cd1e104af3e6ed3cb344f263fd0d5a"
  }
}

secondary-dns-master--update-master

PUT Update Master
free
pro
business
enterprise

Modify Master

PUT accounts/:account_identifier/secondary_dns/masters/:identifier

Required parameters

Name /type	Description /example	Constraints
id string	API item identifier tag `"23ff594956f20c2a721606e94745a8aa"`	max length: 32 read only
ip string	IPv4/IPv6 address of master nameserver `"192.0.2.53"`
port number	DNS port of master nameserver `53`

Optional parameters

Name /type	Description /example	Constraints
ixfr_enable boolean	Enable IXFR transfer protocol, default is AXFR `false`	valid values: (true,false)
tsig_id string	TSIG authentication will be used for zone transfer if configured `"69cd1e104af3e6ed3cb344f263fd0d5a"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/secondary_dns/masters/23ff594956f20c2a721606e94745a8aa" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"23ff594956f20c2a721606e94745a8aa","ip":"192.0.2.53","port":53,"ixfr_enable":false,"tsig_id":"69cd1e104af3e6ed3cb344f263fd0d5a"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "23ff594956f20c2a721606e94745a8aa",
    "ip": "192.0.2.53",
    "port": 53,
    "ixfr_enable": false,
    "tsig_id": "69cd1e104af3e6ed3cb344f263fd0d5a"
  }
}

secondary-dns-master--delete-master

DELETE Delete Master
free
pro
business
enterprise

Delete Master

DELETE accounts/:account_identifier/secondary_dns/masters/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/secondary_dns/masters/23ff594956f20c2a721606e94745a8aa" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "23ff594956f20c2a721606e94745a8aa"
  }
}

secondary-dns-master--create-master

POST Create Master
free
pro
business
enterprise

Create Master

POST accounts/:account_identifier/secondary_dns/masters

Required parameters

Name /type	Description /example	Constraints
ip string	IPv4/IPv6 address of master nameserver `"192.0.2.53"`
port number	DNS port of master nameserver `53`

Optional parameters

Name /type	Description /example	Constraints
ixfr_enable boolean	Enable IXFR transfer protocol, default is AXFR `false`	valid values: (true,false)
tsig_id string	TSIG authentication will be used for zone transfer if configured `"69cd1e104af3e6ed3cb344f263fd0d5a"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/secondary_dns/masters" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"ip":"192.0.2.53","port":53,"ixfr_enable":false,"tsig_id":"69cd1e104af3e6ed3cb344f263fd0d5a"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "23ff594956f20c2a721606e94745a8aa",
    "ip": "192.0.2.53",
    "port": 53,
    "ixfr_enable": false,
    "tsig_id": "69cd1e104af3e6ed3cb344f263fd0d5a"
  }
}

Cloudflare IPs

Cloudflare IP space

cloudflare-ips

Object definition

View properties and constraints defined on the object

Show definition

cloudflare-ips-cloudflare-ip-details

GET Cloudflare IP Details

Get Cloudflare IPs

GET ips

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/ips"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "ipv4_cidrs": [
      "199.27.128.0/21"
    ],
    "ipv6_cidrs": [
      "2400:cb00::/32"
    ]
  }
}

Custom Pages for a Zone

Custom pages associated with a zone

custom-pages-for-a-zone

Object definitions

View properties and constraints defined on the object

Show definitions

custom-pages-for-a-zone-list-available-custom-pages

GET List Available Custom Pages permission needed: #zone_settings:read
free
pro
business
enterprise

A list of available Custom Pages the zone can use

GET zones/:zone_identifier/custom_pages

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_pages" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "basic_challenge",
      "created_on": "2014-01-01T05:20:00.12345Z",
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "url": "http://www.example.com",
      "state": "default",
      "required_tokens": [
        "::CAPTCHA_BOX::"
      ],
      "preview_target": "preview:target",
      "description": true
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

custom-pages-for-a-zone-custom-page-details

GET Custom Page Details permission needed: #zone_settings:read
free
pro
business
enterprise

Details about a specific Custom page details

GET zones/:zone_identifier/custom_pages/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_pages/basic_challenge" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "basic_challenge",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "url": "http://www.example.com",
    "state": "default",
    "required_tokens": [
      "::CAPTCHA_BOX::"
    ],
    "preview_target": "preview:target",
    "description": true
  }
}

custom-pages-for-a-zone-update-custom-page-url

PUT Update Custom Page URL permission needed: #zone_settings:edit
free
pro
business
enterprise

Update custom page URL

PUT zones/:zone_identifier/custom_pages/:identifier

Required parameters

Name /type	Description /example	Constraints
url string (url)	A URL that is associated with the Custom Page. `"http://www.example.com"`	default value:
state string	The Custom Page state `"default"`	valid values: default, customized

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_pages/basic_challenge" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"url":"http://www.example.com","state":"default"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "basic_challenge",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "url": "http://www.example.com",
    "state": "default",
    "required_tokens": [
      "::CAPTCHA_BOX::"
    ],
    "preview_target": "preview:target",
    "description": true
  }
}

Custom Pages for a Zone error codes

Code	Description
1000	Invalid user
1001	Invalid request. Could not connect to database
1002	Validator dispatcher expects an array
1004	Cannot find a valid zone
1006	Cannot find a valid customization page
1007	Invalid validation method being called
1200	A URL is required
1201	The URL provided seems to be irregular
1202	Unable to grab the content for the URL provided. Please try again.
1203	Your custom page must be larger than <characters> characters
1204	Your custom page must be smaller than <characters> characters
1205	A <token> token was not detected on the error page, and must be added before this page can be integrated into Cloudflare. The default error page will show until this is corrected and rescanned.
1206	Could not find a valid zone
1207	That customization page is not modifiable
1208	An unknown error has occurred and has been logged. We will fix this problem promptly. We apologize for the inconvenience.
1209	Could not find a valid customization page for this operation
1210	That operation is no longer allowed for that domain.
1211	Could not find a valid customization page to disable
1212	An undocumented error has occurred and has been logged.
1213	That operation has already been performed for this challenge/error.
1214	Rate limit reached for this operation. Please try again in a minute
1215	Rate limit reached for this operation. Please try again in a minute
1217	Invalid state passed
1218	Missing Custom Page state
1219	Please upgrade to access this feature
1220	We were unable to scan the page provided. Please ensure it is accessible publicly and is larger than 100 characters

Custom SSL for a Zone

Custom SSL certificate for a zone

custom-ssl-for-a-zone

Object definition

View properties and constraints defined on the object

Show definition

custom-ssl-for-a-zone-list-ssl-configurations

GET List SSL Configurations permission needed: #ssl:read
free
pro
business
enterprise

List, search, and filter all of your custom SSL certificates. The priority fields deteremines the order in which the certificate will be used in a request. Higher numbers will be tried first.

GET zones/:zone_identifier/custom_certificates

Optional parameters

Name /type	Description /example	Constraints
status	Status of the zone's custom SSL `"active"`	valid values: active, expired, deleted, pending, initializing 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
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/023e105f4ecef8ad9ca31a8372d0c353/custom_certificates?status=active&page=1&per_page=20&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": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
      "hosts": [
        "example.com"
      ],
      "issuer": "GlobalSign",
      "signature": "SHA256WithRSA",
      "status": "active",
      "bundle_method": "ubiquitous",
      "geo_restrictions": {
        "label": "us"
      },
      "zone_id": "023e105f4ecef8ad9ca31a8372d0c353",
      "uploaded_on": "2014-01-01T05:20:00Z",
      "modified_on": "2014-01-01T05:20:00Z",
      "expires_on": "2016-01-01T05:20:00Z",
      "priority": 1
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

custom-ssl-for-a-zone-create-ssl-configuration

POST Create SSL Configuration permission needed: #ssl:edit
free
pro
business
enterprise

Upload a new SSL certificate for a zone

POST zones/:zone_identifier/custom_certificates

Required parameters

Name /type	Description /example	Constraints
certificate string	The zone's SSL certificate or certificate and the intermediate(s) "-----BEGIN CERTIFICATE-----\nMIIDtTCCAp2gAwIBAgIJAMHAwfXZ5/PWMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV\nBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX\naWRnaXRzIFB0eSBMdGQwHhcNMTYwODI0MTY0MzAxWhcNMTYxMTIyMTY0MzAxWjBF\nMQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50\nZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\nCgKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmGdtcGbg/1\nCGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKnabIRuGvB\nKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpidtnKX/a+5\n0GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+pyFxIXjbEI\ndZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pEewooaeO2\nizNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABo4GnMIGkMB0GA1UdDgQWBBT/LbE4\n9rWf288N6sJA5BRb6FJIGDB1BgNVHSMEbjBsgBT/LbE49rWf288N6sJA5BRb6FJI\nGKFJpEcwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNV\nBAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZIIJAMHAwfXZ5/PWMAwGA1UdEwQF\nMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAHHFwl0tH0quUYZYO0dZYt4R7SJ0pCm2\n2satiyzHl4OnXcHDpekAo7/a09c6Lz6AU83cKy/+x3/djYHXWba7HpEu0dR3ugQP\nMlr4zrhd9xKZ0KZKiYmtJH+ak4OM4L3FbT0owUZPyjLSlhMtJVcoRp5CJsjAMBUG\nSvD8RX+T01wzox/Qb+lnnNnOlaWpqu8eoOenybxKp1a9ULzIVvN/LAcc+14vioFq\n2swRWtmocBAs8QR9n4uvbpiYvS8eYueDCWMM4fvFfBhaDZ3N9IbtySh3SpFdQDhw\nYbjM2rxXiyLGxB4Bol7QTv4zHif7Zt89FReT/NBy4rzaskDJY5L6xmY=\n-----END CERTIFICATE-----\n"
private_key string	The zone's private key "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmG\ndtcGbg/1CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKn\nabIRuGvBKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpid\ntnKX/a+50GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+py\nFxIXjbEIdZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pE\newooaeO2izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABAoIBACbhTYXBZYKmYPCb\nHBR1IBlCQA2nLGf0qRuJNJZg5iEzXows/6tc8YymZkQE7nolapWsQ+upk2y5Xdp/\naxiuprIs9JzkYK8Ox0r+dlwCG1kSW+UAbX0bQ/qUqlsTvU6muVuMP8vZYHxJ3wmb\n+ufRBKztPTQ/rYWaYQcgC0RWI20HTFBMxlTAyNxYNWzX7RKFkGVVyB9RsAtmcc8g\n+j4OdosbfNoJPS0HeIfNpAznDfHKdxDk2Yc1tV6RHBrC1ynyLE9+TaflIAdo2MVv\nKLMLq51GqYKtgJFIlBRPQqKoyXdz3fGvXrTkf/WY9QNq0J1Vk5ERePZ54mN8iZB7\n9lwy/AkCgYEA6FXzosxswaJ2wQLeoYc7ceaweX/SwTvxHgXzRyJIIT0eJWgx13Wo\n/WA3Iziimsjf6qE+SI/8laxPp2A86VMaIt3Z3mJN/CqSVGw8LK2AQst+OwdPyDMu\niacE8lj/IFGC8mwNUAb9CzGU3JpU4PxxGFjS/eMtGeRXCWkK4NE+G08CgYEA1Kp9\nN2JrVlqUz+gAX+LPmE9OEMAS9WQSQsfCHGogIFDGGcNf7+uwBM7GAaSJIP01zcoe\nVAgWdzXCv3FLhsaZoJ6RyLOLay5phbu1iaTr4UNYm5WtYTzMzqh8l1+MFFDl9xDB\nvULuCIIrglM5MeS/qnSg1uMoH2oVPj9TVst/ir8CgYEAxrI7Ws9Zc4Bt70N1As+U\nlySjaEVZCMkqvHJ6TCuVZFfQoE0r0whdLdRLU2PsLFP+q7qaeZQqgBaNSKeVcDYR\n9B+nY/jOmQoPewPVsp/vQTCnE/R81spu0mp0YI6cIheT1Z9zAy322svcc43JaWB7\nmEbeqyLOP4Z4qSOcmghZBSECgYACvR9Xs0DGn+wCsW4vze/2ei77MD4OQvepPIFX\ndFZtlBy5ADcgE9z0cuVB6CiL8DbdK5kwY9pGNr8HUCI03iHkW6Zs+0L0YmihfEVe\nPG19PSzK9CaDdhD9KFZSbLyVFmWfxOt50H7YRTTiPMgjyFpfi5j2q348yVT0tEQS\nfhRqaQKBgAcWPokmJ7EbYQGeMbS7HC8eWO/RyamlnSffdCdSc7ue3zdVJxpAkQ8W\nqu80pEIF6raIQfAf8MXiiZ7auFOSnHQTXUbhCpvDLKi0Mwq3G8Pl07l+2s6dQG6T\nlv6XTQaMyf6n1yjzL+fzDrH3qXMxHMO/b13EePXpDMpY7HQpoLDi\n-----END RSA PRIVATE KEY-----\n"

Optional parameters

Name /type	Description /example	Constraints
bundle_method string	A ubiquitous bundle has the highest probability of being verified everywhere, even by clients using outdated or unusual trust stores. An optimal bundle uses the shortest chain and newest intermediates. And the force bundle verifies the chain, but does not otherwise modify it. `"ubiquitous"`	default value: ubiquitous valid values: ubiquitous, optimal, force
geo_restrictions object	Specify the region where your private key can be held locally for optimal TLS performance. HTTPS connections to any excluded data center will still be fully encrypted, but will incur some latency while Keyless SSL is used to complete the handshake with the nearest allowed data center. Options allow distribution to only to U.S. data centers, only to E.U. data centers, or only to highest security data centers. Default distribution is to all Cloudflare datacenters, for optimal performance. `{ "label": "us" }` An object with the following properties: Show definition »
type string	The type 'legacy_custom' enables support for legacy clients which do not include SNI in the TLS handshake. `"sni_custom"`	default value: legacy_custom valid values: legacy_custom, sni_custom

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_certificates" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"certificate":"-----BEGIN CERTIFICATE-----\nMIIDtTCCAp2gAwIBAgIJAMHAwfXZ5/PWMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV\nBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX\naWRnaXRzIFB0eSBMdGQwHhcNMTYwODI0MTY0MzAxWhcNMTYxMTIyMTY0MzAxWjBF\nMQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50\nZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\nCgKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmGdtcGbg/1\nCGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKnabIRuGvB\nKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpidtnKX/a+5\n0GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+pyFxIXjbEI\ndZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pEewooaeO2\nizNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABo4GnMIGkMB0GA1UdDgQWBBT/LbE4\n9rWf288N6sJA5BRb6FJIGDB1BgNVHSMEbjBsgBT/LbE49rWf288N6sJA5BRb6FJI\nGKFJpEcwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNV\nBAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZIIJAMHAwfXZ5/PWMAwGA1UdEwQF\nMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAHHFwl0tH0quUYZYO0dZYt4R7SJ0pCm2\n2satiyzHl4OnXcHDpekAo7/a09c6Lz6AU83cKy/+x3/djYHXWba7HpEu0dR3ugQP\nMlr4zrhd9xKZ0KZKiYmtJH+ak4OM4L3FbT0owUZPyjLSlhMtJVcoRp5CJsjAMBUG\nSvD8RX+T01wzox/Qb+lnnNnOlaWpqu8eoOenybxKp1a9ULzIVvN/LAcc+14vioFq\n2swRWtmocBAs8QR9n4uvbpiYvS8eYueDCWMM4fvFfBhaDZ3N9IbtySh3SpFdQDhw\nYbjM2rxXiyLGxB4Bol7QTv4zHif7Zt89FReT/NBy4rzaskDJY5L6xmY=\n-----END CERTIFICATE-----\n","private_key":"-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmG\ndtcGbg/1CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKn\nabIRuGvBKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpid\ntnKX/a+50GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+py\nFxIXjbEIdZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pE\newooaeO2izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABAoIBACbhTYXBZYKmYPCb\nHBR1IBlCQA2nLGf0qRuJNJZg5iEzXows/6tc8YymZkQE7nolapWsQ+upk2y5Xdp/\naxiuprIs9JzkYK8Ox0r+dlwCG1kSW+UAbX0bQ/qUqlsTvU6muVuMP8vZYHxJ3wmb\n+ufRBKztPTQ/rYWaYQcgC0RWI20HTFBMxlTAyNxYNWzX7RKFkGVVyB9RsAtmcc8g\n+j4OdosbfNoJPS0HeIfNpAznDfHKdxDk2Yc1tV6RHBrC1ynyLE9+TaflIAdo2MVv\nKLMLq51GqYKtgJFIlBRPQqKoyXdz3fGvXrTkf/WY9QNq0J1Vk5ERePZ54mN8iZB7\n9lwy/AkCgYEA6FXzosxswaJ2wQLeoYc7ceaweX/SwTvxHgXzRyJIIT0eJWgx13Wo\n/WA3Iziimsjf6qE+SI/8laxPp2A86VMaIt3Z3mJN/CqSVGw8LK2AQst+OwdPyDMu\niacE8lj/IFGC8mwNUAb9CzGU3JpU4PxxGFjS/eMtGeRXCWkK4NE+G08CgYEA1Kp9\nN2JrVlqUz+gAX+LPmE9OEMAS9WQSQsfCHGogIFDGGcNf7+uwBM7GAaSJIP01zcoe\nVAgWdzXCv3FLhsaZoJ6RyLOLay5phbu1iaTr4UNYm5WtYTzMzqh8l1+MFFDl9xDB\nvULuCIIrglM5MeS/qnSg1uMoH2oVPj9TVst/ir8CgYEAxrI7Ws9Zc4Bt70N1As+U\nlySjaEVZCMkqvHJ6TCuVZFfQoE0r0whdLdRLU2PsLFP+q7qaeZQqgBaNSKeVcDYR\n9B+nY/jOmQoPewPVsp/vQTCnE/R81spu0mp0YI6cIheT1Z9zAy322svcc43JaWB7\nmEbeqyLOP4Z4qSOcmghZBSECgYACvR9Xs0DGn+wCsW4vze/2ei77MD4OQvepPIFX\ndFZtlBy5ADcgE9z0cuVB6CiL8DbdK5kwY9pGNr8HUCI03iHkW6Zs+0L0YmihfEVe\nPG19PSzK9CaDdhD9KFZSbLyVFmWfxOt50H7YRTTiPMgjyFpfi5j2q348yVT0tEQS\nfhRqaQKBgAcWPokmJ7EbYQGeMbS7HC8eWO/RyamlnSffdCdSc7ue3zdVJxpAkQ8W\nqu80pEIF6raIQfAf8MXiiZ7auFOSnHQTXUbhCpvDLKi0Mwq3G8Pl07l+2s6dQG6T\nlv6XTQaMyf6n1yjzL+fzDrH3qXMxHMO/b13EePXpDMpY7HQpoLDi\n-----END RSA PRIVATE KEY-----\n","bundle_method":"ubiquitous","geo_restrictions":{"label":"us"},"type":"sni_custom"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
    "hosts": [
      "example.com"
    ],
    "issuer": "GlobalSign",
    "signature": "SHA256WithRSA",
    "status": "active",
    "bundle_method": "ubiquitous",
    "geo_restrictions": {
      "label": "us"
    },
    "zone_id": "023e105f4ecef8ad9ca31a8372d0c353",
    "uploaded_on": "2014-01-01T05:20:00Z",
    "modified_on": "2014-01-01T05:20:00Z",
    "expires_on": "2016-01-01T05:20:00Z",
    "priority": 1
  }
}

custom-ssl-for-a-zone-ssl-configuration-details

GET SSL Configuration Details permission needed: #ssl:read
free
pro
business
enterprise

GET zones/:zone_identifier/custom_certificates/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_certificates/2458ce5a-0c35-4c7f-82c7-8e9487d3ff60" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
    "hosts": [
      "example.com"
    ],
    "issuer": "GlobalSign",
    "signature": "SHA256WithRSA",
    "status": "active",
    "bundle_method": "ubiquitous",
    "geo_restrictions": {
      "label": "us"
    },
    "zone_id": "023e105f4ecef8ad9ca31a8372d0c353",
    "uploaded_on": "2014-01-01T05:20:00Z",
    "modified_on": "2014-01-01T05:20:00Z",
    "expires_on": "2016-01-01T05:20:00Z",
    "priority": 1
  }
}

custom-ssl-for-a-zone-edit-ssl-configuration

PATCH Edit SSL Configuration permission needed: #ssl:edit
free
pro
business
enterprise

Upload a new private key and/or PEM/CRT for the SSL certificate. Note: PATCHing a configuration for sni_custom certificates will result in a new resource id being returned, and the previous one being deleted.

PATCH zones/:zone_identifier/custom_certificates/:identifier

Optional parameters

Name /type	Description /example	Constraints
private_key string	The zone's private key "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmG\ndtcGbg/1CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKn\nabIRuGvBKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpid\ntnKX/a+50GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+py\nFxIXjbEIdZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pE\newooaeO2izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABAoIBACbhTYXBZYKmYPCb\nHBR1IBlCQA2nLGf0qRuJNJZg5iEzXows/6tc8YymZkQE7nolapWsQ+upk2y5Xdp/\naxiuprIs9JzkYK8Ox0r+dlwCG1kSW+UAbX0bQ/qUqlsTvU6muVuMP8vZYHxJ3wmb\n+ufRBKztPTQ/rYWaYQcgC0RWI20HTFBMxlTAyNxYNWzX7RKFkGVVyB9RsAtmcc8g\n+j4OdosbfNoJPS0HeIfNpAznDfHKdxDk2Yc1tV6RHBrC1ynyLE9+TaflIAdo2MVv\nKLMLq51GqYKtgJFIlBRPQqKoyXdz3fGvXrTkf/WY9QNq0J1Vk5ERePZ54mN8iZB7\n9lwy/AkCgYEA6FXzosxswaJ2wQLeoYc7ceaweX/SwTvxHgXzRyJIIT0eJWgx13Wo\n/WA3Iziimsjf6qE+SI/8laxPp2A86VMaIt3Z3mJN/CqSVGw8LK2AQst+OwdPyDMu\niacE8lj/IFGC8mwNUAb9CzGU3JpU4PxxGFjS/eMtGeRXCWkK4NE+G08CgYEA1Kp9\nN2JrVlqUz+gAX+LPmE9OEMAS9WQSQsfCHGogIFDGGcNf7+uwBM7GAaSJIP01zcoe\nVAgWdzXCv3FLhsaZoJ6RyLOLay5phbu1iaTr4UNYm5WtYTzMzqh8l1+MFFDl9xDB\nvULuCIIrglM5MeS/qnSg1uMoH2oVPj9TVst/ir8CgYEAxrI7Ws9Zc4Bt70N1As+U\nlySjaEVZCMkqvHJ6TCuVZFfQoE0r0whdLdRLU2PsLFP+q7qaeZQqgBaNSKeVcDYR\n9B+nY/jOmQoPewPVsp/vQTCnE/R81spu0mp0YI6cIheT1Z9zAy322svcc43JaWB7\nmEbeqyLOP4Z4qSOcmghZBSECgYACvR9Xs0DGn+wCsW4vze/2ei77MD4OQvepPIFX\ndFZtlBy5ADcgE9z0cuVB6CiL8DbdK5kwY9pGNr8HUCI03iHkW6Zs+0L0YmihfEVe\nPG19PSzK9CaDdhD9KFZSbLyVFmWfxOt50H7YRTTiPMgjyFpfi5j2q348yVT0tEQS\nfhRqaQKBgAcWPokmJ7EbYQGeMbS7HC8eWO/RyamlnSffdCdSc7ue3zdVJxpAkQ8W\nqu80pEIF6raIQfAf8MXiiZ7auFOSnHQTXUbhCpvDLKi0Mwq3G8Pl07l+2s6dQG6T\nlv6XTQaMyf6n1yjzL+fzDrH3qXMxHMO/b13EePXpDMpY7HQpoLDi\n-----END RSA PRIVATE KEY-----\n"
certificate string	The zone's SSL certificate or certificate and the intermediate(s) "-----BEGIN CERTIFICATE-----\nMIIDtTCCAp2gAwIBAgIJAMHAwfXZ5/PWMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV\nBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX\naWRnaXRzIFB0eSBMdGQwHhcNMTYwODI0MTY0MzAxWhcNMTYxMTIyMTY0MzAxWjBF\nMQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50\nZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\nCgKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmGdtcGbg/1\nCGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKnabIRuGvB\nKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpidtnKX/a+5\n0GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+pyFxIXjbEI\ndZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pEewooaeO2\nizNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABo4GnMIGkMB0GA1UdDgQWBBT/LbE4\n9rWf288N6sJA5BRb6FJIGDB1BgNVHSMEbjBsgBT/LbE49rWf288N6sJA5BRb6FJI\nGKFJpEcwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNV\nBAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZIIJAMHAwfXZ5/PWMAwGA1UdEwQF\nMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAHHFwl0tH0quUYZYO0dZYt4R7SJ0pCm2\n2satiyzHl4OnXcHDpekAo7/a09c6Lz6AU83cKy/+x3/djYHXWba7HpEu0dR3ugQP\nMlr4zrhd9xKZ0KZKiYmtJH+ak4OM4L3FbT0owUZPyjLSlhMtJVcoRp5CJsjAMBUG\nSvD8RX+T01wzox/Qb+lnnNnOlaWpqu8eoOenybxKp1a9ULzIVvN/LAcc+14vioFq\n2swRWtmocBAs8QR9n4uvbpiYvS8eYueDCWMM4fvFfBhaDZ3N9IbtySh3SpFdQDhw\nYbjM2rxXiyLGxB4Bol7QTv4zHif7Zt89FReT/NBy4rzaskDJY5L6xmY=\n-----END CERTIFICATE-----\n"
bundle_method string	A ubiquitous bundle has the highest probability of being verified everywhere, even by clients using outdated or unusual trust stores. An optimal bundle uses the shortest chain and newest intermediates. And the force bundle verifies the chain, but does not otherwise modify it. `"ubiquitous"`	default value: ubiquitous valid values: ubiquitous, optimal, force
geo_restrictions object	Specify the region where your private key can be held locally for optimal TLS performance. HTTPS connections to any excluded data center will still be fully encrypted, but will incur some latency while Keyless SSL is used to complete the handshake with the nearest allowed data center. Options allow distribution to only to U.S. data centers, only to E.U. data centers, or only to highest security data centers. Default distribution is to all Cloudflare datacenters, for optimal performance. `{ "label": "us" }` An object with the following properties: Show definition »

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_certificates/2458ce5a-0c35-4c7f-82c7-8e9487d3ff60" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"private_key":"-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmG\ndtcGbg/1CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKn\nabIRuGvBKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpid\ntnKX/a+50GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+py\nFxIXjbEIdZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pE\newooaeO2izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABAoIBACbhTYXBZYKmYPCb\nHBR1IBlCQA2nLGf0qRuJNJZg5iEzXows/6tc8YymZkQE7nolapWsQ+upk2y5Xdp/\naxiuprIs9JzkYK8Ox0r+dlwCG1kSW+UAbX0bQ/qUqlsTvU6muVuMP8vZYHxJ3wmb\n+ufRBKztPTQ/rYWaYQcgC0RWI20HTFBMxlTAyNxYNWzX7RKFkGVVyB9RsAtmcc8g\n+j4OdosbfNoJPS0HeIfNpAznDfHKdxDk2Yc1tV6RHBrC1ynyLE9+TaflIAdo2MVv\nKLMLq51GqYKtgJFIlBRPQqKoyXdz3fGvXrTkf/WY9QNq0J1Vk5ERePZ54mN8iZB7\n9lwy/AkCgYEA6FXzosxswaJ2wQLeoYc7ceaweX/SwTvxHgXzRyJIIT0eJWgx13Wo\n/WA3Iziimsjf6qE+SI/8laxPp2A86VMaIt3Z3mJN/CqSVGw8LK2AQst+OwdPyDMu\niacE8lj/IFGC8mwNUAb9CzGU3JpU4PxxGFjS/eMtGeRXCWkK4NE+G08CgYEA1Kp9\nN2JrVlqUz+gAX+LPmE9OEMAS9WQSQsfCHGogIFDGGcNf7+uwBM7GAaSJIP01zcoe\nVAgWdzXCv3FLhsaZoJ6RyLOLay5phbu1iaTr4UNYm5WtYTzMzqh8l1+MFFDl9xDB\nvULuCIIrglM5MeS/qnSg1uMoH2oVPj9TVst/ir8CgYEAxrI7Ws9Zc4Bt70N1As+U\nlySjaEVZCMkqvHJ6TCuVZFfQoE0r0whdLdRLU2PsLFP+q7qaeZQqgBaNSKeVcDYR\n9B+nY/jOmQoPewPVsp/vQTCnE/R81spu0mp0YI6cIheT1Z9zAy322svcc43JaWB7\nmEbeqyLOP4Z4qSOcmghZBSECgYACvR9Xs0DGn+wCsW4vze/2ei77MD4OQvepPIFX\ndFZtlBy5ADcgE9z0cuVB6CiL8DbdK5kwY9pGNr8HUCI03iHkW6Zs+0L0YmihfEVe\nPG19PSzK9CaDdhD9KFZSbLyVFmWfxOt50H7YRTTiPMgjyFpfi5j2q348yVT0tEQS\nfhRqaQKBgAcWPokmJ7EbYQGeMbS7HC8eWO/RyamlnSffdCdSc7ue3zdVJxpAkQ8W\nqu80pEIF6raIQfAf8MXiiZ7auFOSnHQTXUbhCpvDLKi0Mwq3G8Pl07l+2s6dQG6T\nlv6XTQaMyf6n1yjzL+fzDrH3qXMxHMO/b13EePXpDMpY7HQpoLDi\n-----END RSA PRIVATE KEY-----\n","certificate":"-----BEGIN CERTIFICATE-----\nMIIDtTCCAp2gAwIBAgIJAMHAwfXZ5/PWMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV\nBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX\naWRnaXRzIFB0eSBMdGQwHhcNMTYwODI0MTY0MzAxWhcNMTYxMTIyMTY0MzAxWjBF\nMQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50\nZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\nCgKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmGdtcGbg/1\nCGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKnabIRuGvB\nKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpidtnKX/a+5\n0GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+pyFxIXjbEI\ndZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pEewooaeO2\nizNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABo4GnMIGkMB0GA1UdDgQWBBT/LbE4\n9rWf288N6sJA5BRb6FJIGDB1BgNVHSMEbjBsgBT/LbE49rWf288N6sJA5BRb6FJI\nGKFJpEcwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNV\nBAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZIIJAMHAwfXZ5/PWMAwGA1UdEwQF\nMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAHHFwl0tH0quUYZYO0dZYt4R7SJ0pCm2\n2satiyzHl4OnXcHDpekAo7/a09c6Lz6AU83cKy/+x3/djYHXWba7HpEu0dR3ugQP\nMlr4zrhd9xKZ0KZKiYmtJH+ak4OM4L3FbT0owUZPyjLSlhMtJVcoRp5CJsjAMBUG\nSvD8RX+T01wzox/Qb+lnnNnOlaWpqu8eoOenybxKp1a9ULzIVvN/LAcc+14vioFq\n2swRWtmocBAs8QR9n4uvbpiYvS8eYueDCWMM4fvFfBhaDZ3N9IbtySh3SpFdQDhw\nYbjM2rxXiyLGxB4Bol7QTv4zHif7Zt89FReT/NBy4rzaskDJY5L6xmY=\n-----END CERTIFICATE-----\n","bundle_method":"ubiquitous","geo_restrictions":{"label":"us"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
    "hosts": [
      "example.com"
    ],
    "issuer": "GlobalSign",
    "signature": "SHA256WithRSA",
    "status": "active",
    "bundle_method": "ubiquitous",
    "geo_restrictions": {
      "label": "us"
    },
    "zone_id": "023e105f4ecef8ad9ca31a8372d0c353",
    "uploaded_on": "2014-01-01T05:20:00Z",
    "modified_on": "2014-01-01T05:20:00Z",
    "expires_on": "2016-01-01T05:20:00Z",
    "priority": 1
  }
}

custom-ssl-for-a-zone-delete-ssl-configuration

DELETE Delete SSL Configuration permission needed: #ssl:edit
free
pro
business
enterprise

DELETE zones/:zone_identifier/custom_certificates/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_certificates/2458ce5a-0c35-4c7f-82c7-8e9487d3ff60" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60"
  }
}

custom-ssl-for-a-zone-re-prioritize-ssl-certificates

PUT Re-prioritize SSL Certificates permission needed: #ssl:edit
free
pro
business
enterprise

If a zone has multiple SSL certificates, you can set the order in which they should be used during a request. Higher priority numbers will be tried first.

PUT zones/:zone_identifier/custom_certificates/prioritize

Required parameters

Name /type	Description /example	Constraints
certificates array	Array of ordered certificates. `[ { "id": "5a7805061c76ada191ed06f989cc3dac", "priority": 2 }, { "id": "9a7806061c88ada191ed06f989cc3dac", "priority": 1 } ]` An array with items in the following form: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_certificates/prioritize" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"certificates":[{"id":"5a7805061c76ada191ed06f989cc3dac","priority":2},{"id":"9a7806061c88ada191ed06f989cc3dac","priority":1}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
      "hosts": [
        "example.com"
      ],
      "issuer": "GlobalSign",
      "signature": "SHA256WithRSA",
      "status": "active",
      "bundle_method": "ubiquitous",
      "geo_restrictions": {
        "label": "us"
      },
      "zone_id": "023e105f4ecef8ad9ca31a8372d0c353",
      "uploaded_on": "2014-01-01T05:20:00Z",
      "modified_on": "2014-01-01T05:20:00Z",
      "expires_on": "2016-01-01T05:20:00Z",
      "priority": 1
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

Custom Hostname for a Zone

Manage hostnames for your zone that are routed via CNAME.

custom-hostname-for-a-zone

Object definition

View properties and constraints defined on the object

Show definition

custom-hostname-for-a-zone-list-custom-hostnames

GET List Custom Hostnames permission needed: #ssl:read
free
pro
business
enterprise

List, search, sort, and filter all of your custom hostnames

GET zones/:zone_identifier/custom_hostnames

Optional parameters

Name /type	Description /example	Constraints
hostname string	Fully qualified domain name to match against. This parameter cannot be used with the 'id' parameter. `"app.example.com"`	max length: 255
id string	Hostname ID to match against. This ID was generated and returned during the initial custom_hostname creation. This parameter cannot be used with the 'hostname' parameter. `"0d89c70d-ad9f-4843-b99f-6cc0252067e9"`	min length: 36 max length: 36
page number	Page number of paginated results `1`	default value: 1 min value:1
per_page number	Number of hostnames per page `20`	default value: 20 min value:5 max value:50
order	Field to order hostnames by `"ssl"`	default value: ssl valid values: ssl, ssl_status
direction	Direction to order hostnames `"desc"`	valid values: asc, desc
ssl	Whether to filter hostnames based on if they have SSL enabled `"0"`	default value: 0 valid values: 0, 1

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_hostnames?hostname=app.example.com&id=0d89c70d-ad9f-4843-b99f-6cc0252067e9&page=1&per_page=20&order=ssl&direction=desc&ssl=0" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "0d89c70d-ad9f-4843-b99f-6cc0252067e9",
      "hostname": "app.example.com",
      "ssl": {
        "status": "pending_validation",
        "method": "http",
        "type": "dv",
        "cname_target": "dcv.digicert.com",
        "cname": "810b7d5f01154524b961ba0cd578acc2.app.example.com"
      }
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

custom-hostname-for-a-zone-create-custom-hostname

POST Create Custom Hostname permission needed: #ssl:edit
free
pro
business
enterprise

Add a new custom hostname and request that an SSL certificate be issued for it. One of three validation methods—http, cname, email—should be used, with 'http' recommended if the CNAME is already in place (or will be soon). Specifying 'email' will send an email to the WHOIS contacts on file for the base domain plus hostmaster, postmaster, webmaster, admin, administrator. Specifying 'cname' will return a CNAME that needs to be placed. If http is used and the domain is not already pointing to the Managed CNAME host, the PATCH method must be used once it is (to complete validation).

POST zones/:zone_identifier/custom_hostnames

Required parameters

Name /type	Description /example	Constraints
hostname string	The custom hostname that will point to your hostname via CNAME. `"app.example.com"`	max length: 255 read only
ssl object	SSL properties used when creating the custom hostname `{ "method": "http", "type": "dv", "settings": { "http2": "on", "min_tls_version": "1.2", "tls_1_3": "on", "ciphers": [ "ECDHE-RSA-AES128-GCM-SHA256", "AES128-SHA" ] } }` One of the following: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_hostnames" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"hostname":"app.example.com","ssl":{"method":"http","type":"dv","settings":{"http2":"on","min_tls_version":"1.2","tls_1_3":"on","ciphers":["ECDHE-RSA-AES128-GCM-SHA256","AES128-SHA"]}}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "0d89c70d-ad9f-4843-b99f-6cc0252067e9",
    "hostname": "app.example.com",
    "ssl": {
      "status": "pending_validation",
      "method": "http",
      "type": "dv",
      "cname_target": "dcv.digicert.com",
      "cname": "810b7d5f01154524b961ba0cd578acc2.app.example.com"
    }
  }
}

custom-hostname-for-a-zone-custom-hostname-details

GET Custom Hostname Details permission needed: #ssl:read
free
pro
business
enterprise

GET zones/:zone_identifier/custom_hostnames/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_hostnames/0d89c70d-ad9f-4843-b99f-6cc0252067e9" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "0d89c70d-ad9f-4843-b99f-6cc0252067e9",
    "hostname": "app.example.com",
    "ssl": {
      "status": "pending_validation",
      "method": "http",
      "type": "dv",
      "cname_target": "dcv.digicert.com",
      "cname": "810b7d5f01154524b961ba0cd578acc2.app.example.com"
    }
  }
}

custom-hostname-for-a-zone-edit-custom-hostname

PATCH Edit Custom Hostname permission needed: #ssl:edit
free
pro
business
enterprise

Modify SSL configuration for a custom hostname. When sent with SSL config that matches existing config, used to indicate that hostname should pass domain control validation (DCV). Can also be used to change validation type, e.g., from 'http' to 'email'.

PATCH zones/:zone_identifier/custom_hostnames/:identifier

Optional parameters

Name /type	Description /example	Constraints
ssl object	SSL properties used when creating the custom hostname `{ "method": "http", "type": "dv", "settings": { "http2": "on", "min_tls_version": "1.2", "tls_1_3": "on", "ciphers": [ "ECDHE-RSA-AES128-GCM-SHA256", "AES128-SHA" ] } }` One of the following: Show definition »

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_hostnames/0d89c70d-ad9f-4843-b99f-6cc0252067e9" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"ssl":{"method":"http","type":"dv","settings":{"http2":"on","min_tls_version":"1.2","tls_1_3":"on","ciphers":["ECDHE-RSA-AES128-GCM-SHA256","AES128-SHA"]}}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "0d89c70d-ad9f-4843-b99f-6cc0252067e9",
    "hostname": "app.example.com",
    "ssl": {
      "status": "pending_validation",
      "method": "http",
      "type": "dv",
      "cname_target": "dcv.digicert.com",
      "cname": "810b7d5f01154524b961ba0cd578acc2.app.example.com"
    }
  }
}

custom-hostname-for-a-zone-delete-custom-hostname-and-any-issued-ssl-certificates-

DELETE Delete Custom Hostname (and any issued SSL certificates) permission needed: #ssl:edit
free
pro
business
enterprise

DELETE zones/:zone_identifier/custom_hostnames/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_hostnames/0d89c70d-ad9f-4843-b99f-6cc0252067e9" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "id": "0d89c70d-ad9f-4843-b99f-6cc0252067e9"
}

Keyless SSL for a Zone

A Keyless certificate is an SSL certificate where the SSL private key is not stored on Cloudflare

keyless-ssl-for-a-zone

Object definition

View properties and constraints defined on the object

Show definition

keyless-ssl-for-a-zone-list-keyless-ssl-configurations

GET List Keyless SSL Configurations permission needed: #ssl:read
free
pro
business
enterprise

List all Keyless SSL configurations for a given zone

GET zones/:zone_identifier/keyless_certificates

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/keyless_certificates" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "4d2844d2ce78891c34d0b6c0535a291e",
      "name": "example.com Keyless SSL",
      "host": "example.com",
      "port": 24008,
      "status": "active",
      "enabled": false,
      "permissions": [
        "#ssl:read",
        "#ssl:edit"
      ],
      "created_on": "2014-01-01T05:20:00Z",
      "modified_on": "2014-01-01T05:20:00Z"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

keyless-ssl-for-a-zone-create-keyless-ssl-configuration

POST Create Keyless SSL Configuration permission needed: #ssl:edit
free
pro
business
enterprise

POST zones/:zone_identifier/keyless_certificates

Required parameters

Name /type	Description /example	Constraints
host string	The keyless SSL name `"example.com"`	max length: 253 pattern: hostname_or_ip
port number	The keyless SSL port used to commmunicate between Cloudflare and the client's Keyless SSL server `24008`	default value: 24008 max length: 65535
certificate string	The zone's SSL certificate or SSL certificate and intermediate(s) "-----BEGIN CERTIFICATE----- MIIDtTCCAp2gAwIBAgIJAM15n7fdxhRtMA0GCSqGSIb3DQEBBQUAMEUxCzAJBgNV BAYTAlVTMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX aWRnaXRzIFB0eSBMdGQwHhcNMTQwMzExMTkyMTU5WhcNMTQwNDEwMTkyMTU5WjBF MQswCQYDVQQGEwJVUzETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50 ZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB CgKCAQEAvq3sKsHpeduJHimOK+fvQdKsI8z8A05MZyyLp2/R/GE8FjNv+hkVY1WQ LIyTNNQH7CJecE1nbTfo8Y56S7x/rhxC6/DJ8MIulapFPnorq46KU6yRxiM0MQ3N nTJHlHA2ozZta6YBBfVfhHWl1F0IfNbXCLKvGwWWMbCx43OfW6KTkbRnE6gFWKuO fSO5h2u5TaWVuSIzBvYs7Vza6m+gtYAvKAJV2nSZ+eSEFPDo29corOy8+huEOUL8 5FAw4BFPsr1TlrlGPFitduQUHGrSL7skk1ESGza0to3bOtrodKei2s9bk5MXm7lZ qI+WZJX4Zu9+mzZhc9pCVi8r/qlXuQIDAQABo4GnMIGkMB0GA1UdDgQWBBRvavf+ sWM4IwKiH9X9w1vl6nUVRDB1BgNVHSMEbjBsgBRvavf+sWM4IwKiH9X9w1vl6nUV RKFJpEcwRTELMAkGA1UEBhMCVVMxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNV BAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZIIJAM15n7fdxhRtMAwGA1UdEwQF MAMBAf8wDQYJKoZIhvcNAQEFBQADggEBABY2ZzBaW0dMsAAT7tPJzrVWVzQx6KU4 UEBLudIlWPlkAwTnINCWR/8eNjCCmGA4heUdHmazdpPa8RzwOmc0NT1NQqzSyktt vTqb4iHD7+8f9MqJ9/FssCfTtqr/Qst/hGH4Wmdf1EJ/6FqYAAb5iRlPgshFZxU8 uXtA8hWn6fK6eISD9HBdcAFToUvKNZ1BIDPvh9f95Ine8ar6yGd56TUNrHR8eHBs ESxz5ddVR/oWRysNJ+aGAyYqHS8S/ttmC7r4XCAHqXptkHPCGRqkAhsterYhd4I8 /cBzejUobNCjjHFbtkAL/SjxZOLW+pNkZwfeYdM8iPkD54Uua1v2tdw= -----END CERTIFICATE-----"

Optional parameters

Name /type	Description /example	Constraints
name string	The keyless SSL name `"example.com Keyless SSL"`	max length: 180 read only
bundle_method string	A ubiquitous bundle has the highest probability of being verified everywhere, even by clients using outdated or unusual trust stores. An optimal bundle uses the shortest chain and newest intermediates. And the force bundle verifies the chain, but does not otherwise modify it. `"ubiquitous"`	default value: ubiquitous valid values: ubiquitous, optimal, force

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/keyless_certificates" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"host":"example.com","port":24008,"name":"example.com Keyless SSL","certificate":"-----BEGIN CERTIFICATE----- MIIDtTCCAp2gAwIBAgIJAM15n7fdxhRtMA0GCSqGSIb3DQEBBQUAMEUxCzAJBgNV BAYTAlVTMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX aWRnaXRzIFB0eSBMdGQwHhcNMTQwMzExMTkyMTU5WhcNMTQwNDEwMTkyMTU5WjBF MQswCQYDVQQGEwJVUzETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50 ZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB CgKCAQEAvq3sKsHpeduJHimOK+fvQdKsI8z8A05MZyyLp2/R/GE8FjNv+hkVY1WQ LIyTNNQH7CJecE1nbTfo8Y56S7x/rhxC6/DJ8MIulapFPnorq46KU6yRxiM0MQ3N nTJHlHA2ozZta6YBBfVfhHWl1F0IfNbXCLKvGwWWMbCx43OfW6KTkbRnE6gFWKuO fSO5h2u5TaWVuSIzBvYs7Vza6m+gtYAvKAJV2nSZ+eSEFPDo29corOy8+huEOUL8 5FAw4BFPsr1TlrlGPFitduQUHGrSL7skk1ESGza0to3bOtrodKei2s9bk5MXm7lZ qI+WZJX4Zu9+mzZhc9pCVi8r/qlXuQIDAQABo4GnMIGkMB0GA1UdDgQWBBRvavf+ sWM4IwKiH9X9w1vl6nUVRDB1BgNVHSMEbjBsgBRvavf+sWM4IwKiH9X9w1vl6nUV RKFJpEcwRTELMAkGA1UEBhMCVVMxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNV BAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZIIJAM15n7fdxhRtMAwGA1UdEwQF MAMBAf8wDQYJKoZIhvcNAQEFBQADggEBABY2ZzBaW0dMsAAT7tPJzrVWVzQx6KU4 UEBLudIlWPlkAwTnINCWR/8eNjCCmGA4heUdHmazdpPa8RzwOmc0NT1NQqzSyktt vTqb4iHD7+8f9MqJ9/FssCfTtqr/Qst/hGH4Wmdf1EJ/6FqYAAb5iRlPgshFZxU8 uXtA8hWn6fK6eISD9HBdcAFToUvKNZ1BIDPvh9f95Ine8ar6yGd56TUNrHR8eHBs ESxz5ddVR/oWRysNJ+aGAyYqHS8S/ttmC7r4XCAHqXptkHPCGRqkAhsterYhd4I8 /cBzejUobNCjjHFbtkAL/SjxZOLW+pNkZwfeYdM8iPkD54Uua1v2tdw= -----END CERTIFICATE-----","bundle_method":"ubiquitous"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "4d2844d2ce78891c34d0b6c0535a291e",
    "name": "example.com Keyless SSL",
    "host": "example.com",
    "port": 24008,
    "status": "active",
    "enabled": false,
    "permissions": [
      "#ssl:read",
      "#ssl:edit"
    ],
    "created_on": "2014-01-01T05:20:00Z",
    "modified_on": "2014-01-01T05:20:00Z"
  }
}

keyless-ssl-for-a-zone-get-keyless-ssl-configuration

GET Get Keyless SSL Configuration permission needed: #ssl:read
free
pro
business
enterprise

Get details for one Keyless SSL configuration

GET zones/:zone_identifier/keyless_certificates/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/keyless_certificates/4d2844d2ce78891c34d0b6c0535a291e" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "4d2844d2ce78891c34d0b6c0535a291e",
    "name": "example.com Keyless SSL",
    "host": "example.com",
    "port": 24008,
    "status": "active",
    "enabled": false,
    "permissions": [
      "#ssl:read",
      "#ssl:edit"
    ],
    "created_on": "2014-01-01T05:20:00Z",
    "modified_on": "2014-01-01T05:20:00Z"
  }
}

keyless-ssl-for-a-zone-edit-keyless-ssl-configuration

PATCH Edit Keyless SSL Configuration permission needed: #ssl:edit
free
pro
business
enterprise

This will update attributes of a Keyless SSL. Consists of one or more of the following: host,name,port,certificate,enabled

PATCH zones/:zone_identifier/keyless_certificates/:identifier

Optional parameters

Name /type	Description /example	Constraints
host string	The keyless SSL name `"example.com"`	max length: 253 pattern: hostname_or_ip
name string	The keyless SSL name `"example.com Keyless SSL"`	max length: 180 read only
port number	The keyless SSL port used to commmunicate between Cloudflare and the client's Keyless SSL server `24008`	default value: 24008 max length: 65535
enabled boolean	Whether or not the Keyless SSL is on or off `false`	valid values: (true,false) read only

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/keyless_certificates/4d2844d2ce78891c34d0b6c0535a291e" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"host":"example.com","name":"example.com Keyless SSL","port":24008,"enabled":false}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "4d2844d2ce78891c34d0b6c0535a291e",
    "name": "example.com Keyless SSL",
    "host": "example.com",
    "port": 24008,
    "status": "active",
    "enabled": false,
    "permissions": [
      "#ssl:read",
      "#ssl:edit"
    ],
    "created_on": "2014-01-01T05:20:00Z",
    "modified_on": "2014-01-01T05:20:00Z"
  }
}

keyless-ssl-for-a-zone-delete-keyless-ssl-configuration

DELETE Delete Keyless SSL Configuration permission needed: #ssl:edit
free
pro
business
enterprise

DELETE zones/:zone_identifier/keyless_certificates/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/keyless_certificates/4d2844d2ce78891c34d0b6c0535a291e" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "4d2844d2ce78891c34d0b6c0535a291e"
  }
}

Analyze Certificate

analyze-certificate

Object definition

View properties and constraints defined on the object

Show definition

analyze-certificate-analyze-certificate

POST Analyze Certificate permission needed: #ssl:read
free
pro
business
enterprise

Returns the set of hostnames, the signature algorithm, and the expiration date of the certificate.

POST zones/:identifier/ssl/analyze

Optional parameters

Name /type	Description /example	Constraints
certificate string	The zone's SSL certificate or certificate and the intermediate(s) "-----BEGIN CERTIFICATE-----\nMIIDtTCCAp2gAwIBAgIJAMHAwfXZ5/PWMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV\nBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX\naWRnaXRzIFB0eSBMdGQwHhcNMTYwODI0MTY0MzAxWhcNMTYxMTIyMTY0MzAxWjBF\nMQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50\nZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\nCgKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmGdtcGbg/1\nCGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKnabIRuGvB\nKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpidtnKX/a+5\n0GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+pyFxIXjbEI\ndZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pEewooaeO2\nizNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABo4GnMIGkMB0GA1UdDgQWBBT/LbE4\n9rWf288N6sJA5BRb6FJIGDB1BgNVHSMEbjBsgBT/LbE49rWf288N6sJA5BRb6FJI\nGKFJpEcwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNV\nBAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZIIJAMHAwfXZ5/PWMAwGA1UdEwQF\nMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAHHFwl0tH0quUYZYO0dZYt4R7SJ0pCm2\n2satiyzHl4OnXcHDpekAo7/a09c6Lz6AU83cKy/+x3/djYHXWba7HpEu0dR3ugQP\nMlr4zrhd9xKZ0KZKiYmtJH+ak4OM4L3FbT0owUZPyjLSlhMtJVcoRp5CJsjAMBUG\nSvD8RX+T01wzox/Qb+lnnNnOlaWpqu8eoOenybxKp1a9ULzIVvN/LAcc+14vioFq\n2swRWtmocBAs8QR9n4uvbpiYvS8eYueDCWMM4fvFfBhaDZ3N9IbtySh3SpFdQDhw\nYbjM2rxXiyLGxB4Bol7QTv4zHif7Zt89FReT/NBy4rzaskDJY5L6xmY=\n-----END CERTIFICATE-----\n"
bundle_method string	A ubiquitous bundle has the highest probability of being verified everywhere, even by clients using outdated or unusual trust stores. An optimal bundle uses the shortest chain and newest intermediates. And the force bundle verifies the chain, but does not otherwise modify it. `"ubiquitous"`	default value: ubiquitous valid values: ubiquitous, optimal, force

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/ssl/analyze" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"certificate":"-----BEGIN CERTIFICATE-----\nMIIDtTCCAp2gAwIBAgIJAMHAwfXZ5/PWMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV\nBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX\naWRnaXRzIFB0eSBMdGQwHhcNMTYwODI0MTY0MzAxWhcNMTYxMTIyMTY0MzAxWjBF\nMQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50\nZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\nCgKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmGdtcGbg/1\nCGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKnabIRuGvB\nKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpidtnKX/a+5\n0GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+pyFxIXjbEI\ndZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pEewooaeO2\nizNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABo4GnMIGkMB0GA1UdDgQWBBT/LbE4\n9rWf288N6sJA5BRb6FJIGDB1BgNVHSMEbjBsgBT/LbE49rWf288N6sJA5BRb6FJI\nGKFJpEcwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNV\nBAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZIIJAMHAwfXZ5/PWMAwGA1UdEwQF\nMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAHHFwl0tH0quUYZYO0dZYt4R7SJ0pCm2\n2satiyzHl4OnXcHDpekAo7/a09c6Lz6AU83cKy/+x3/djYHXWba7HpEu0dR3ugQP\nMlr4zrhd9xKZ0KZKiYmtJH+ak4OM4L3FbT0owUZPyjLSlhMtJVcoRp5CJsjAMBUG\nSvD8RX+T01wzox/Qb+lnnNnOlaWpqu8eoOenybxKp1a9ULzIVvN/LAcc+14vioFq\n2swRWtmocBAs8QR9n4uvbpiYvS8eYueDCWMM4fvFfBhaDZ3N9IbtySh3SpFdQDhw\nYbjM2rxXiyLGxB4Bol7QTv4zHif7Zt89FReT/NBy4rzaskDJY5L6xmY=\n-----END CERTIFICATE-----\n","bundle_method":"ubiquitous"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "hosts": [
      "example.com"
    ],
    "signature_algorithm": "SHA256WithRSA",
    "expires_on": "2016-01-01T05:20:00Z"
  }
}

Certificate Packs

certificate-packs

Object definition

View properties and constraints defined on the object

Show definition

certificate-packs-list-certificate-packs

GET List Certificate Packs permission needed: #ssl:read
free
pro
business
enterprise

For a given zone, list all certificate packs

GET zones/:zone_identifier/ssl/certificate_packs

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/ssl/certificate_packs" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "3822ff90-ea29-44df-9e55-21300bb9419b",
      "type": "custom",
      "hosts": [
        "example.com",
        "www.example.com",
        "foo.example.com"
      ],
      "certificates": [
        {
          "id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
          "hosts": [
            "example.com"
          ],
          "issuer": "GlobalSign",
          "signature": "SHA256WithRSA",
          "status": "active",
          "bundle_method": "ubiquitous",
          "geo_restrictions": {
            "label": "us"
          },
          "zone_id": "023e105f4ecef8ad9ca31a8372d0c353",
          "uploaded_on": "2014-01-01T05:20:00Z",
          "modified_on": "2014-01-01T05:20:00Z",
          "expires_on": "2016-01-01T05:20:00Z",
          "priority": 1
        }
      ],
      "primary_certificate": "7e7b8deba8538af625850b7b2530034c"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

certificate-packs-order-certificate-pack

POST Order Certificate Pack permission needed: #ssl:read#ssl:edit
free
pro
business
enterprise

For a given zone, order a certificate pack with a list of hostnames

POST zones/:zone_identifier/ssl/certificate_packs

Optional parameters

Name /type	Description /example	Constraints
hosts array	Comma separated list of valid host names for the certificate packs `[ "example.com", "www.example.com", "foo.example.com" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/ssl/certificate_packs" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"hosts":["example.com","www.example.com","foo.example.com"]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "3822ff90-ea29-44df-9e55-21300bb9419b",
    "type": "custom",
    "hosts": [
      "example.com",
      "www.example.com",
      "foo.example.com"
    ],
    "certificates": [
      {
        "id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
        "hosts": [
          "example.com"
        ],
        "issuer": "GlobalSign",
        "signature": "SHA256WithRSA",
        "status": "active",
        "bundle_method": "ubiquitous",
        "geo_restrictions": {
          "label": "us"
        },
        "zone_id": "023e105f4ecef8ad9ca31a8372d0c353",
        "uploaded_on": "2014-01-01T05:20:00Z",
        "modified_on": "2014-01-01T05:20:00Z",
        "expires_on": "2016-01-01T05:20:00Z",
        "priority": 1
      }
    ],
    "primary_certificate": "7e7b8deba8538af625850b7b2530034c"
  }
}

certificate-packs-edit-certificate-pack

PATCH Edit Certificate Pack permission needed: #ssl:read#ssl:edit
free
pro
business
enterprise

For a given certificate pack, edit the hosts

PATCH zones/:zone_identifier/ssl/certificate_packs/:identifier

Optional parameters

Name /type	Description /example	Constraints
hosts array	Comma separated list of valid host names for the certificate packs `[ "example.com", "www.example.com", "foo.example.com" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/ssl/certificate_packs/3822ff90-ea29-44df-9e55-21300bb9419b" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"hosts":["example.com","www.example.com","foo.example.com"]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "3822ff90-ea29-44df-9e55-21300bb9419b",
    "type": "custom",
    "hosts": [
      "example.com",
      "www.example.com",
      "foo.example.com"
    ],
    "certificates": [
      {
        "id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
        "hosts": [
          "example.com"
        ],
        "issuer": "GlobalSign",
        "signature": "SHA256WithRSA",
        "status": "active",
        "bundle_method": "ubiquitous",
        "geo_restrictions": {
          "label": "us"
        },
        "zone_id": "023e105f4ecef8ad9ca31a8372d0c353",
        "uploaded_on": "2014-01-01T05:20:00Z",
        "modified_on": "2014-01-01T05:20:00Z",
        "expires_on": "2016-01-01T05:20:00Z",
        "priority": 1
      }
    ],
    "primary_certificate": "7e7b8deba8538af625850b7b2530034c"
  }
}

Certificate Packs error codes

Code	Description
1400	Missing required property in request
1401	Error connecting to certificate service
1402	Error connecting to certificate service
1403	Bad response certificate service
1404	Bad response certificate service
1406	Bad response certificate service
1407	Bad response certificate service
1408	ID is not a dedicated certificate.

SSL Verification

SSL Verification for a Zone

ssl-verification

Object definition

View properties and constraints defined on the object

Show definition

ssl-verification-ssl-verification-details

GET SSL Verification Details permission needed: #ssl:read
free
pro
business
enterprise

Get SSL Verification Info for a Zone

GET zones/:zone_identifier/ssl/verification

Optional parameters

Name /type	Description /example	Constraints
retry	Immediately retry SSL Verification `true`	valid values: true

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/ssl/verification?retry=true" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "result": [
    {
      "certificate_status": "active",
      "verification_type": "cname",
      "verification_status": true,
      "verification_info": {
        "record_name": "b3b90cfedd89a3e487d3e383c56c4267.example.com",
        "record_target": "6979be7e4cfc9e5c603e31df7efac9cc60fee82d.comodoca.com"
      },
      "brand_check": false,
      "validation_method": "txt",
      "cert_pack_uuid": "a77f8bd7-3b47-46b4-a6f1-75cf98109948"
    }
  ]
}

ssl-verification-edit-ssl-certificate-pack-validation-method

PATCH Edit SSL Certificate Pack Validation Method permission needed: #ssl:read#ssl:edit
free
pro
business
enterprise

Edit SSL validation method for a certificate pack. A PATCH request will request an immediate validation check on any certificate, and return the updated status. If a validation method is provided, the validation will be immediately attempted using that method.

PATCH zones/:zone_identifier/ssl/verification/:cert_pack_uuid

Required parameters

Name /type	Description /example	Constraints
validation_method string	Desired validation method `"txt"`	valid values: http, cname, txt, email

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/ssl/verification/a77f8bd7-3b47-46b4-a6f1-75cf98109948" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"validation_method":"txt"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "validation_method": "txt",
    "status": "pending_validation"
  }
}

Universal SSL Settings for a Zone

universal-ssl-settings-for-a-zone

Object definition

View properties and constraints defined on the object

Show definition

universal-ssl-settings-for-a-zone-universal-ssl-settings-details

GET Universal SSL Settings Details permission needed: #ssl:read
free
pro
business
enterprise

Get Universal SSL Settings for a Zone

GET zones/:zone_identifier/ssl/universal/settings

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/ssl/universal/settings" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "enabled": true
  }
}

universal-ssl-settings-for-a-zone-edit-universal-ssl-settings

PATCH Edit Universal SSL Settings permission needed: #ssl:read#ssl:edit
free
pro
business
enterprise

Patch Universal SSL Settings for a Zone

PATCH zones/:zone_identifier/ssl/universal/settings

Optional parameters

Name /type	Description /example	Constraints
enabled boolean	Disabling Universal SSL removes any currently active Universal SSL certificates for your zone from the edge and prevents any future Universal SSL certificates from being ordered. If there are no dedicated certificates or custom certificates uploaded for the domain, visitors will be unable to access the domain over HTTPS. By disabling Universal SSL, you understand that the following Cloudflare settings and preferences will result in visitors being unable to visit your domain unless you have uploaded a custom certificate or purchased a dedicated certificate. HSTS Always Use HTTPS Opportunistic Encryption Onion Routing Any Page Rules redirecting traffic to HTTPS Similarly, any HTTP redirect to HTTPS at the origin while the Cloudflare proxy is enabled will result in users being unable to visit your site without a valid certificate at Cloudflare's edge. If you do not have a valid custom or dedicated certificate at Cloudflare's edge and are unsure if any of the above Cloudflare settings are enabled, or if any HTTP redirects exist at your origin, we advise leaving Universal SSL enabled for your domain. `true`	valid values: (true,false)

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/ssl/universal/settings" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"enabled":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "enabled": true
  }
}

Cloudflare CA

API to create Cloudflare-issued SSL certificates that can be installed on your origin server. Use your Certificates API Key as your User Service Key when calling these endpoints (see the section on request headers for details).

cloudflare-ca

Object definition

View properties and constraints defined on the object

Show definition

cloudflare-ca-list-certificates

GET List Certificates
free
pro
business
enterprise

List all existing Cloudflare-issued Certificates for a given zone. Use your Certificates API Key as your User Service Key when calling this endpoint (see above).

GET certificates

Required parameters

Name /type	Description /example	Constraints
zone_id string	Zone identifier tag `"023e105f4ecef8ad9ca31a8372d0c353"`	max length: 32 read only

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/certificates?zone_id=023e105f4ecef8ad9ca31a8372d0c353" \
     -H "X-Auth-User-Service-Key: v1.0-e24fd090c02efcfecb4de8f4ff246fd5c75b48946fdf0ce26c59f91d0d90797b-cfa33fe60e8e34073c149323454383fc9005d25c9b4c502c2f063457ef65322eade065975001a0b4b4c591c5e1bd36a6e8f7e2d4fa8a9ec01c64c041e99530c2-07b9efe0acd78c82c8d9c690aacb8656d81c369246d7f996a205fe3c18e9254a"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "3664634374038615934",
      "certificate": "-----BEGIN CERTIFICATE-----\nMIICvDCCAaQCAQAwdzELMAkGA1UEBhMCVVMxDTALBgNVBAgMBFV0YWgxDzANBgNV\nBAcMBkxpbmRvbjEWMBQGA1UECgwNRGlnaUNlcnQgSW5jLjERMA8GA1UECwwIRGln\naUNlcnQxHTAbBgNVBAMMFGV4YW1wbGUuZGlnaWNlcnQuY29tMIIBIjANBgkqhkiG\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEA8+To7d+2kPWeBv/orU3LVbJwDrSQbeKamCmo\nwp5bqDxIwV20zqRb7APUOKYoVEFFOEQs6T6gImnIolhbiH6m4zgZ/CPvWBOkZc+c\n1Po2EmvBz+AD5sBdT5kzGQA6NbWyZGldxRthNLOs1efOhdnWFuhI162qmcflgpiI\nWDuwq4C9f+YkeJhNn9dF5+owm8cOQmDrV8NNdiTqin8q3qYAHHJRW28glJUCZkTZ\nwIaSR6crBQ8TbYNE0dc+Caa3DOIkz1EOsHWzTx+n0zKfqcbgXi4DJx+C1bjptYPR\nBPZL8DAeWuA8ebudVT44yEp82G96/Ggcf7F33xMxe0yc+Xa6owIDAQABoAAwDQYJ\nKoZIhvcNAQEFBQADggEBAB0kcrFccSmFDmxox0Ne01UIqSsDqHgL+XmHTXJwre6D\nhJSZwbvEtOK0G3+dr4Fs11WuUNt5qcLsx5a8uk4G6AKHMzuhLsJ7XZjgmQXGECpY\nQ4mC3yT3ZoCGpIXbw+iP3lmEEXgaQL0Tx5LFl/okKbKYwIqNiyKWOMj7ZR/wxWg/\nZDGRs55xuoeLDJ/ZRFf9bI+IaCUd1YrfYcHIl3G87Av+r49YVwqRDT0VDV7uLgqn\n29XI1PpVUNCPQGn9p/eX6Qo7vpDaPybRtA2R7XLKjQaF9oXWeCUqy1hvJac9QFO2\n97Ob1alpHPoZ7mWiEuJwjBPii6a9M9G30nUo39lBi1w=\n-----END CERTIFICATE-----",
      "hostnames": [
        "example.com",
        "*.example.com"
      ],
      "expires_on": "2014-01-01T05:20:00.12345Z",
      "request_type": "origin-rsa",
      "requested_validity": 5475,
      "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICxzCCAa8CAQAwSDELMAkGA1UEBhMCVVMxFjAUBgNVBAgTDVNhbiBGcmFuY2lz\nY28xCzAJBgNVBAcTAkNBMRQwEgYDVQQDEwtleGFtcGxlLm5ldDCCASIwDQYJKoZI\nhvcNAQEBBQADggEPADCCAQoCggEBALxejtu4b+jPdFeFi6OUsye8TYJQBm3WfCvL\nHu5EvijMO/4Z2TImwASbwUF7Ir8OLgH+mGlQZeqyNvGoSOMEaZVXcYfpR1hlVak8\n4GGVr+04IGfOCqaBokaBFIwzclGZbzKmLGwIQioNxGfqFm6RGYGA3be2Je2iseBc\nN8GV1wYmvYE0RR+yWweJCTJ157exyRzu7sVxaEW9F87zBQLyOnwXc64rflXslRqi\ng7F7w5IaQYOl8yvmk/jEPCAha7fkiUfEpj4N12+oPRiMvleJF98chxjD4MH39c5I\nuOslULhrWunfh7GB1jwWNA9y44H0snrf+xvoy2TcHmxvma9Eln8CAwEAAaA6MDgG\nCSqGSIb3DQEJDjErMCkwJwYDVR0RBCAwHoILZXhhbXBsZS5uZXSCD3d3dy5leGFt\ncGxlLm5ldDANBgkqhkiG9w0BAQsFAAOCAQEAcBaX6dOnI8ncARrI9ZSF2AJX+8mx\npTHY2+Y2C0VvrVDGMtbBRH8R9yMbqWtlxeeNGf//LeMkSKSFa4kbpdx226lfui8/\nauRDBTJGx2R1ccUxmLZXx4my0W5iIMxunu+kez+BDlu7bTT2io0uXMRHue4i6quH\nyc5ibxvbJMjR7dqbcanVE10/34oprzXQsJ/VmSuZNXtjbtSKDlmcpw6To/eeAJ+J\nhXykcUihvHyG4A1m2R6qpANBjnA0pHexfwM/SgfzvpbvUg0T1ubmer8BgTwCKIWs\ndcWYTthM51JIqRBfNqy4QcBnX+GY05yltEEswQI55wdiS3CjTTA67sdbcQ==\n-----END CERTIFICATE REQUEST-----"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

cloudflare-ca-create-certificate

POST Create Certificate
free
pro
business
enterprise

Create a Cloudflare-signed certificate. Use your Certificates API Key as your User Service Key when calling this endpoint (see above).

POST certificates

Optional parameters

Name /type	Description /example	Constraints
hostnames array	Array of hostnames or wildcard names (e.g., .example.com) bound to the certificate `[ "example.com", ".example.com" ]`
requested_validity number	The number of days for which the certificate should be valid `5475`	default value: 5475 valid values: 7, 30, 90, 365, 730, 1095, 5475
request_type string	Signature type desired on certificate ("origin-rsa" (rsa), "origin-ecc" (ecdsa), or "keyless-certificate" (for Keyless SSL servers) `"origin-rsa"`	valid values: origin-rsa, origin-ecc, keyless-certificate
csr string	The Certificate Signing Request (CSR). Must be newline-encoded. "-----BEGIN CERTIFICATE REQUEST-----\nMIICxzCCAa8CAQAwSDELMAkGA1UEBhMCVVMxFjAUBgNVBAgTDVNhbiBGcmFuY2lz\nY28xCzAJBgNVBAcTAkNBMRQwEgYDVQQDEwtleGFtcGxlLm5ldDCCASIwDQYJKoZI\nhvcNAQEBBQADggEPADCCAQoCggEBALxejtu4b+jPdFeFi6OUsye8TYJQBm3WfCvL\nHu5EvijMO/4Z2TImwASbwUF7Ir8OLgH+mGlQZeqyNvGoSOMEaZVXcYfpR1hlVak8\n4GGVr+04IGfOCqaBokaBFIwzclGZbzKmLGwIQioNxGfqFm6RGYGA3be2Je2iseBc\nN8GV1wYmvYE0RR+yWweJCTJ157exyRzu7sVxaEW9F87zBQLyOnwXc64rflXslRqi\ng7F7w5IaQYOl8yvmk/jEPCAha7fkiUfEpj4N12+oPRiMvleJF98chxjD4MH39c5I\nuOslULhrWunfh7GB1jwWNA9y44H0snrf+xvoy2TcHmxvma9Eln8CAwEAAaA6MDgG\nCSqGSIb3DQEJDjErMCkwJwYDVR0RBCAwHoILZXhhbXBsZS5uZXSCD3d3dy5leGFt\ncGxlLm5ldDANBgkqhkiG9w0BAQsFAAOCAQEAcBaX6dOnI8ncARrI9ZSF2AJX+8mx\npTHY2+Y2C0VvrVDGMtbBRH8R9yMbqWtlxeeNGf//LeMkSKSFa4kbpdx226lfui8/\nauRDBTJGx2R1ccUxmLZXx4my0W5iIMxunu+kez+BDlu7bTT2io0uXMRHue4i6quH\nyc5ibxvbJMjR7dqbcanVE10/34oprzXQsJ/VmSuZNXtjbtSKDlmcpw6To/eeAJ+J\nhXykcUihvHyG4A1m2R6qpANBjnA0pHexfwM/SgfzvpbvUg0T1ubmer8BgTwCKIWs\ndcWYTthM51JIqRBfNqy4QcBnX+GY05yltEEswQI55wdiS3CjTTA67sdbcQ==\n-----END CERTIFICATE REQUEST-----"

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/certificates" \
     -H "X-Auth-User-Service-Key: v1.0-e24fd090c02efcfecb4de8f4ff246fd5c75b48946fdf0ce26c59f91d0d90797b-cfa33fe60e8e34073c149323454383fc9005d25c9b4c502c2f063457ef65322eade065975001a0b4b4c591c5e1bd36a6e8f7e2d4fa8a9ec01c64c041e99530c2-07b9efe0acd78c82c8d9c690aacb8656d81c369246d7f996a205fe3c18e9254a" \
     --data '{"hostnames":["example.com","*.example.com"],"requested_validity":5475,"request_type":"origin-rsa","csr":"-----BEGIN CERTIFICATE REQUEST-----\nMIICxzCCAa8CAQAwSDELMAkGA1UEBhMCVVMxFjAUBgNVBAgTDVNhbiBGcmFuY2lz\nY28xCzAJBgNVBAcTAkNBMRQwEgYDVQQDEwtleGFtcGxlLm5ldDCCASIwDQYJKoZI\nhvcNAQEBBQADggEPADCCAQoCggEBALxejtu4b+jPdFeFi6OUsye8TYJQBm3WfCvL\nHu5EvijMO/4Z2TImwASbwUF7Ir8OLgH+mGlQZeqyNvGoSOMEaZVXcYfpR1hlVak8\n4GGVr+04IGfOCqaBokaBFIwzclGZbzKmLGwIQioNxGfqFm6RGYGA3be2Je2iseBc\nN8GV1wYmvYE0RR+yWweJCTJ157exyRzu7sVxaEW9F87zBQLyOnwXc64rflXslRqi\ng7F7w5IaQYOl8yvmk/jEPCAha7fkiUfEpj4N12+oPRiMvleJF98chxjD4MH39c5I\nuOslULhrWunfh7GB1jwWNA9y44H0snrf+xvoy2TcHmxvma9Eln8CAwEAAaA6MDgG\nCSqGSIb3DQEJDjErMCkwJwYDVR0RBCAwHoILZXhhbXBsZS5uZXSCD3d3dy5leGFt\ncGxlLm5ldDANBgkqhkiG9w0BAQsFAAOCAQEAcBaX6dOnI8ncARrI9ZSF2AJX+8mx\npTHY2+Y2C0VvrVDGMtbBRH8R9yMbqWtlxeeNGf//LeMkSKSFa4kbpdx226lfui8/\nauRDBTJGx2R1ccUxmLZXx4my0W5iIMxunu+kez+BDlu7bTT2io0uXMRHue4i6quH\nyc5ibxvbJMjR7dqbcanVE10/34oprzXQsJ/VmSuZNXtjbtSKDlmcpw6To/eeAJ+J\nhXykcUihvHyG4A1m2R6qpANBjnA0pHexfwM/SgfzvpbvUg0T1ubmer8BgTwCKIWs\ndcWYTthM51JIqRBfNqy4QcBnX+GY05yltEEswQI55wdiS3CjTTA67sdbcQ==\n-----END CERTIFICATE REQUEST-----"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "3664634374038615934",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIICvDCCAaQCAQAwdzELMAkGA1UEBhMCVVMxDTALBgNVBAgMBFV0YWgxDzANBgNV\nBAcMBkxpbmRvbjEWMBQGA1UECgwNRGlnaUNlcnQgSW5jLjERMA8GA1UECwwIRGln\naUNlcnQxHTAbBgNVBAMMFGV4YW1wbGUuZGlnaWNlcnQuY29tMIIBIjANBgkqhkiG\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEA8+To7d+2kPWeBv/orU3LVbJwDrSQbeKamCmo\nwp5bqDxIwV20zqRb7APUOKYoVEFFOEQs6T6gImnIolhbiH6m4zgZ/CPvWBOkZc+c\n1Po2EmvBz+AD5sBdT5kzGQA6NbWyZGldxRthNLOs1efOhdnWFuhI162qmcflgpiI\nWDuwq4C9f+YkeJhNn9dF5+owm8cOQmDrV8NNdiTqin8q3qYAHHJRW28glJUCZkTZ\nwIaSR6crBQ8TbYNE0dc+Caa3DOIkz1EOsHWzTx+n0zKfqcbgXi4DJx+C1bjptYPR\nBPZL8DAeWuA8ebudVT44yEp82G96/Ggcf7F33xMxe0yc+Xa6owIDAQABoAAwDQYJ\nKoZIhvcNAQEFBQADggEBAB0kcrFccSmFDmxox0Ne01UIqSsDqHgL+XmHTXJwre6D\nhJSZwbvEtOK0G3+dr4Fs11WuUNt5qcLsx5a8uk4G6AKHMzuhLsJ7XZjgmQXGECpY\nQ4mC3yT3ZoCGpIXbw+iP3lmEEXgaQL0Tx5LFl/okKbKYwIqNiyKWOMj7ZR/wxWg/\nZDGRs55xuoeLDJ/ZRFf9bI+IaCUd1YrfYcHIl3G87Av+r49YVwqRDT0VDV7uLgqn\n29XI1PpVUNCPQGn9p/eX6Qo7vpDaPybRtA2R7XLKjQaF9oXWeCUqy1hvJac9QFO2\n97Ob1alpHPoZ7mWiEuJwjBPii6a9M9G30nUo39lBi1w=\n-----END CERTIFICATE-----",
    "hostnames": [
      "example.com",
      "*.example.com"
    ],
    "expires_on": "2014-01-01T05:20:00.12345Z",
    "request_type": "origin-rsa",
    "requested_validity": 5475,
    "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICxzCCAa8CAQAwSDELMAkGA1UEBhMCVVMxFjAUBgNVBAgTDVNhbiBGcmFuY2lz\nY28xCzAJBgNVBAcTAkNBMRQwEgYDVQQDEwtleGFtcGxlLm5ldDCCASIwDQYJKoZI\nhvcNAQEBBQADggEPADCCAQoCggEBALxejtu4b+jPdFeFi6OUsye8TYJQBm3WfCvL\nHu5EvijMO/4Z2TImwASbwUF7Ir8OLgH+mGlQZeqyNvGoSOMEaZVXcYfpR1hlVak8\n4GGVr+04IGfOCqaBokaBFIwzclGZbzKmLGwIQioNxGfqFm6RGYGA3be2Je2iseBc\nN8GV1wYmvYE0RR+yWweJCTJ157exyRzu7sVxaEW9F87zBQLyOnwXc64rflXslRqi\ng7F7w5IaQYOl8yvmk/jEPCAha7fkiUfEpj4N12+oPRiMvleJF98chxjD4MH39c5I\nuOslULhrWunfh7GB1jwWNA9y44H0snrf+xvoy2TcHmxvma9Eln8CAwEAAaA6MDgG\nCSqGSIb3DQEJDjErMCkwJwYDVR0RBCAwHoILZXhhbXBsZS5uZXSCD3d3dy5leGFt\ncGxlLm5ldDANBgkqhkiG9w0BAQsFAAOCAQEAcBaX6dOnI8ncARrI9ZSF2AJX+8mx\npTHY2+Y2C0VvrVDGMtbBRH8R9yMbqWtlxeeNGf//LeMkSKSFa4kbpdx226lfui8/\nauRDBTJGx2R1ccUxmLZXx4my0W5iIMxunu+kez+BDlu7bTT2io0uXMRHue4i6quH\nyc5ibxvbJMjR7dqbcanVE10/34oprzXQsJ/VmSuZNXtjbtSKDlmcpw6To/eeAJ+J\nhXykcUihvHyG4A1m2R6qpANBjnA0pHexfwM/SgfzvpbvUg0T1ubmer8BgTwCKIWs\ndcWYTthM51JIqRBfNqy4QcBnX+GY05yltEEswQI55wdiS3CjTTA67sdbcQ==\n-----END CERTIFICATE REQUEST-----"
  }
}

cloudflare-ca-certificate-details

GET Certificate Details
free
pro
business
enterprise

Get an existing certificate by its serial number. Use your Certificates API Key as your User Service Key when calling this endpoint (see above).

GET certificates/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/certificates/3664634374038615934" \
     -H "X-Auth-User-Service-Key: v1.0-e24fd090c02efcfecb4de8f4ff246fd5c75b48946fdf0ce26c59f91d0d90797b-cfa33fe60e8e34073c149323454383fc9005d25c9b4c502c2f063457ef65322eade065975001a0b4b4c591c5e1bd36a6e8f7e2d4fa8a9ec01c64c041e99530c2-07b9efe0acd78c82c8d9c690aacb8656d81c369246d7f996a205fe3c18e9254a"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "3664634374038615934",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIICvDCCAaQCAQAwdzELMAkGA1UEBhMCVVMxDTALBgNVBAgMBFV0YWgxDzANBgNV\nBAcMBkxpbmRvbjEWMBQGA1UECgwNRGlnaUNlcnQgSW5jLjERMA8GA1UECwwIRGln\naUNlcnQxHTAbBgNVBAMMFGV4YW1wbGUuZGlnaWNlcnQuY29tMIIBIjANBgkqhkiG\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEA8+To7d+2kPWeBv/orU3LVbJwDrSQbeKamCmo\nwp5bqDxIwV20zqRb7APUOKYoVEFFOEQs6T6gImnIolhbiH6m4zgZ/CPvWBOkZc+c\n1Po2EmvBz+AD5sBdT5kzGQA6NbWyZGldxRthNLOs1efOhdnWFuhI162qmcflgpiI\nWDuwq4C9f+YkeJhNn9dF5+owm8cOQmDrV8NNdiTqin8q3qYAHHJRW28glJUCZkTZ\nwIaSR6crBQ8TbYNE0dc+Caa3DOIkz1EOsHWzTx+n0zKfqcbgXi4DJx+C1bjptYPR\nBPZL8DAeWuA8ebudVT44yEp82G96/Ggcf7F33xMxe0yc+Xa6owIDAQABoAAwDQYJ\nKoZIhvcNAQEFBQADggEBAB0kcrFccSmFDmxox0Ne01UIqSsDqHgL+XmHTXJwre6D\nhJSZwbvEtOK0G3+dr4Fs11WuUNt5qcLsx5a8uk4G6AKHMzuhLsJ7XZjgmQXGECpY\nQ4mC3yT3ZoCGpIXbw+iP3lmEEXgaQL0Tx5LFl/okKbKYwIqNiyKWOMj7ZR/wxWg/\nZDGRs55xuoeLDJ/ZRFf9bI+IaCUd1YrfYcHIl3G87Av+r49YVwqRDT0VDV7uLgqn\n29XI1PpVUNCPQGn9p/eX6Qo7vpDaPybRtA2R7XLKjQaF9oXWeCUqy1hvJac9QFO2\n97Ob1alpHPoZ7mWiEuJwjBPii6a9M9G30nUo39lBi1w=\n-----END CERTIFICATE-----",
    "hostnames": [
      "example.com",
      "*.example.com"
    ],
    "expires_on": "2014-01-01T05:20:00.12345Z",
    "request_type": "origin-rsa",
    "requested_validity": 5475,
    "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICxzCCAa8CAQAwSDELMAkGA1UEBhMCVVMxFjAUBgNVBAgTDVNhbiBGcmFuY2lz\nY28xCzAJBgNVBAcTAkNBMRQwEgYDVQQDEwtleGFtcGxlLm5ldDCCASIwDQYJKoZI\nhvcNAQEBBQADggEPADCCAQoCggEBALxejtu4b+jPdFeFi6OUsye8TYJQBm3WfCvL\nHu5EvijMO/4Z2TImwASbwUF7Ir8OLgH+mGlQZeqyNvGoSOMEaZVXcYfpR1hlVak8\n4GGVr+04IGfOCqaBokaBFIwzclGZbzKmLGwIQioNxGfqFm6RGYGA3be2Je2iseBc\nN8GV1wYmvYE0RR+yWweJCTJ157exyRzu7sVxaEW9F87zBQLyOnwXc64rflXslRqi\ng7F7w5IaQYOl8yvmk/jEPCAha7fkiUfEpj4N12+oPRiMvleJF98chxjD4MH39c5I\nuOslULhrWunfh7GB1jwWNA9y44H0snrf+xvoy2TcHmxvma9Eln8CAwEAAaA6MDgG\nCSqGSIb3DQEJDjErMCkwJwYDVR0RBCAwHoILZXhhbXBsZS5uZXSCD3d3dy5leGFt\ncGxlLm5ldDANBgkqhkiG9w0BAQsFAAOCAQEAcBaX6dOnI8ncARrI9ZSF2AJX+8mx\npTHY2+Y2C0VvrVDGMtbBRH8R9yMbqWtlxeeNGf//LeMkSKSFa4kbpdx226lfui8/\nauRDBTJGx2R1ccUxmLZXx4my0W5iIMxunu+kez+BDlu7bTT2io0uXMRHue4i6quH\nyc5ibxvbJMjR7dqbcanVE10/34oprzXQsJ/VmSuZNXtjbtSKDlmcpw6To/eeAJ+J\nhXykcUihvHyG4A1m2R6qpANBjnA0pHexfwM/SgfzvpbvUg0T1ubmer8BgTwCKIWs\ndcWYTthM51JIqRBfNqy4QcBnX+GY05yltEEswQI55wdiS3CjTTA67sdbcQ==\n-----END CERTIFICATE REQUEST-----"
  }
}

cloudflare-ca-revoke-certificate

DELETE Revoke Certificate
free
pro
business
enterprise

Revoke a created certificate for a zone. Use your Certificates API Key as your User Service Key when calling this endpoint (see above).

DELETE certificates/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/certificates/3664634374038615934" \
     -H "X-Auth-User-Service-Key: v1.0-e24fd090c02efcfecb4de8f4ff246fd5c75b48946fdf0ce26c59f91d0d90797b-cfa33fe60e8e34073c149323454383fc9005d25c9b4c502c2f063457ef65322eade065975001a0b4b4c591c5e1bd36a6e8f7e2d4fa8a9ec01c64c041e99530c2-07b9efe0acd78c82c8d9c690aacb8656d81c369246d7f996a205fe3c18e9254a"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "3664634374038615934"
  }
}

Cloudflare CA error codes

Code	Description
1000	API errors encountered
1001	Request had no Authorization header
1002	Unsupported request_type
1003	Failed to read contents of HTTP request
1004	Failed to parse request JSON
1005	Too many hostnames requested - you may only request up to 100 per certificate
1006	One or more hostnames were duplicated in the request and have been removed prior to certificate generation
1007	CSR parsed as empty
1008	Error creating request to CA
1009	Permitted values for the 'requested_validity' parameter (specified in days) are: 7, 30, 90, 365, 730, 1095, and 5475 (default)
1010	Failed to validate SAN <hostname>: <reason for failure>
1011	Failed to parse CSR
1012	Please provide a zone id when requesting a stored certificate, or fetch by serial number
1013	Please provide a certificate serial number when operating on a single certificate
1014	Certificate already revoked
1100	Failed to write certificate to database
1101	Failed to read certificate from database
1200	API Error: Failed to generate CA request
1201	CA signing failure. Could not parse returned certificate
1300	Failed to fetch keyless servers from API
1301	key server didn't activate correctly
1302	Could not get keyless server port for server <server>
1303	invalid hostname: <hostname>

Stream Videos

You can upload videos to Cloudflare Stream for fast video processing and delivery.

stream-videos

Object definition

View properties and constraints defined on the object

Show definition

GET List Videos

GET zones/:zone_identifier/media

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/media" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "uid": "ea95132c15732412d22c1476fa83f27a",
      "thumb": "https://cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/thumbnails/thumb_5_0.jpg",
      "ready": false,
      "status": {
        "state": "ready",
        "pct_complete": 51
      },
      "labels": [],
      "created": "2014-01-02T02:20:00Z",
      "modified": "2014-01-02T02:20:00Z",
      "size": 4190963,
      "preview": "https://watch.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

stream-videos-initiate-a-video-upload

POST Initiate a Video Upload

Initiate a video upload using the TUS protocol. On success, server will response with status code 201 (Created) and include a 'location' header indicating where the video content should be uploaded to. (See https://tus.io for protocol details.). On success the body of the response will be empty (zero-length content). On failure the body will contain a JSON error response.

POST zones/:zone_identifier/media

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/media" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Tus-Resumable: 1.0.0" \
     -H "Upload-Length: 900000000"

Response (example)

stream-videos-upload-a-video-content-range

PATCH Upload a Video Content Range

Upload a portion of a video using the TUS protocol (See https://tus.io for protocol details). On success return 204 (No Content) with no body content. Each chunk, except the final chunk must be 5242880 bytes in size for uploads larger than 5242880 bytes.

PATCH zones/:zone_identifier/media/:identifier

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/media/ea95132c15732412d22c1476fa83f27a" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Tus-Resumable: 1.0.0" \
     -H "Content-Length: 52428800" \
     -H "Upload-Offset: 0"

Response (example)

stream-videos-video-details

GET Video Details

Fetch details of a single video.

GET zones/:zone_identifier/media/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/media/ea95132c15732412d22c1476fa83f27a" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "uid": "ea95132c15732412d22c1476fa83f27a",
    "thumb": "https://cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/thumbnails/thumb_5_0.jpg",
    "ready": false,
    "status": {
      "state": "ready",
      "pct_complete": 51
    },
    "labels": [],
    "created": "2014-01-02T02:20:00Z",
    "modified": "2014-01-02T02:20:00Z",
    "size": 4190963,
    "preview": "https://watch.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a"
  }
}

stream-videos-embed-code-html

GET Embed Code HTML

Fetch an HTML code snippet that can be used to embed the video in a web page that is delivered through Cloudflare. On success returns an HTML fragment (not a full document) that can be included on a web page to display the video. On failure returns a JSON response body (see Error Response) above.

GET zones/:zone_identifier/media/:identifier/embed

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/media/ea95132c15732412d22c1476fa83f27a/embed" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

<stream id="ea95132c15732412d22c1476fa83f27a"></stream><script data-cfasync="false" defer type="text/javascript" src="https://embed.cloudflarestream.com/embed/we4g.fla9.latest.js"></script>

stream-videos-link-to-video

GET Link to Video

Receive an HTTP redirect response to an HTML page containing a preview of this video. On success returns status code 301 and a location header indicating the new location, with no body. On failure returns a JSON response body (see Error Response above).

GET zones/:zone_identifier/media/:identifier/preview

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/media/ea95132c15732412d22c1476fa83f27a/preview" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

"<a href=\"https://watch.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a\">Permanent Redirect</a>."

stream-videos-delete-video

DELETE Delete video

Delete a video on Cloudflare Stream. On success, all copies of the video are deleted.

DELETE zones/:zone_identifier/media/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/media/ea95132c15732412d22c1476fa83f27a" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

Stream Videos error codes

Code	Description
10000	Internal Server Error
10001	Authentication Failure

Worker Script

A Worker script is a single script that is executed on matching filters in the Cloudflare edge

worker-script

Object definition

View properties and constraints defined on the object

Show definition

worker-script-download-worker

GET Download Worker

Fetch raw script content for your worker. Note this is the original script content, not JSON encoded.

GET zones/:zone_identifier/workers/script

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/workers/script" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Accept: application/javascript"

Response (example)

addEventListener('fetch', event => { event.respondWith(fetch(event.request) }))

worker-script-delete-worker

DELETE Delete Worker

Delete your worker. This call has no response body on a successful delete.

DELETE zones/:zone_identifier/workers/script

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/workers/script" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

worker-script-upload-worker

PUT Upload Worker

Upload a worker, or a new version of a worker.

PUT zones/:zone_identifier/workers/script

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/workers/script" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/javascript" \
--data "addEventListener('fetch', event => { event.respondWith(fetch(event.request) }))"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "script": "addEventListener('fetch', event => { event.respondWith(fetch(event.request) }))",
    "etag": "ea95132c15732412d22c1476fa83f27a",
    "size": 1024,
    "modified_on": "2017-01-01T00:00:00Z"
  }
}

Worker Script error codes

Code	Description
10001	Unsupported or unexpected Content Type
10002	Unexpected internal server error
10003	Missing required URL parameter
10004	Malformed URL parameter
10006	Unparseable script body
10007	Resource not found (similar to HTTP 404)
10014	Internal error while attempting authorization checks
10015	The current account is not authorized to use workers
10018	Attempted to update a script where the e-tag does not match
10021	Script content failed validation checks, but was otherwise parseable
10023	Unauthorized access attempt
10027	Script body was too large

Worker Binding

A worker binding is a resource made available to a worker via a JavaScript variable name.

worker-binding

Object definitions

View properties and constraints defined on the object

Show definitions

worker-binding-list-bindings

GET List Bindings

List the bindings for a Workers script.

GET zones/:zone_identifier/workers/script/bindings

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/workers/script/bindings" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "name": "myBinding",
      "type": "kv_namespace",
      "namespace_id": "0f2ac74b498b48028cb68387c421e279"
    }
  ]
}

Worker Filters

Filters are basic patterns used to enable or disable workers that match requests.

worker-filters

Object definition

View properties and constraints defined on the object

Show definition

worker-filters-list-filters

GET List Filters

GET zones/:zone_id/workers/filters

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/workers/filters" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "9a7806061c88ada191ed06f989cc3dac",
      "pattern": "example.net/*",
      "enabled": true
    }
  ]
}

worker-filters-update-filter

PUT Update Filter

PUT zones/:zone_id/workers/filters/:filter_id

Required parameters

Name /type	Description /example	Constraints
pattern string	`"example.net/*"`
enabled boolean	`true`	valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/workers/filters/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"pattern":"example.net/*","enabled":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "pattern": "example.net/*",
    "enabled": true
  }
}

worker-filters-delete-filter

DELETE Delete Filter

DELETE zones/:zone_id/workers/filters/:filter_id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/workers/filters/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac"
  }
}

worker-filters-create-filter

POST Create Filter

POST zones/:zone_id/workers/filters

Required parameters

Name /type	Description /example	Constraints
pattern string	`"example.net/*"`
enabled boolean	`true`	valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/workers/filters" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"pattern":"example.net/*","enabled":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac"
  }
}

Worker Filters error codes

Code	Description
10001	Unsupported or unexpected Content Type
10002	Unexpected internal server error
10003	Missing required URL parameter
10004	Malformed URL parameter
10007	Resource not found (similar to HTTP 404)
10014	Internal error while attempting authorization checks
10015	The current account is not authorized to use workers
10020	Attempted to create a filter for a pattern that already exists
10022	Filter pattern was invalid
10023	Unauthorized access attempt
10026	Filter pattern was unparseable

Worker Script (Enterprise)

A Worker script is a single script that is executed on matching routes in the Cloudflare edge

worker-script-enterprise-

Object definition

View properties and constraints defined on the object

Show definition

worker-script-enterprise--upload-worker

PUT Upload Worker

Upload a worker, or a new version of a worker.

PUT accounts/:account_identifier/workers/scripts/:script_name

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/scripts/this-is_my_script-01" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/javascript" \
--data "addEventListener('fetch', event => { event.respondWith(fetch(event.request) }))"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "script": "addEventListener('fetch', event => { event.respondWith(fetch(event.request) }))",
    "etag": "ea95132c15732412d22c1476fa83f27a",
    "size": 1024,
    "modified_on": "2017-01-01T00:00:00Z"
  }
}

worker-script-enterprise--list-workers

GET List Workers

Fetch a list of uploaded workers.

GET accounts/:account_identifier/workers/scripts

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/scripts" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "this-is_my_script-01",
      "etag": "ea95132c15732412d22c1476fa83f27a",
      "created_on": "2017-01-01T00:00:00Z",
      "modified_on": "2017-01-01T00:00:00Z"
    }
  ]
}

worker-script-enterprise--download-worker

GET Download Worker

Fetch raw script content for your worker. Note this is the original script content, not JSON encoded.

GET accounts/:account_identifier/workers/scripts/:script_name

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/scripts/this-is_my_script-01" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Accept: application/javascript"

Response (example)

addEventListener('fetch', event => { event.respondWith(fetch(event.request) }))

worker-script-enterprise--delete-worker

DELETE Delete Worker

Delete your worker. This call has no response body on a successful delete.

DELETE accounts/:account_identifier/workers/scripts/:script_name

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/scripts/this-is_my_script-01" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

Worker Script (Enterprise) error codes

Code	Description
10001	Unsupported or unexpected Content Type
10002	Unexpected internal server error
10003	Missing required URL parameter
10004	Malformed URL parameter
10006	Unparseable script body
10007	Resource not found (similar to HTTP 404)
10014	Internal error while attempting authorization checks
10015	The current account is not authorized to use workers
10018	Attempted to update a script where the e-tag does not match
10021	Script content failed validation checks, but was otherwise parseable
10023	Unauthorized access attempt
10027	Script body was too large

Worker Routes (Enterprise)

Routes are basic patterns used to enable or disable workers that match requests.

worker-routes-enterprise-

Object definition

View properties and constraints defined on the object

Show definition

worker-routes-enterprise--create-route

POST Create Route

POST zones/:zone_id/workers/routes

Required parameters

Name /type	Description /example	Constraints
pattern string	`"example.net/*"`

Optional parameters

Name /type	Description /example	Constraints
script string	Name of the script to apply when the route is matched. The route is skipped when this is blank/missing. `"this-is_my_script-01"`	pattern: ^[a-z0-9_][a-z0-9-_]*$

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/workers/routes" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"pattern":"example.net/*","script":"this-is_my_script-01"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac"
  }
}

worker-routes-enterprise--list-routes

GET List Routes

GET zones/:zone_id/workers/routes

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/workers/routes" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "9a7806061c88ada191ed06f989cc3dac",
      "pattern": "example.net/*",
      "script": "this-is_my_script-01"
    }
  ]
}

worker-routes-enterprise--get-route

GET Get Route

GET zones/:zone_id/workers/routes/:route_id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/workers/routes/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "pattern": "example.net/*",
    "script": "this-is_my_script-01"
  }
}

worker-routes-enterprise--update-route

PUT Update Route

PUT zones/:zone_id/workers/routes/:route_id

Required parameters

Name /type	Description /example	Constraints
pattern string	`"example.net/*"`

Optional parameters

Name /type	Description /example	Constraints
script string	Name of the script to apply when the route is matched. The route is skipped when this is blank/missing. `"this-is_my_script-01"`	pattern: ^[a-z0-9_][a-z0-9-_]*$

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/workers/routes/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"pattern":"example.net/*","script":"this-is_my_script-01"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "pattern": "example.net/*",
    "script": "this-is_my_script-01"
  }
}

worker-routes-enterprise--delete-route

DELETE Delete Route

DELETE zones/:zone_id/workers/routes/:route_id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/workers/routes/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac"
  }
}

Worker Routes (Enterprise) error codes

Code	Description
10001	Unsupported or unexpected Content Type
10002	Unexpected internal server error
10003	Missing required URL parameter
10004	Malformed URL parameter
10007	Resource not found (similar to HTTP 404)
10014	Internal error while attempting authorization checks
10015	The current account is not authorized to use workers
10020	Attempted to create a route for a pattern that already exists
10022	Route pattern was invalid
10023	Unauthorized access attempt
10026	Route pattern was unparseable

Workers KV Namespace

A Namespace is a collection of key-value pairs stored in Workers KV.

workers-kv-namespace

Object definition

View properties and constraints defined on the object

Show definition

workers-kv-namespace-list-namespaces

GET List Namespaces

Returns the namespaces owned by an account

GET accounts/:account_identifier/storage/kv/namespaces

Optional parameters

Name /type	Description /example	Constraints
page number	Page number of paginated results `1`	default value: 1 min value:1
per_page number	Maximum number of results per page `20`	default value: 20 min value:5 max value:50

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/storage/kv/namespaces?page=1&per_page=20" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "0f2ac74b498b48028cb68387c421e279",
      "title": "My Own Namespace"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

workers-kv-namespace-create-a-namespace

POST Create a Namespace

Creates a namespace under the given title. A 400 is returned if the account already owns a namespace with this title. A namespace must be explicitly deleted to be replaced.

POST accounts/:account_identifier/storage/kv/namespaces

Required parameters

Name /type	Description /example	Constraints
title string	A human-readable string name for a Namespace. `"My Own Namespace"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/storage/kv/namespaces" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"title":"My Own Namespace"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "0f2ac74b498b48028cb68387c421e279",
    "title": "My Own Namespace"
  }
}

workers-kv-namespace-remove-a-namespace

DELETE Remove a Namespace

Deletes the namespace corresponding to the given ID.

DELETE accounts/:account_identifier/storage/kv/namespaces/:namespace_identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/storage/kv/namespaces/0f2ac74b498b48028cb68387c421e279" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": []
}

workers-kv-namespace-rename-a-namespace

PUT Rename a Namespace

Modifies a namespace's title.

PUT accounts/:account_identifier/storage/kv/namespaces/:namespace_identifier

Required parameters

Name /type	Description /example	Constraints
title string	A human-readable string name for a Namespace. `"My Own Namespace"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/storage/kv/namespaces/0f2ac74b498b48028cb68387c421e279" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"title":"My Own Namespace"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": []
}

workers-kv-namespace-list-a-namespace-s-keys

GET List a Namespace's Keys

Lists a namespace's keys.

GET accounts/:account_identifier/storage/kv/namespaces/:namespace_identifier/keys

Optional parameters

Name /type	Description /example	Constraints
limit number	The number of keys to return. The cursor attribute may be used to iterate over the next batch of keys if there are more than the limit. `1000`	default value: 1000 min value:10 max value:1000
cursor string	Opaque token indicating the position from which to continue when requesting the next set of records if the amount of list results was limited by the limit parameter. A valid value for the cursor can be obtained from the cursors object in the result_info structure. `"6Ck1la0VxJ0djhidm1MdX2FyDGxLKVeeHZZmORS_8XeSuhz9SjIJRaSa2lnsF01tQOHrfTGAP3R5X1Kv5iVUuMbNKhWNAXHOl6ePB0TUL8nw"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/storage/kv/namespaces/0f2ac74b498b48028cb68387c421e279/keys?limit=1000&cursor=6Ck1la0VxJ0djhidm1MdX2FyDGxLKVeeHZZmORS_8XeSuhz9SjIJRaSa2lnsF01tQOHrfTGAP3R5X1Kv5iVUuMbNKhWNAXHOl6ePB0TUL8nw" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "name": "My-Key",
      "expiration": 1577836800
    }
  ],
  "result_info": {
    "count": 1,
    "cursor": "6Ck1la0VxJ0djhidm1MdX2FyDGxLKVeeHZZmORS_8XeSuhz9SjIJRaSa2lnsF01tQOHrfTGAP3R5X1Kv5iVUuMbNKhWNAXHOl6ePB0TUL8nw"
  }
}

workers-kv-namespace-read-key-value-pair

GET Read key-value pair

Returns the value associated with the given key in the given namespace. Use URL-encoding to use special characters (e.g. :, !, %) in the key name. If the KV-pair is set to expire at some point, the expiration time as measured in seconds since the UNIX epoch will be returned in the "Expiration" response header.

GET accounts/:account_identifier/storage/kv/namespaces/:namespace_identifier/values/:key_name

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/storage/kv/namespaces/0f2ac74b498b48028cb68387c421e279/values/My-Key" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

"Some Value"

workers-kv-namespace-write-key-value-pair

PUT Write key-value pair

Write a value identified by a key. Use URL-encoding to use special characters (e.g. :, !, %) in the key name. Body should be the value to be stored. Existing values and expirations will be overwritten. If neither expiration nor expiration_ttl is specified, the key-value pair will never expire.

PUT accounts/:account_identifier/storage/kv/namespaces/:namespace_identifier/values/:key_name

Optional parameters

Name /type	Description /example	Constraints
expiration number	The time, measured in number of seconds since the UNIX epoch, at which the key should expire.
expiration_ttl number	The number of seconds for which the key should be visible before it expires. At least 60.

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/storage/kv/namespaces/0f2ac74b498b48028cb68387c421e279/values/My-Key" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: text/plain" \
     --data '{}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": []
}

workers-kv-namespace-write-multiple-key-value-pairs

PUT Write multiple key-value pairs

Write multiple keys and values at once. Body should be an array of up to 10,000 key-value pairs to be stored, along with optional expiration information. Existing values and expirations will be overwritten. If neither expiration nor expiration_ttl is specified, the key-value pair will never expire. The entire request size must be 100 megabytes or less.

PUT accounts/:account_identifier/storage/kv/namespaces/:namespace_identifier/bulk

Required parameters

Name /type	Description /example	Constraints
key string	A key's name. The name may be at most 2 kB. All printable, non-whitespace characters are valid. `"My-Key"`	max length: 2048
value string	A UTF-8 encoded string to be stored, up to 2 MB in length. `"Some string"`	max length: 2097152

Optional parameters

Name /type	Description /example	Constraints
expiration number	The time, measured in number of seconds since the UNIX epoch, at which the key should expire.
expiration_ttl number	The number of seconds for which the key should be visible before it expires. At least 60.

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/storage/kv/namespaces/0f2ac74b498b48028cb68387c421e279/bulk" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '[{"key":"My-Key","value":"Some string"}]'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": []
}

workers-kv-namespace-delete-key-value-pair

DELETE Delete key-value pair

Remove a KV pair from the Namespace. Use URL-encoding to use special characters (e.g. :, !, %) in the key name.

DELETE accounts/:account_identifier/storage/kv/namespaces/:namespace_identifier/values/:key_name

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/storage/kv/namespaces/0f2ac74b498b48028cb68387c421e279/values/My-Key" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": []
}

Workers KV Namespace error codes

Code	Description
10001	service temporarily unavailable
10002	missing CF-Ray header
10003	missing account public ID
10004	missing account tag
10005	URL parameter account tag does not match JWT account tag
10006	malformed account tag
10007	malformed page argument
10008	malformed per_page argument
10009	key not found
10010	malformed namespace
10011	malformed namespace ID
10012	malformed value
10013	namespace not found
10014	namespace already exists
10015	missing account internal ID
10016	malformed account internal ID
10017	not entitled to use this endpoint
10018	too many namespaces in this account
10019	missing title
10020	too many values in namespace
10021	this namespace does not support the list-keys endpoint
10022	too many requests
10023	illegal key name
10024	payload too large
10025	path does not exist
10026	not permitted
10027	invalid storage gateway worker version
10028	invalid limit argument
10029	invalid request
10030	key too long
10031	invalid authorization
10032	invalid tunnel type

Workers KV Analytics

Metrics on Workers KV usage.

workers-kv-analytics

Object definition

View properties and constraints defined on the object

Show definition

workers-kv-analytics-query-analytics

GET Query Analytics

Retrieves Workers KV metrics for the given account.

GET accounts/:account_identifier/storage/analytics

Optional parameters

Name /type Description /example Constraints

limit
integer

Limit number of returned metrics.

10000

since
string (date-time)

Start of time interval to query, defaults to 6 hours before request received.

"2019-01-02T02:20:00Z"

until
string (date-time)

End of time interval to query, defaults to current time.

"2019-01-02T03:20:00Z"

metrics
array

One or more metrics to compute.

[
  "requests",
  "readKiB"
]

An array with items in the following form:

Show definition »

dimensions
array

Can be used to break down the data by given attributes.

[
  "zoneName",
  "responseCode"
]

An array with items in the following form:

Show definition »

sort
array

Array of dimensions or metrics to sort by, each dimension/metric may be prefixed by - (descending) or + (ascending)

[
  "+requests",
  "-responseCode"
]

filters
string

Used to filter rows by one or more dimensions. Filters can be combined using OR and AND boolean logic. AND takes precedence over OR in all the expressions. The OR operator is defined using a comma (,) or OR keyword surrounded by whitespace. The AND operator is defined using a semicolon (;) or AND keyword surrounded by whitespace. Comparison options are:

Operator	Name	URL Encoded
==	Equals	%3D%3D
!=	Does not equals	!%3D
>	Greater Than	%3E
<	Less Than	%3C
>=	Greater than or equal to	%3E%3D
<=	Less than or equal to	%3C%3D

"zoneName==example.com AND responseCode!=200"

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/storage/analytics?limit=10000&since=2019-01-02T02:20:00Z&until=2019-01-02T03:20:00Z&metrics=requests,readKiB&dimensions=zoneName,responseCode&sort=+requests,-responseCode&filters=zoneName==example.com AND responseCode!=200" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "rows": 2,
    "data": [
      {
        "metrics": [
          [
            2,
            4
          ],
          [
            16,
            32
          ]
        ]
      }
    ],
    "data_lag": 0,
    "min": {
      "requests": 2,
      "readKiB": 16
    },
    "max": {
      "requests": 4,
      "readKiB": 32
    },
    "totals": {
      "requests": 6,
      "readKiB": 48
    },
    "query": {
      "limit": 10000,
      "since": "2019-01-02T02:20:00Z",
      "until": "2019-01-02T03:20:00Z",
      "metrics": [
        "requests",
        "readKiB"
      ],
      "dimensions": [
        "zoneName",
        "responseCode"
      ],
      "sort": [
        "+requests",
        "-responseCode"
      ],
      "filters": "zoneName==example.com AND responseCode!=200"
    }
  }
}

Workers KV Analytics error codes

Code	Description
10001	missing CF-Ray header
10002	missing account ID
10003	malformed account ID
10004	malformed query

Spectrum Applications

You can extend the power of Cloudflare's DDoS, TLS, and IP Firewall to your other TCP-based services.

spectrum-applications

Object definitions

View properties and constraints defined on the object

Show definitions

spectrum-applications-list-spectrum-applications

GET List Spectrum Applications

Retrieve a list of currently existing Spectrum Applications inside a zone.

GET zones/:zone/spectrum/apps

Optional parameters

Name /type	Description /example	Constraints
page number	Page number of paginated results. This parameter is required in order to use other pagination parameters. If included in the query, `result_info` will be present in the response. `1`	min value:1
per_page number	Maximum number of results per page `20`	default value: 20 min value:1
direction string	Direction to order results `"desc"`	default value: asc valid values: asc, desc
order string	Application field to order results by `"protocol"`	default value: dns valid values: protocol, app_id, created_on, modified_on, dns

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/spectrum/apps?page=1&per_page=20&direction=desc&order=protocol" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "ea95132c15732412d22c1476fa83f27a",
      "protocol": "tcp/22",
      "dns": {
        "type": "CNAME",
        "name": "ssh.example.com"
      },
      "origin_direct": [
        "tcp://192.0.2.1:22"
      ],
      "proxy_protocol": true,
      "ip_firewall": true,
      "tls": "full",
      "spp": true,
      "traffic_type": "direct",
      "created_on": "2014-01-02T02:20:00Z",
      "modified_on": "2014-01-02T02:20:00Z"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

spectrum-applications-create-spectrum-application

POST Create Spectrum Application

Create a new Spectrum Application from a configuration.

POST zones/:zone/spectrum/apps

Required parameters

Name /type	Description /example	Constraints
protocol string	Port configuration at Cloudflare’s edge. `"tcp/22"`
dns object	The name and type of DNS record for the Spectrum application. `{ "type": "CNAME", "name": "ssh.example.com" }` An object with the following properties: Show definition »
origin_direct array	A list of destination addresses to the origin. `[ "tcp://192.0.2.1:22" ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
proxy_protocol boolean	Enables Proxy Protocol v1 to the origin. See the developer documentation for implementation details. `true`	valid values: (true,false) notes: Only available for TCP applications.
ip_firewall boolean	Enables IP Access Rules for this application. `true`	valid values: (true,false) notes: Only available for TCP applications.
tls string	The type of TLS termination associated with the application. `"full"`	valid values: off, flexible, full, strict
spp boolean	Enables Cloudflare's Simple Proxy Protocol. Simple Proxy Protocol relays the client's original IP and port information to your origin. See the developer documentation for implementation details. `true`	default value: false valid values: (true,false) notes: Only available for UDP applications.

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/spectrum/apps" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"protocol":"tcp/22","dns":{"type":"CNAME","name":"ssh.example.com"},"origin_direct":["tcp://192.0.2.1:22"],"proxy_protocol":true,"ip_firewall":true,"tls":"full","spp":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "ea95132c15732412d22c1476fa83f27a",
    "protocol": "tcp/22",
    "dns": {
      "type": "CNAME",
      "name": "ssh.example.com"
    },
    "origin_direct": [
      "tcp://192.0.2.1:22"
    ],
    "proxy_protocol": true,
    "ip_firewall": true,
    "tls": "full",
    "spp": true,
    "traffic_type": "direct",
    "created_on": "2014-01-02T02:20:00Z",
    "modified_on": "2014-01-02T02:20:00Z"
  }
}

spectrum-applications-get-spectrum-application-configuration

GET Get Spectrum Application Configuration

Get the application configuration of a specific application inside a zone.

GET zones/:zone/spectrum/apps/:app_id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/spectrum/apps/ea95132c15732412d22c1476fa83f27a" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "ea95132c15732412d22c1476fa83f27a",
    "protocol": "tcp/22",
    "dns": {
      "type": "CNAME",
      "name": "ssh.example.com"
    },
    "origin_direct": [
      "tcp://192.0.2.1:22"
    ],
    "proxy_protocol": true,
    "ip_firewall": true,
    "tls": "full",
    "spp": true,
    "traffic_type": "direct",
    "created_on": "2014-01-02T02:20:00Z",
    "modified_on": "2014-01-02T02:20:00Z"
  }
}

spectrum-applications-update-spectrum-application-configuration

PUT Update Spectrum Application Configuration

Update a previously existing application's configuration.

PUT zones/:zone/spectrum/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
protocol string	Port configuration at Cloudflare’s edge. `"tcp/22"`
dns object	The name and type of DNS record for the Spectrum application. `{ "type": "CNAME", "name": "ssh.example.com" }` An object with the following properties: Show definition »
origin_direct array	A list of destination addresses to the origin. `[ "tcp://192.0.2.1:22" ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
proxy_protocol boolean	Enables Proxy Protocol v1 to the origin. See the developer documentation for implementation details. `true`	valid values: (true,false) notes: Only available for TCP applications.
ip_firewall boolean	Enables IP Access Rules for this application. `true`	valid values: (true,false) notes: Only available for TCP applications.
tls string	The type of TLS termination associated with the application. `"full"`	valid values: off, flexible, full, strict

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/spectrum/apps/ea95132c15732412d22c1476fa83f27a" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"protocol":"tcp/22","dns":{"type":"CNAME","name":"ssh.example.com"},"origin_direct":["tcp://192.0.2.1:22"],"proxy_protocol":true,"ip_firewall":true,"tls":"full"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "ea95132c15732412d22c1476fa83f27a",
    "protocol": "tcp/22",
    "dns": {
      "type": "CNAME",
      "name": "ssh.example.com"
    },
    "origin_direct": [
      "tcp://192.0.2.1:22"
    ],
    "proxy_protocol": true,
    "ip_firewall": true,
    "tls": "full",
    "spp": true,
    "traffic_type": "direct",
    "created_on": "2014-01-02T02:20:00Z",
    "modified_on": "2014-01-02T02:20:00Z"
  }
}

spectrum-applications-delete-spectrum-application

DELETE Delete Spectrum Application

Delete a previously existing application.

DELETE zones/:zone/spectrum/apps/:app_id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/spectrum/apps/ea95132c15732412d22c1476fa83f27a" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "ea95132c15732412d22c1476fa83f27a"
  }
}

Spectrum Applications error codes

Code	Description
10000	Unknown Error
10001	Unexpected Content Type
10002	Internal Server Error
10003	Missing Required URL Param
10004	Malformed URL Param
10005	JSON Parsing Error
10006	Resource Not Found
10007	Forbidden
11000	Invalid Origin Configuration
11002	Invalid Origin Address
11003	Invalid Edge Port
11004	Invalid DNS Configuration
11005	Proxy Protocol v1 Not Supported for non TCP Applications
11006	TLS Termination Not Supported for non TCP Applications
11007	Origin/Edge Transport Mismatch
11008	UDP Not Enabled
12000	No Address Available
13000	Protocol Not Found
13002	Protocol Not Available
14002	Port Conflict
1402	DNS Validation Error
81053	DNS Record Exists Error

Spectrum Analytics (Summary)

Summarized analytics data for Spectrum applications.

spectrum-analytics-summary-

Object definition

View properties and constraints defined on the object

Show definition

spectrum-analytics-summary--get-analytics-summary

GET Get Analytics Summary

Retrieves a list of summarised aggregate metrics over a given time period.

GET zones/:zone/spectrum/analytics/events/summary

Optional parameters

Name /type Description /example Constraints

metrics
array

One or more metrics to compute. Options are:

Metric	Name	Example	Unit
count	Count of total events	1000	Count
bytesIngress	Sum of ingress bytes	1000	Sum
bytesEgress	Sum of egress bytes	1000	Sum
durationAvg	Average connection duration	1.0	Time in milliseconds
durationMedian	Median connection duration	1.0	Time in milliseconds
duration90th	90th percentile connection duration	1.0	Time in milliseconds
duration99th	99th percentile connection duration	1.0	Time in milliseconds

[
  "count",
  "bytesIngress"
]

An array with items in the following form:

Show definition »

dimensions
array

Can be used to break down the data by given attributes. Options are:

Dimension	Name	Example
event	Connection Event	connect, progress, disconnect, originError, clientFiltered
appID	Application ID	40d67c87c6cd4b889a4fd57805225e85
coloName	Colo Name	SFO
ipVersion	IP version used by the client	4, 6

[
  "event",
  "appID"
]

An array with items in the following form:

Show definition »

filters
string

Operator	Name	URL Encoded
==	Equals	%3D%3D
!=	Does not equals	!%3D
>	Greater Than	%3E
<	Less Than	%3C
>=	Greater than or equal to	%3E%3D
<=	Less than or equal to	%3C%3D

"event==connect AND coloName!=SFO"

sort
array

The sort order for the result set; sort fields must be included in metrics or dimensions.

[
  "+count",
  "-bytesIngress"
]

since
string (date-time)

Start of time interval to query, defaults to until - 6 hours.

"2014-01-02T02:20:00Z"

until
string (date-time)

End of time interval to query, defaults to current time.

"2014-01-02T03:20:00Z"

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/spectrum/analytics/events/summary?metrics=count,bytesIngress&dimensions=event,appID&filters=event==connect AND coloName!=SFO&sort=+count,-bytesIngress&since=2014-01-02T02:20:00Z&until=2014-01-02T03:20:00Z" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "rows": 2,
    "data": [
      {
        "dimensions": [
          "connect",
          "42aea0b453934875a216920f1ec8f074"
        ],
        "metrics": [
          2,
          1
        ]
      },
      {
        "dimensions": [
          "disconnect",
          "42aea0b453934875a216920f1ec8f074"
        ],
        "metrics": [
          2,
          2
        ]
      }
    ],
    "totals": {
      "count": 4,
      "bytesIngress": 3
    },
    "min": {
      "count": 2,
      "bytesIngress": 1
    },
    "max": {
      "count": 2,
      "bytesIngress": 2
    },
    "data_lag": 60,
    "query": {
      "metrics": [
        "count",
        "bytesIngress"
      ],
      "dimensions": [
        "event",
        "appID"
      ],
      "filters": "event==connect AND coloName!=SFO",
      "sort": [
        {
          "Id": "count",
          "Desc": false
        },
        {
          "Id": "bytesIngress",
          "Desc": true
        }
      ],
      "since": "2014-01-02T02:20:00Z",
      "until": "2014-01-02T03:20:00Z",
      "limit": 10000
    }
  }
}

Spectrum Analytics (By Time)

Analytics data for Spectrum applications grouped by time interval.

spectrum-analytics-by-time-

Object definition

View properties and constraints defined on the object

Show definition

spectrum-analytics-by-time--get-analytics-by-time

GET Get Analytics By Time

Retrieves a list of aggregate metrics grouped by time interval.

GET zones/:zone/spectrum/analytics/events/bytime

Optional parameters

Name /type Description /example Constraints

metrics
array

One or more metrics to compute. Options are:

Metric	Name	Example	Unit
count	Count of total events	1000	Count
bytesIngress	Sum of ingress bytes	1000	Sum
bytesEgress	Sum of egress bytes	1000	Sum
durationAvg	Average connection duration	1.0	Time in milliseconds
durationMedian	Median connection duration	1.0	Time in milliseconds
duration90th	90th percentile connection duration	1.0	Time in milliseconds
duration99th	99th percentile connection duration	1.0	Time in milliseconds

[
  "count",
  "bytesIngress"
]

An array with items in the following form:

Show definition »

dimensions
array

Can be used to break down the data by given attributes. Options are:

Dimension	Name	Example
event	Connection Event	connect, progress, disconnect, originError, clientFiltered
appID	Application ID	40d67c87c6cd4b889a4fd57805225e85
coloName	Colo Name	SFO
ipVersion	IP version used by the client	4, 6

[
  "event",
  "appID"
]

An array with items in the following form:

Show definition »

filters
string

Operator	Name	URL Encoded
==	Equals	%3D%3D
!=	Does not equals	!%3D
>	Greater Than	%3E
<	Less Than	%3C
>=	Greater than or equal to	%3E%3D
<=	Less than or equal to	%3C%3D

"event==connect AND coloName!=SFO"

sort
array

The sort order for the result set; sort fields must be included in metrics or dimensions.

[
  "+count",
  "-bytesIngress"
]

since
string (date-time)

Start of time interval to query, defaults to until - 6 hours.

"2014-01-02T02:20:00Z"

until
string (date-time)

End of time interval to query, defaults to current time.

"2014-01-02T03:20:00Z"

time_delta
string

Used to select time series resolution.

"minute"

valid values: year, quarter, month, week, day, hour, dekaminute, minute

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/spectrum/analytics/events/bytime?metrics=count,bytesIngress&dimensions=event,appID&filters=event==connect AND coloName!=SFO&sort=+count,-bytesIngress&since=2014-01-02T02:20:00Z&until=2014-01-02T03:20:00Z&time_delta=minute" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "rows": 2,
    "data": [
      {
        "dimensions": [
          "connect",
          "42aea0b453934875a216920f1ec8f074"
        ],
        "metrics": [
          [
            1,
            2
          ],
          [
            0,
            0
          ]
        ]
      },
      {
        "dimensions": [
          "disconnect",
          "42aea0b453934875a216920f1ec8f074"
        ],
        "metrics": [
          [
            3,
            1
          ],
          [
            1,
            1
          ]
        ]
      }
    ],
    "totals": {
      "count": 5,
      "bytesIngress": 4
    },
    "min": {
      "count": 0,
      "bytesIngress": 0
    },
    "max": {
      "count": 3,
      "bytesIngress": 2
    },
    "data_lag": 60,
    "time_intervals": [
      [
        "2018-10-01T12:31:00Z",
        "2018-10-01T12:31:59Z"
      ],
      [
        "2018-10-01T12:39:00Z",
        "2018-10-01T12:39:59Z"
      ]
    ],
    "query": {
      "metrics": [
        "count",
        "bytesIngress"
      ],
      "dimensions": [
        "event",
        "appID"
      ],
      "filters": "event==connect AND coloName!=SFO",
      "sort": [
        {
          "Id": "count",
          "Desc": false
        },
        {
          "Id": "bytesIngress",
          "Desc": true
        }
      ],
      "since": "2014-01-02T02:20:00Z",
      "until": "2014-01-02T03:20:00Z",
      "time_delta": "minute",
      "limit": 10000
    }
  }
}

Spectrum Aggregate Analytics

Aggregated Analytics for Spectrum in real time.

spectrum-aggregate-analytics

Object definitions

View properties and constraints defined on the object

Show definitions

spectrum-aggregate-analytics-get-current-aggregate-analytics

GET Get Current Aggregate Analytics

Retrieves analytics aggregated from the last minute of usage on Spectrum Applications underneath a given zone.

GET zones/:zone/spectrum/analytics/aggregate/current

Optional parameters

Name /type	Description /example	Constraints
coloName string	Co-location Identifier. `"PDX"`	max length: 3
appID string	Comma-delimited list of Spectrum Application Id(s). If provided, the response will be limited to Spectrum Application Id(s) that match. `"ea95132c15732412d22c1476fa83f27a,d122c5f4bb71e25cc9e86ab43b142e2f"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/spectrum/analytics/aggregate/current?coloName=PDX&appID=ea95132c15732412d22c1476fa83f27a,d122c5f4bb71e25cc9e86ab43b142e2f" \
     -H "X-Auth-Email: [email protected]com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "appID": "ea95132c15732412d22c1476fa83f27a",
      "bytesIngress": 500,
      "bytesEgress": 500,
      "connections": 10,
      "durationAvg": 10000
    }
  ]
}

Page Rules for a Zone

A rule describing target patterns for requests and actions to perform on matching requests

page-rules-for-a-zone

Object definition

View properties and constraints defined on the object

Show definition

page-rules-for-a-zone-list-page-rules

GET List Page Rules permission needed: #zone:read
free
pro
business
enterprise

GET zones/:zone_identifier/pagerules

Optional parameters

Name /type	Description /example	Constraints
status string	Status of the page rule `"active"`	default value: disabled valid values: active, disabled
order string	Field to order page rules by `"status"`	default value: priority valid values: status, priority
direction string	Direction to order page rules `"desc"`	default value: 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/023e105f4ecef8ad9ca31a8372d0c353/pagerules?status=active&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",
      "targets": [
        {
          "target": "url",
          "constraint": {
            "operator": "matches",
            "value": "*example.com/images/*"
          }
        }
      ],
      "actions": [
        {
          "id": "always_online",
          "value": "on"
        }
      ],
      "priority": 1,
      "status": "active",
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "created_on": "2014-01-01T05:20:00.12345Z"
    }
  ]
}

page-rules-for-a-zone-create-page-rule

POST Create Page Rule permission needed: #zone:edit
free
pro
business
enterprise

POST zones/:zone_identifier/pagerules

Required parameters

Name /type	Description /example	Constraints
targets array	Targets to evaluate on a request `[ { "target": "url", "constraint": { "operator": "matches", "value": "example.com/images/" } } ]` An array with items in the following form: Show definition »
actions array	The set of actions to perform if the targets of this rule match the request. Actions can redirect the url to another url or override settings (but not both) `[ { "id": "always_online", "value": "on" } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
priority integer	A number that indicates the preference for a page rule over another. In the case where you may have a catch-all page rule (e.g., #1: '/images/') but want a rule that is more specific to take precedence (e.g., #2: '/images/special/'), you'll want to specify a higher priority on the latter (#2) so it will override the first. `1`	default value: 1
status string	Status of the page rule `"active"`	default value: disabled valid values: active, disabled

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/pagerules" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"targets":[{"target":"url","constraint":{"operator":"matches","value":"*example.com/images/*"}}],"actions":[{"id":"always_online","value":"on"}],"priority":1,"status":"active"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "targets": [
      {
        "target": "url",
        "constraint": {
          "operator": "matches",
          "value": "*example.com/images/*"
        }
      }
    ],
    "actions": [
      {
        "id": "always_online",
        "value": "on"
      }
    ],
    "priority": 1,
    "status": "active",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "created_on": "2014-01-01T05:20:00.12345Z"
  }
}

page-rules-for-a-zone-page-rule-details

GET Page Rule Details permission needed: #zone:read
free
pro
business
enterprise

GET zones/:zone_identifier/pagerules/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/pagerules/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",
    "targets": [
      {
        "target": "url",
        "constraint": {
          "operator": "matches",
          "value": "*example.com/images/*"
        }
      }
    ],
    "actions": [
      {
        "id": "always_online",
        "value": "on"
      }
    ],
    "priority": 1,
    "status": "active",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "created_on": "2014-01-01T05:20:00.12345Z"
  }
}

page-rules-for-a-zone-update-page-rule

PUT Update Page Rule permission needed: #zone:edit
free
pro
business
enterprise

Replace a page rule. The final rule will exactly match the data passed with this request.

PUT zones/:zone_identifier/pagerules/:identifier

Required parameters

Name /type	Description /example	Constraints
targets array	Targets to evaluate on a request `[ { "target": "url", "constraint": { "operator": "matches", "value": "example.com/images/" } } ]` An array with items in the following form: Show definition »
actions array	The set of actions to perform if the targets of this rule match the request. Actions can redirect the url to another url or override settings (but not both) `[ { "id": "always_online", "value": "on" } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
priority integer	A number that indicates the preference for a page rule over another. In the case where you may have a catch-all page rule (e.g., #1: '/images/') but want a rule that is more specific to take precedence (e.g., #2: '/images/special/'), you'll want to specify a higher priority on the latter (#2) so it will override the first. `1`	default value: 1
status string	Status of the page rule `"active"`	default value: disabled valid values: active, disabled

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/pagerules/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"targets":[{"target":"url","constraint":{"operator":"matches","value":"*example.com/images/*"}}],"actions":[{"id":"always_online","value":"on"}],"priority":1,"status":"active"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "targets": [
      {
        "target": "url",
        "constraint": {
          "operator": "matches",
          "value": "*example.com/images/*"
        }
      }
    ],
    "actions": [
      {
        "id": "always_online",
        "value": "on"
      }
    ],
    "priority": 1,
    "status": "active",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "created_on": "2014-01-01T05:20:00.12345Z"
  }
}

page-rules-for-a-zone-edit-page-rule

PATCH Edit Page Rule permission needed: #zone:edit
free
pro
business
enterprise

PATCH zones/:zone_identifier/pagerules/:identifier

Optional parameters

Name /type	Description /example	Constraints
targets array	Targets to evaluate on a request `[ { "target": "url", "constraint": { "operator": "matches", "value": "example.com/images/" } } ]` An array with items in the following form: Show definition »
actions array	The set of actions to perform if the targets of this rule match the request. Actions can redirect the url to another url or override settings (but not both) `[ { "id": "always_online", "value": "on" } ]` An array with items in the following form: Show definition »
priority integer	A number that indicates the preference for a page rule over another. In the case where you may have a catch-all page rule (e.g., #1: '/images/') but want a rule that is more specific to take precedence (e.g., #2: '/images/special/'), you'll want to specify a higher priority on the latter (#2) so it will override the first. `1`	default value: 1
status string	Status of the page rule `"active"`	default value: disabled valid values: active, disabled

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/pagerules/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"targets":[{"target":"url","constraint":{"operator":"matches","value":"*example.com/images/*"}}],"actions":[{"id":"always_online","value":"on"}],"priority":1,"status":"active"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "targets": [
      {
        "target": "url",
        "constraint": {
          "operator": "matches",
          "value": "*example.com/images/*"
        }
      }
    ],
    "actions": [
      {
        "id": "always_online",
        "value": "on"
      }
    ],
    "priority": 1,
    "status": "active",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "created_on": "2014-01-01T05:20:00.12345Z"
  }
}

page-rules-for-a-zone-delete-page-rule

DELETE Delete Page Rule permission needed: #zone:edit
free
pro
business
enterprise

DELETE zones/:zone_identifier/pagerules/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/pagerules/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"
  }
}

Available Page Rules for a Zone

A rule describing target patterns for requests and actions to perform on matching requests

available-page-rules-for-a-zone

Object definition

View properties and constraints defined on the object

Show definition

available-page-rules-for-a-zone-list-available-page-rule-setting

GET List Available Page rule setting permission needed: #zone:read
free
pro
business
enterprise

GET zones/:zone_identifier/pagerules/settings

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/pagerules/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",
      "properties": [
        {
          "name": "value",
          "type": "toggle"
        }
      ]
    },
    {
      "id": "browser_cache_ttl",
      "properties": [
        {
          "name": "value",
          "type": "range",
          "min": 1800,
          "max": 31536000,
          "suggested_values": [
            1800,
            3600,
            7200,
            10800,
            14400,
            18000,
            28800,
            43200,
            57600,
            72000,
            86400,
            172800,
            259200,
            345600,
            432000,
            691200,
            1382400,
            2073600,
            2678400,
            5356800,
            16070400,
            31536000
          ]
        }
      ]
    },
    {
      "id": "browser_check",
      "properties": [
        {
          "name": "value",
          "type": "toggle"
        }
      ]
    },
    {
      "id": "cache_deception_armor",
      "properties": [
        {
          "name": "value",
          "type": "toggle"
        }
      ]
    },
    {
      "id": "cache_level",
      "properties": [
        {
          "name": "value",
          "type": "select",
          "multiple": false,
          "choices": [
            "bypass",
            "basic",
            "simplified",
            "aggressive",
            "cache_everything"
          ]
        }
      ]
    },
    {
      "id": "disable_apps",
      "properties": []
    },
    {
      "id": "disable_performance",
      "properties": []
    },
    {
      "id": "disable_security",
      "properties": []
    },
    {
      "id": "edge_cache_ttl",
      "properties": [
        {
          "name": "value",
          "type": "range",
          "min": 7200,
          "max": 2419200,
          "suggested_values": [
            7200,
            10800,
            14400,
            18000,
            28800,
            43200,
            57600,
            72000,
            86400,
            172800,
            259200,
            345600,
            432000,
            518400,
            604800,
            1209600,
            2419200
          ]
        }
      ]
    },
    {
      "id": "email_obfuscation",
      "properties": [
        {
          "name": "value",
          "type": "toggle"
        }
      ]
    },
    {
      "id": "forwarding_url",
      "properties": [
        {
          "name": "status_code",
          "type": "choice",
          "multiple": false,
          "choices": [
            301,
            302
          ]
        },
        {
          "name": "url",
          "type": "forwardingUrl"
        }
      ]
    },
    {
      "id": "ip_geolocation",
      "properties": [
        {
          "name": "value",
          "type": "toggle"
        }
      ]
    },
    {
      "id": "minify",
      "properties": [
        {
          "name": "value",
          "type": "select",
          "multiple": true,
          "allowEmpty": true,
          "choices": [
            "html",
            "css",
            "js"
          ]
        }
      ]
    },
    {
      "id": "explicit_cache_control",
      "properties": [
        {
          "name": "value",
          "type": "toggle"
        }
      ]
    },
    {
      "id": "rocket_loader",
      "properties": [
        {
          "name": "value",
          "type": "toggle"
        }
      ]
    },
    {
      "id": "security_level",
      "properties": [
        {
          "name": "value",
          "type": "select",
          "multiple": false,
          "choices": [
            "essentially_off",
            "low",
            "medium",
            "high",
            "under_attack"
          ]
        }
      ]
    },
    {
      "id": "server_side_exclude",
      "properties": [
        {
          "name": "value",
          "type": "toggle"
        }
      ]
    },
    {
      "id": "ssl",
      "properties": [
        {
          "name": "value",
          "type": "choice",
          "multiple": false,
          "choices": [
            "off",
            "flexible",
            "full",
            "strict"
          ]
        }
      ]
    }
  ]
}

Rate Limits for a Zone

Documentation for Cloudflare Rate Limits

rate-limits-for-a-zone

Object definition

View properties and constraints defined on the object

Show definition

rate-limits-for-a-zone-list-rate-limits

GET List Rate Limits
free
pro
business
enterprise

List the rate limits on a zone.

GET zones/:zone_identifier/rate_limits

Optional parameters

Name /type	Description /example	Constraints
page number	Page number of paginated results `1`	default value: 1 min value:1
per_page number	Maximum number of results per page. This can only be provided as 1 or in multiples of 5 such as 5, 10, 15 or 20 `20`	default value: 20 min value:1 max value:1000

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rate_limits?page=1&per_page=20" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "372e67954025e0ba6aaa6d586b9e0b59",
      "disabled": false,
      "description": "Prevent multiple login failures to mitigate brute force attacks",
      "match": {
        "request": {
          "methods": [
            "GET",
            "POST"
          ],
          "schemes": [
            "HTTP",
            "HTTPS"
          ],
          "url": "*.example.org/path*"
        },
        "response": {},
        "headers": [
          {
            "name": "Cf-Cache-Status",
            "op": "ne",
            "value": "HIT"
          }
        ]
      },
      "bypass": [
        {
          "name": "url",
          "value": "api.example.com/*"
        }
      ],
      "threshold": 60,
      "period": 900,
      "action": {
        "mode": "challenge",
        "timeout": 86400,
        "response": {
          "content_type": "text/xml",
          "body": "<error>This request has been rate-limited.</error>"
        }
      }
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

rate-limits-for-a-zone-create-rate-limit

POST Create Rate Limit
free
pro
business
enterprise

Create a new rate limit for a zone. See the record object definitions for required attributes for each record type

POST zones/:zone_identifier/rate_limits

Required parameters

Name /type	Description /example	Constraints
match object	Determines which traffic the rate limit counts towards the threshold `{ "request": { "methods": [ "GET", "POST" ], "schemes": [ "HTTP", "HTTPS" ], "url": ".example.org/path" }, "response": {}, "headers": [ { "name": "Cf-Cache-Status", "op": "ne", "value": "HIT" } ] }` One of the following: Show definition »
threshold number	The threshold that triggers the rate limit mitigations, combine with period. i.e. threshold per period `60`	min value:1
period number	The time in seconds to count matching traffic. If the count exceeds threshold within this period the action will be performed `900`	min value:1 max value:86400
action object	The action to be performed when the threshold of matched traffic within the period defined is exceeded `{ "mode": "challenge", "timeout": 86400, "response": { "content_type": "text/xml", "body": "<error>This request has been rate-limited.</error>" } }` Any of the following: Show definition »

Optional parameters

Name /type	Description /example	Constraints
id string	Ratelimit identifier `"372e67954025e0ba6aaa6d586b9e0b59"`	max length: 32 read only
disabled boolean	Whether this ratelimit is currently disabled `false`	valid values: (true,false)
description string	A note that you can use to describe the reason for a rate limit. This value is sanitized and all tags are removed `"Prevent multiple login failures to mitigate brute force attacks"`	max length: 1024
bypass array	Criteria that would allow the rate limit to be bypassed, for example to express that you shouldn't apply a rate limit to a given set of URLs `[ { "name": "url", "value": "api.example.com/*" } ]` An array with items in the following form: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rate_limits" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"372e67954025e0ba6aaa6d586b9e0b59","disabled":false,"description":"Prevent multiple login failures to mitigate brute force attacks","match":{"request":{"methods":["GET","POST"],"schemes":["HTTP","HTTPS"],"url":"*.example.org/path*"},"response":{},"headers":[{"name":"Cf-Cache-Status","op":"ne","value":"HIT"}]},"bypass":[{"name":"url","value":"api.example.com/*"}],"threshold":60,"period":900,"action":{"mode":"challenge","timeout":86400,"response":{"content_type":"text/xml","body":"<error>This request has been rate-limited.</error>"}}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b59",
    "disabled": false,
    "description": "Prevent multiple login failures to mitigate brute force attacks",
    "match": {
      "request": {
        "methods": [
          "GET",
          "POST"
        ],
        "schemes": [
          "HTTP",
          "HTTPS"
        ],
        "url": "*.example.org/path*"
      },
      "response": {},
      "headers": [
        {
          "name": "Cf-Cache-Status",
          "op": "ne",
          "value": "HIT"
        }
      ]
    },
    "bypass": [
      {
        "name": "url",
        "value": "api.example.com/*"
      }
    ],
    "threshold": 60,
    "period": 900,
    "action": {
      "mode": "challenge",
      "timeout": 86400,
      "response": {
        "content_type": "text/xml",
        "body": "<error>This request has been rate-limited.</error>"
      }
    }
  }
}

rate-limits-for-a-zone-rate-limit-details

GET Rate Limit Details
free
pro
business
enterprise

GET zones/:zone_identifier/rate_limits/:id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rate_limits/372e67954025e0ba6aaa6d586b9e0b59" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b59",
    "disabled": false,
    "description": "Prevent multiple login failures to mitigate brute force attacks",
    "match": {
      "request": {
        "methods": [
          "GET",
          "POST"
        ],
        "schemes": [
          "HTTP",
          "HTTPS"
        ],
        "url": "*.example.org/path*"
      },
      "response": {},
      "headers": [
        {
          "name": "Cf-Cache-Status",
          "op": "ne",
          "value": "HIT"
        }
      ]
    },
    "bypass": [
      {
        "name": "url",
        "value": "api.example.com/*"
      }
    ],
    "threshold": 60,
    "period": 900,
    "action": {
      "mode": "challenge",
      "timeout": 86400,
      "response": {
        "content_type": "text/xml",
        "body": "<error>This request has been rate-limited.</error>"
      }
    }
  }
}

rate-limits-for-a-zone-update-rate-limit

PUT Update Rate Limit
free
pro
business
enterprise

PUT zones/:zone_identifier/rate_limits/:id

Required parameters

Name /type	Description /example	Constraints
id string	Ratelimit identifier `"372e67954025e0ba6aaa6d586b9e0b59"`	max length: 32 read only
match object	Determines which traffic the rate limit counts towards the threshold `{ "request": { "methods": [ "GET", "POST" ], "schemes": [ "HTTP", "HTTPS" ], "url": ".example.org/path" }, "response": {}, "headers": [ { "name": "Cf-Cache-Status", "op": "ne", "value": "HIT" } ] }` One of the following: Show definition »
threshold number	The threshold that triggers the rate limit mitigations, combine with period. i.e. threshold per period `60`	min value:1
period number	The time in seconds to count matching traffic. If the count exceeds threshold within this period the action will be performed `900`	min value:1 max value:86400
action object	The action to be performed when the threshold of matched traffic within the period defined is exceeded `{ "mode": "challenge", "timeout": 86400, "response": { "content_type": "text/xml", "body": "<error>This request has been rate-limited.</error>" } }` Any of the following: Show definition »

Optional parameters

Name /type	Description /example	Constraints
disabled boolean	Whether this ratelimit is currently disabled `false`	valid values: (true,false)
description string	A note that you can use to describe the reason for a rate limit. This value is sanitized and all tags are removed `"Prevent multiple login failures to mitigate brute force attacks"`	max length: 1024
bypass array	Criteria that would allow the rate limit to be bypassed, for example to express that you shouldn't apply a rate limit to a given set of URLs `[ { "name": "url", "value": "api.example.com/*" } ]` An array with items in the following form: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rate_limits/372e67954025e0ba6aaa6d586b9e0b59" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"372e67954025e0ba6aaa6d586b9e0b59","disabled":false,"description":"Prevent multiple login failures to mitigate brute force attacks","match":{"request":{"methods":["GET","POST"],"schemes":["HTTP","HTTPS"],"url":"*.example.org/path*"},"response":{},"headers":[{"name":"Cf-Cache-Status","op":"ne","value":"HIT"}]},"bypass":[{"name":"url","value":"api.example.com/*"}],"threshold":60,"period":900,"action":{"mode":"challenge","timeout":86400,"response":{"content_type":"text/xml","body":"<error>This request has been rate-limited.</error>"}}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b59",
    "disabled": false,
    "description": "Prevent multiple login failures to mitigate brute force attacks",
    "match": {
      "request": {
        "methods": [
          "GET",
          "POST"
        ],
        "schemes": [
          "HTTP",
          "HTTPS"
        ],
        "url": "*.example.org/path*"
      },
      "response": {},
      "headers": [
        {
          "name": "Cf-Cache-Status",
          "op": "ne",
          "value": "HIT"
        }
      ]
    },
    "bypass": [
      {
        "name": "url",
        "value": "api.example.com/*"
      }
    ],
    "threshold": 60,
    "period": 900,
    "action": {
      "mode": "challenge",
      "timeout": 86400,
      "response": {
        "content_type": "text/xml",
        "body": "<error>This request has been rate-limited.</error>"
      }
    }
  }
}

rate-limits-for-a-zone-delete-rate-limit

DELETE Delete Rate Limit
free
pro
business
enterprise

DELETE zones/:zone_identifier/rate_limits/:id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rate_limits/372e67954025e0ba6aaa6d586b9e0b59" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b59"
  }
}

Rate Limits for a Zone error codes

Code	Description
10000	Invalid user
10001	Rate limit not found
10002	Rate limit not unique (edit the existing rather than adding a new)
10004	Invalid data submitted
10006	Auth missing
10007	Auth corrupt
10008	Auth expired
10009	Unauthorized
10010	Time param not valid
10011	Pagination results in empty page
10012	URL Param incorrect format
10013	Patch values not valid
10014	Patch operation not valid
10015	Patch value not valid for given context
10016	Patch not valid

User-level Firewall Access Rule

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

user-level-firewall-access-rule

Object definition

View properties and constraints defined on the object

Show definition

user-level-firewall-access-rule-list-access-rules

GET List Access Rules
free
pro
business
enterprise

Search, sort, and filter IP/country access rules

GET user/firewall/access_rules/rules

Optional parameters

Name /type	Description /example	Constraints
notes string	Search in the access rules by notes. `"my note"`	notes: Matching any string within previously created access rules with the notes. For example, access rules with notes 'Attack 26/02' & 'Attack 27/02' would both match string 'attack'. Search is not case sensitive.
mode string	The action to apply to a matched request `"challenge"`	valid values: block, challenge, whitelist, js_challenge
match string	Whether to match all search requirements or at least one (any) `"all"`	default value: all valid values: any, all
configuration.target string	Search rules by target `"ip"`	valid values: ip, ip_range, asn, country
order string	Field to order rules by `"mode"`	valid values: configuration.target, configuration.value, mode
page number	Page number of paginated results `1`	default value: 1 min value:1
per_page number	Maximum number of results per page. This can only be provided as 1 or in multiples of 5 such as 5, 10, 15 or 20 `20`	default value: 20 min value:1 max value:1000
configuration.value string	Search by IP, range, or country code `"198.51.100.4"`	notes: IP is a single IPv4 address. IP range has a subnet of /16 or /24. Country code is an ISO 2-letter country code.
direction string	Direction to order rules `"desc"`	valid values: asc, desc

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/user/firewall/access_rules/rules?page=1&per_page=20&mode=challenge&configuration.target=ip&configuration.value=198.51.100.4&notes=my note&match=all&order=mode&direction=desc" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "92f17202ed8bd63d69a66b86a49a8f6b",
      "notes": "This rule is on because of an event that occured on date X",
      "allowed_modes": [
        "whitelist",
        "block",
        "challenge",
        "js_challenge"
      ],
      "mode": "challenge",
      "configuration": {
        "target": "ip",
        "value": "198.51.100.4"
      },
      "created_on": "2014-01-01T05:20:00.12345Z",
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "scope": {
        "id": "7c5dae5552338874e5053f2534d2767a",
        "email": "[email protected]",
        "type": "user"
      }
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

user-level-firewall-access-rule-create-access-rule

POST Create Access Rule
free
pro
business
enterprise

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, js_challenge
configuration object	Rule configuration `{ "target": "ip", "value": "198.51.100.4" }` One of the following: Show definition » Show definition » Show definition » Show definition »

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":"198.51.100.4"},"notes":"This rule is on because of an event that occured on date X"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "92f17202ed8bd63d69a66b86a49a8f6b",
    "notes": "This rule is on because of an event that occured on date X",
    "allowed_modes": [
      "whitelist",
      "block",
      "challenge",
      "js_challenge"
    ],
    "mode": "challenge",
    "configuration": {
      "target": "ip",
      "value": "198.51.100.4"
    },
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "scope": {
      "id": "7c5dae5552338874e5053f2534d2767a",
      "email": "[email protected]",
      "type": "user"
    }
  }
}

user-level-firewall-access-rule-edit-access-rule

PATCH Edit Access Rule
free
pro
business
enterprise

Edit rule state and/or note. 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, js_challenge
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/92f17202ed8bd63d69a66b86a49a8f6b" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"mode":"challenge","notes":"This rule is on because of an event that occured on date X"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "92f17202ed8bd63d69a66b86a49a8f6b",
    "notes": "This rule is on because of an event that occured on date X",
    "allowed_modes": [
      "whitelist",
      "block",
      "challenge",
      "js_challenge"
    ],
    "mode": "challenge",
    "configuration": {
      "target": "ip",
      "value": "198.51.100.4"
    },
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "scope": {
      "id": "7c5dae5552338874e5053f2534d2767a",
      "email": "[email protected]",
      "type": "user"
    }
  }
}

user-level-firewall-access-rule-delete-access-rule

DELETE Delete Access Rule
free
pro
business
enterprise

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/92f17202ed8bd63d69a66b86a49a8f6b" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "92f17202ed8bd63d69a66b86a49a8f6b"
  }
}

Account-level Firewall access rule

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

account-level-firewall-access-rule

Object definition

View properties and constraints defined on the object

Show definition

account-level-firewall-access-rule-list-access-rules

GET List Access Rules permission needed: #waf:read
free
pro
business
enterprise

Search, sort, and filter IP/country access rules

GET accounts/:account_identifier/firewall/access_rules/rules

Optional parameters

Name /type	Description /example	Constraints
notes string	Search in the access rules by notes. `"my note"`	notes: Matching any string within previously created access rules with the notes. For example, access rules with notes 'Attack 26/02' & 'Attack 27/02' would both match string 'attack'. Search is not case sensitive.
mode string	The action to apply to a matched request `"challenge"`	valid values: block, challenge, whitelist, js_challenge
match string	Whether to match all search requirements or at least one (any) `"all"`	default value: all valid values: any, all
configuration.target string	Search rules by target `"ip"`	valid values: ip, ip_range, asn, country
order string	Field to order rules by `"mode"`	valid values: configuration.target, configuration.value, mode
page number	Page number of paginated results `1`	default value: 1 min value:1
per_page number	Maximum number of results per page. This can only be provided as 1 or in multiples of 5 such as 5, 10, 15 or 20 `20`	default value: 20 min value:1 max value:1000
configuration.value string	Search by IP, range, or country code `"198.51.100.4"`	notes: IP is a single IPv4 address. IP range has a subnet of /16 or /24. Country code is an ISO 2-letter country code.
direction string	Direction to order rules `"desc"`	valid values: asc, desc

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/firewall/access_rules/rules?page=1&per_page=20&mode=challenge&configuration.target=ip&configuration.value=198.51.100.4&notes=my note&match=all&order=mode&direction=desc" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "92f17202ed8bd63d69a66b86a49a8f6b",
      "notes": "This rule is on because of an event that occured on date X",
      "allowed_modes": [
        "whitelist",
        "block",
        "challenge",
        "js_challenge"
      ],
      "mode": "challenge",
      "configuration": {
        "target": "ip",
        "value": "198.51.100.4"
      },
      "created_on": "2014-01-01T05:20:00.12345Z",
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "scope": {
        "id": "7c5dae5552338874e5053f2534d2767a",
        "email": "[email protected]",
        "type": "user"
      }
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

account-level-firewall-access-rule-create-access-rule

POST Create Access Rule permission needed: #waf:edit
free
pro
business
enterprise

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

POST accounts/:account_identifier/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, js_challenge
configuration object	Rule configuration `{ "target": "ip", "value": "198.51.100.4" }` One of the following: Show definition » Show definition » Show definition » Show definition »

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/accounts/01a7362d577a6c3019a474fd6f485823/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":"198.51.100.4"},"notes":"This rule is on because of an event that occured on date X"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "92f17202ed8bd63d69a66b86a49a8f6b",
    "notes": "This rule is on because of an event that occured on date X",
    "allowed_modes": [
      "whitelist",
      "block",
      "challenge",
      "js_challenge"
    ],
    "mode": "challenge",
    "configuration": {
      "target": "ip",
      "value": "198.51.100.4"
    },
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "scope": {
      "id": "7c5dae5552338874e5053f2534d2767a",
      "email": "[email protected]",
      "type": "user"
    }
  }
}

account-level-firewall-access-rule-access-rule-details

GET Access Rule Details permission needed: #waf:read
free
pro
business
enterprise

Get the details of an access rule

GET accounts/:account_identifier/firewall/access_rules/rules/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/firewall/access_rules/rules/92f17202ed8bd63d69a66b86a49a8f6b" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "92f17202ed8bd63d69a66b86a49a8f6b",
    "notes": "This rule is on because of an event that occured on date X",
    "allowed_modes": [
      "whitelist",
      "block",
      "challenge",
      "js_challenge"
    ],
    "mode": "challenge",
    "configuration": {
      "target": "ip",
      "value": "198.51.100.4"
    },
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "scope": {
      "id": "7c5dae5552338874e5053f2534d2767a",
      "email": "[email protected]",
      "type": "user"
    }
  }
}

account-level-firewall-access-rule-update-access-rule

PATCH Update Access Rule permission needed: #waf:edit
free
pro
business
enterprise

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

PATCH accounts/:account_identifier/firewall/access_rules/rules/:identifier

Required parameters

Name /type	Description /example	Constraints
id string	Access rule identifier tag `"92f17202ed8bd63d69a66b86a49a8f6b"`	max length: 32 read only
allowed_modes array	The possible modes the rule can be in. `[ "whitelist", "block", "challenge", "js_challenge" ]` An array with items in the following form: Show definition »	read only
mode string	The action to apply to a matched request `"challenge"`	valid values: block, challenge, whitelist, js_challenge
configuration object	Rule configuration `{ "target": "ip", "value": "198.51.100.4" }` One of the following: Show definition » Show definition » Show definition » Show definition »
scope object	All zones owned by the user will have the rule applied. `{ "id": "7c5dae5552338874e5053f2534d2767a", "email": "[email protected]", "type": "user" }` An object with the following properties: Show definition »	read only

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"`
created_on string (date-time)	When the rule was created `"2014-01-01T05:20:00.12345Z"`	read only
modified_on string (date-time)	When the rule was last modified `"2014-01-01T05:20:00.12345Z"`	read only

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/firewall/access_rules/rules/92f17202ed8bd63d69a66b86a49a8f6b" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"92f17202ed8bd63d69a66b86a49a8f6b","notes":"This rule is on because of an event that occured on date X","allowed_modes":["whitelist","block","challenge","js_challenge"],"mode":"challenge","configuration":{"target":"ip","value":"198.51.100.4"},"created_on":"2014-01-01T05:20:00.12345Z","modified_on":"2014-01-01T05:20:00.12345Z","scope":{"id":"7c5dae5552338874e5053f2534d2767a","email":"[email protected]","type":"user"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "92f17202ed8bd63d69a66b86a49a8f6b",
    "notes": "This rule is on because of an event that occured on date X",
    "allowed_modes": [
      "whitelist",
      "block",
      "challenge",
      "js_challenge"
    ],
    "mode": "challenge",
    "configuration": {
      "target": "ip",
      "value": "198.51.100.4"
    },
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "scope": {
      "id": "7c5dae5552338874e5053f2534d2767a",
      "email": "[email protected]",
      "type": "user"
    }
  }
}

account-level-firewall-access-rule-delete-access-rule

DELETE Delete Access Rule permission needed: #waf:edit
free
pro
business
enterprise

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

DELETE accounts/:account_identifier/firewall/access_rules/rules/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/firewall/access_rules/rules/92f17202ed8bd63d69a66b86a49a8f6b" \
     -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"
  }
}

Organization-level Firewall Access Rule

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

organization-level-firewall-access-rule

Object definition

View properties and constraints defined on the object

Show definition

organization-level-firewall-access-rule-list-access-rules

GET List Access Rules permission needed: #waf:edit
free
pro
business
enterprise

Search, sort, and filter IP/country access rules

GET organizations/:organization_id/firewall/access_rules/rules

Optional parameters

Name /type	Description /example	Constraints
notes string	Search in the access rules by notes. `"my note"`	notes: Matching any string within previously created access rules with the notes. For example, access rules with notes 'Attack 26/02' & 'Attack 27/02' would both match string 'attack'. Search is not case sensitive.
mode string	The action to apply to a matched request `"challenge"`	valid values: block, challenge, whitelist, js_challenge
match string	Whether to match all search requirements or at least one (any) `"all"`	default value: all valid values: any, all
configuration.target string	Search rules by target `"ip"`	valid values: ip, ip_range, asn, country
order string	Field to order rules by `"mode"`	valid values: configuration.target, configuration.value, mode
page number	Page number of paginated results `1`	default value: 1 min value:1
per_page number	Maximum number of results per page. This can only be provided as 1 or in multiples of 5 such as 5, 10, 15 or 20 `20`	default value: 20 min value:1 max value:1000
configuration.value string	Search by IP, range, or country code `"198.51.100.4"`	notes: IP is a single IPv4 address. IP range has a subnet of /16 or /24. Country code is an ISO 2-letter country code.
direction string	Direction to order rules `"desc"`	valid values: asc, desc

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/firewall/access_rules/rules?page=1&per_page=20&mode=challenge&configuration.target=ip&configuration.value=198.51.100.4&notes=my note&match=all&order=mode&direction=desc" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "92f17202ed8bd63d69a66b86a49a8f6b",
      "notes": "This rule is on because of an event that occured on date X",
      "allowed_modes": [
        "whitelist",
        "block",
        "challenge",
        "js_challenge"
      ],
      "mode": "challenge",
      "configuration": {
        "target": "ip",
        "value": "198.51.100.4"
      },
      "created_on": "2014-01-01T05:20:00.12345Z",
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "scope": {
        "id": "7c5dae5552338874e5053f2534d2767a",
        "email": "[email protected]",
        "type": "user"
      }
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

organization-level-firewall-access-rule-create-access-rule

POST Create Access Rule permission needed: #waf:edit
free
pro
business
enterprise

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

POST organizations/:organization_id/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, js_challenge
configuration object	Rule configuration `{ "target": "ip", "value": "198.51.100.4" }` One of the following: Show definition » Show definition » Show definition » Show definition »

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/organizations/01a7362d577a6c3019a474fd6f485823/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":"198.51.100.4"},"notes":"This rule is on because of an event that occured on date X"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "92f17202ed8bd63d69a66b86a49a8f6b",
    "notes": "This rule is on because of an event that occured on date X",
    "allowed_modes": [
      "whitelist",
      "block",
      "challenge",
      "js_challenge"
    ],
    "mode": "challenge",
    "configuration": {
      "target": "ip",
      "value": "198.51.100.4"
    },
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "scope": {
      "id": "7c5dae5552338874e5053f2534d2767a",
      "email": "[email protected]",
      "type": "user"
    }
  }
}

organization-level-firewall-access-rule-edit-access-rule

PATCH Edit Access Rule permission needed: #waf:edit
free
pro
business
enterprise

Edit rule state and/or note. This will be applied across all zones owned by the organization.

PATCH organizations/:organization_id/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, js_challenge
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/organizations/01a7362d577a6c3019a474fd6f485823/firewall/access_rules/rules/92f17202ed8bd63d69a66b86a49a8f6b" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"mode":"challenge","notes":"This rule is on because of an event that occured on date X"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "92f17202ed8bd63d69a66b86a49a8f6b",
    "notes": "This rule is on because of an event that occured on date X",
    "allowed_modes": [
      "whitelist",
      "block",
      "challenge",
      "js_challenge"
    ],
    "mode": "challenge",
    "configuration": {
      "target": "ip",
      "value": "198.51.100.4"
    },
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "scope": {
      "id": "7c5dae5552338874e5053f2534d2767a",
      "email": "[email protected]",
      "type": "user"
    }
  }
}

organization-level-firewall-access-rule-delete-access-rule

DELETE Delete Access Rule permission needed: #waf:edit
free
pro
business
enterprise

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

DELETE organizations/:organization_id/firewall/access_rules/rules/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/firewall/access_rules/rules/92f17202ed8bd63d69a66b86a49a8f6b" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "92f17202ed8bd63d69a66b86a49a8f6b"
  }
}

Firewall Access Rule for a Zone

An IP, IP range, or country specific firewall rule applied directly to a zone or inherited from user or organization-level rules.

Access Rules are a way to allow, challenge, or block requests to your website based on the IP address, IP address range, or country of the browser making the request.

You can apply Access Rules to one zone only or all zones in your account. See the User-level or Organization-level access rules endpoints for creating rules that are applied across all zones owned by the user or organization.

firewall-access-rule-for-a-zone

Object definition

View properties and constraints defined on the object

Show definition

firewall-access-rule-for-a-zone-list-access-rules

GET List Access Rules
free
pro
business
enterprise

Search, sort, and filter IP/country access rules

GET zones/:zone_id/firewall/access_rules/rules

Optional parameters

Name /type	Description /example	Constraints
notes string	Search in the access rules by notes. `"my note"`	notes: Matching any string within previously created access rules with the notes. For example, access rules with notes 'Attack 26/02' & 'Attack 27/02' would both match string 'attack'. Search is not case sensitive.
mode string	The action to apply to a matched request `"challenge"`	valid values: block, challenge, whitelist, js_challenge
match string	Whether to match all search requirements or at least one (any) `"all"`	default value: all valid values: any, all
configuration.target string	Search rules by target `"ip"`	valid values: ip, ip_range, asn, country
order string	Field to order rules by `"mode"`	valid values: configuration.target, configuration.value, mode
page number	Page number of paginated results `1`	default value: 1 min value:1
per_page number	Maximum number of results per page. This can only be provided as 1 or in multiples of 5 such as 5, 10, 15 or 20 `20`	default value: 20 min value:1 max value:1000
configuration.value string	Search by IP, range, or country code `"198.51.100.4"`	notes: IP is a single IPv4 address. IP range has a subnet of /16 or /24. Country code is an ISO 2-letter country code.
direction string	Direction to order rules `"desc"`	valid values: asc, desc

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/access_rules/rules?page=1&per_page=20&mode=challenge&configuration.target=ip&configuration.value=198.51.100.4&notes=my note&match=all&order=mode&direction=desc" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "92f17202ed8bd63d69a66b86a49a8f6b",
      "notes": "This rule is on because of an event that occured on date X",
      "allowed_modes": [
        "whitelist",
        "block",
        "challenge",
        "js_challenge"
      ],
      "mode": "challenge",
      "configuration": {
        "target": "ip",
        "value": "198.51.100.4"
      },
      "created_on": "2014-01-01T05:20:00.12345Z",
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "scope": {
        "id": "7c5dae5552338874e5053f2534d2767a",
        "email": "[email protected]",
        "type": "user"
      }
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

firewall-access-rule-for-a-zone-create-access-rule

POST Create Access Rule
free
pro
business
enterprise

Make a new IP, IP range, or country access rule for the zone. Note: If you would like to create an access rule that applies across all of your owned zones, use the user or organization firewall endpoints as appropriate.

POST zones/:zone_id/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, js_challenge
configuration object	Rule configuration `{ "target": "ip", "value": "198.51.100.4" }` One of the following: Show definition » Show definition » Show definition » Show definition »
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/zones/023e105f4ecef8ad9ca31a8372d0c353/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":"198.51.100.4"},"notes":"This rule is on because of an event that occured on date X"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "92f17202ed8bd63d69a66b86a49a8f6b",
    "notes": "This rule is on because of an event that occured on date X",
    "allowed_modes": [
      "whitelist",
      "block",
      "challenge",
      "js_challenge"
    ],
    "mode": "challenge",
    "configuration": {
      "target": "ip",
      "value": "198.51.100.4"
    },
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "scope": {
      "id": "7c5dae5552338874e5053f2534d2767a",
      "email": "[email protected]",
      "type": "user"
    }
  }
}

firewall-access-rule-for-a-zone-edit-access-rule

PATCH Edit Access Rule
free
pro
business
enterprise

Update rule state and/or note for the zone. Note: you can only edit rules in the 'zone' group via this endpoint. Use the appropriate owner rules endpoint if trying to manage owner-level rules

PATCH zones/:zone_id/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, js_challenge
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/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/access_rules/rules/92f17202ed8bd63d69a66b86a49a8f6b" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"mode":"challenge","notes":"This rule is on because of an event that occured on date X"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "92f17202ed8bd63d69a66b86a49a8f6b",
    "notes": "This rule is on because of an event that occured on date X",
    "allowed_modes": [
      "whitelist",
      "block",
      "challenge",
      "js_challenge"
    ],
    "mode": "challenge",
    "configuration": {
      "target": "ip",
      "value": "198.51.100.4"
    },
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "scope": {
      "id": "7c5dae5552338874e5053f2534d2767a",
      "email": "[email protected]",
      "type": "user"
    }
  }
}

firewall-access-rule-for-a-zone-delete-access-rule

DELETE Delete Access Rule
free
pro
business
enterprise

Remove an access rule so it is no longer evaluated during requests. Optionally, specify how to delete rules that match the mode and configuration across all other zones that this zone owner manages. 'none' is the default, and will only delete this rule. 'basic' will delete rules that match the same mode and configuration. 'aggressive' will delete rules that match the same configuration.

DELETE zones/:zone_id/firewall/access_rules/rules/:identifier

Optional parameters

Name /type	Description /example	Constraints
cascade string	The level to attempt to delete rules defined on other zones that are similar to this rule `"none"`	default value: none valid values: none, basic, aggressive

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/access_rules/rules/92f17202ed8bd63d69a66b86a49a8f6b" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"cascade":"none"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "92f17202ed8bd63d69a66b86a49a8f6b"
  }
}

WAF Rule Packages

Web application firewall rule package applied to a zone

Web application firewall rule packages are collections of rule groups.

waf-rule-packages

Object definitions

View properties and constraints defined on the object

Show definitions

waf-rule-packages-list-firewall-packages

GET List Firewall Packages
free
pro
business
enterprise

Retrieve firewall packages for a zone

GET zones/:zone_identifier/firewall/waf/packages

Optional parameters

Name /type	Description /example	Constraints
name string	Name of the firewall package `"USER"`	read only
page number	Page number of paginated results `1`	default value: 1 min value:1
per_page number	Number of packages per page `50`	default value: 50 min value:5 max value:100
order string	Field to order packages by `"status"`	valid values: name
direction string	Direction to order packages `"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/023e105f4ecef8ad9ca31a8372d0c353/firewall/waf/packages?name=USER&page=1&per_page=50&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": "a25a9a7e9c00afc1fb2e0245519d725b",
      "name": "USER",
      "description": "null",
      "detection_mode": "traditional",
      "zone_id": "023e105f4ecef8ad9ca31a8372d0c353",
      "status": "active"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

waf-rule-packages-firewall-package-details

GET Firewall Package Details
free
pro
business
enterprise

Get information about a single firewall package

GET zones/:zone_identifier/firewall/waf/packages/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/waf/packages/a25a9a7e9c00afc1fb2e0245519d725b" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "a25a9a7e9c00afc1fb2e0245519d725b",
    "name": "USER",
    "description": "null",
    "detection_mode": "traditional",
    "zone_id": "023e105f4ecef8ad9ca31a8372d0c353",
    "status": "active"
  }
}

waf-rule-packages-edit-firewall-package

PATCH Edit Firewall Package
free
pro
business
enterprise

Change the sensitivity and action for an anomaly detection type WAF rule package

PATCH zones/:zone_identifier/firewall/waf/packages/:identifier

Optional parameters

Name /type	Description /example	Constraints
sensitivity string	The sensitivity of the firewall package. `"high"`	default value: high valid values: high, medium, low, off
action_mode string	The default action that will be taken for rules under the firewall package. `"challenge"`	default value: challenge valid values: simulate, block, challenge

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/waf/packages/a25a9a7e9c00afc1fb2e0245519d725b" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"sensitivity":"high","action_mode":"challenge"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "a25a9a7e9c00afc1fb2e0245519d725b",
    "name": "OWASP ModSecurity Core Rule Set",
    "description": "Covers OWASP Top 10 vulnerabilities, and more.",
    "detection_mode": "anomaly",
    "zone_id": "023e105f4ecef8ad9ca31a8372d0c353",
    "status": "active",
    "sensitivity": "high",
    "action_mode": "challenge"
  }
}

WAF Rule Groups

A group of web application firewall rules that share common functionality and traits

waf-rule-groups

Object definition

View properties and constraints defined on the object

Show definition

waf-rule-groups-list-rule-groups

GET List Rule Groups
free
pro
business
enterprise

Search, list, and sort rule groups contained within a package

GET zones/:zone_identifier/firewall/waf/packages/:package_identifier/groups

Optional parameters

Name /type	Description /example	Constraints
name string	Name of the firewall rule group `"Project Honey Pot"`	read only
mode string	Whether or not the rules contained within this group are configurable/usable `"on"`	default value: on valid values: on, off
rules_count number	How many rules are contained within this group `10`	default value: 0 read only
page number	Page number of paginated results `1`	default value: 1 min value:1
per_page number	Number of groups per page `50`	default value: 50 min value:5 max value:100
order	Field to order groups by `"mode"`	valid values: mode, rules_count
direction	Direction to order groups `"desc"`	valid values: asc, desc
match	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/023e105f4ecef8ad9ca31a8372d0c353/firewall/waf/packages/a25a9a7e9c00afc1fb2e0245519d725b/groups?name=Project Honey Pot&mode=on&rules_count=10&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": "de677e5818985db1285d0e80225f06e5",
      "name": "Project Honey Pot",
      "description": "Group designed to protect against IP addresses that are a threat and typically used to launch DDoS attacks",
      "rules_count": 10,
      "modified_rules_count": 2,
      "package_id": "a25a9a7e9c00afc1fb2e0245519d725b",
      "mode": "on",
      "allowed_modes": [
        "on",
        "off"
      ]
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

waf-rule-groups-rule-group-details

GET Rule Group Details
free
pro
business
enterprise

Get a single rule group

GET zones/:zone_identifier/firewall/waf/packages/:package_identifier/groups/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/waf/packages/a25a9a7e9c00afc1fb2e0245519d725b/groups/de677e5818985db1285d0e80225f06e5" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "de677e5818985db1285d0e80225f06e5",
    "name": "Project Honey Pot",
    "description": "Group designed to protect against IP addresses that are a threat and typically used to launch DDoS attacks",
    "rules_count": 10,
    "modified_rules_count": 2,
    "package_id": "a25a9a7e9c00afc1fb2e0245519d725b",
    "mode": "on",
    "allowed_modes": [
      "on",
      "off"
    ]
  }
}

waf-rule-groups-edit-rule-group

PATCH Edit Rule Group
free
pro
business
enterprise

Update the state of a rule group

PATCH zones/:zone_identifier/firewall/waf/packages/:package_identifier/groups/:identifier

Optional parameters

Name /type	Description /example	Constraints
mode string	Whether or not the rules contained within this group are configurable/usable `"on"`	default value: on valid values: on, off

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/waf/packages/a25a9a7e9c00afc1fb2e0245519d725b/groups/de677e5818985db1285d0e80225f06e5" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"mode":"on"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "de677e5818985db1285d0e80225f06e5",
    "name": "Project Honey Pot",
    "description": "Group designed to protect against IP addresses that are a threat and typically used to launch DDoS attacks",
    "rules_count": 10,
    "modified_rules_count": 2,
    "package_id": "a25a9a7e9c00afc1fb2e0245519d725b",
    "mode": "on",
    "allowed_modes": [
      "on",
      "off"
    ]
  }
}

WAF Rules

A firewall rule for a zone

waf-rules

Object definitions

View properties and constraints defined on the object

Show definitions

waf-rules-list-rules

GET List Rules
free
pro
business
enterprise

Search, sort, and filter rules within a package

GET zones/:zone_id/firewall/waf/packages/:package_id/rules

Optional parameters

Name /type	Description /example	Constraints
mode string	The setting a rule has been overridden to `"CHL"`	valid values: DIS, CHL, BLK, SIM
priority number	The order in which the individual rule is executed within the related group `5`	read only
match string	Whether to match all search requirements or at least one (any) `"all"`	default value: all valid values: any, all
order string	Field to order rules by `"status"`	valid values: priority, group_id, description
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
group_id string	WAF group identifier tag `"de677e5818985db1285d0e80225f06e5"`	max length: 32 read only
description string	Public description of the rule `"SQL injection prevention for SELECT statements"`	read only
direction string	Direction to order rules `"desc"`	valid values: asc, desc

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/waf/packages/a25a9a7e9c00afc1fb2e0245519d725b/rules?description=SQL injection prevention for SELECT statements&mode=CHL&priority=5&group_id=de677e5818985db1285d0e80225f06e5&page=1&per_page=50&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": "f939de3be84e66e757adcdcb87908023",
      "description": "SQL injection prevention for SELECT statements",
      "priority": 5,
      "group": {
        "id": "de677e5818985db1285d0e80225f06e5",
        "name": "Project Honey Pot"
      },
      "package_id": "a25a9a7e9c00afc1fb2e0245519d725b",
      "allowed_modes": [
        "on",
        "off"
      ],
      "mode": "on"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

waf-rules-rule-details

GET Rule Details
free
pro
business
enterprise

Individual information about a rule

GET zones/:zone_id/firewall/waf/packages/:package_id/rules/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/waf/packages/a25a9a7e9c00afc1fb2e0245519d725b/rules/f939de3be84e66e757adcdcb87908023" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f939de3be84e66e757adcdcb87908023",
    "description": "SQL injection prevention for SELECT statements",
    "priority": 5,
    "group": {
      "id": "de677e5818985db1285d0e80225f06e5",
      "name": "Project Honey Pot"
    },
    "package_id": "a25a9a7e9c00afc1fb2e0245519d725b",
    "allowed_modes": [
      "on",
      "off"
    ],
    "mode": "on"
  }
}

waf-rules-edit-rule

PATCH Edit Rule
free
pro
business
enterprise

Update the action the rule will perform if triggered on the zone

PATCH zones/:zone_id/firewall/waf/packages/:package_id/rules/:identifier

Optional parameters

Name /type	Description /example	Constraints
mode	The mode to use when the rule is triggered. Value is restricted based on the allowed_modes of the rule `"on"`	valid values: default, disable, simulate, block, challenge, on, off

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/waf/packages/a25a9a7e9c00afc1fb2e0245519d725b/rules/f939de3be84e66e757adcdcb87908023" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"mode":"on"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f939de3be84e66e757adcdcb87908023",
    "description": "SQL injection prevention for SELECT statements",
    "priority": 5,
    "group": {
      "id": "de677e5818985db1285d0e80225f06e5",
      "name": "Project Honey Pot"
    },
    "package_id": "a25a9a7e9c00afc1fb2e0245519d725b",
    "allowed_modes": [
      "on",
      "off"
    ],
    "mode": "on"
  }
}

User-Agent Blocking Rules

Perform access control when matching the exact UserAgent reported by the client

The access control mechanisms can be defined within a rule to help manage traffic from particular clients. This will enable you to customise the access to your site. The mechanisms are: -

block - Blocks the request immediately

challenge - Send a challenge to the originator of the request

js_challenge - Send a JavaScript based challenge to the originator of the request

user-agent-blocking-rules

Object definition

View properties and constraints defined on the object

Show definition

user-agent-blocking-rules-list-useragent-rules

GET List UserAgent Rules
free
pro
business
enterprise

List the UserAgent rules on a zone.

GET zones/:zone_identifier/firewall/ua_rules

Optional parameters

Name /type	Description /example	Constraints
page number	Page number of paginated results `1`	default value: 1 min value:1
per_page number	Maximum number of results per page. This can only be provided as 1 or in multiples of 5 such as 5, 10, 15 or 20 `20`	default value: 20 min value:1 max value:1000
description string	A single string to search for in the description `"abusive"`
user_agent string	A single UserAgent string to search for `"Safari"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/ua_rules?page=1&per_page=20&description=abusive&user_agent=Safari" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "372e67954025e0ba6aaa6d586b9e0b59",
      "paused": false,
      "description": "Prevent access from abusive clients identified by this UserAgent to mitigate DDoS attack",
      "mode": "js_challenge",
      "configuration": {
        "target": "ua",
        "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/603.2.4 (KHTML, like Gecko) Version/10.1.1 Safari/603.2.4"
      }
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

user-agent-blocking-rules-create-useragent-rule

POST Create UserAgent Rule
free
pro
business
enterprise

Create a new UserAgent rule for a zone. See the record object definitions for required attributes for each record type

POST zones/:zone_identifier/firewall/ua_rules

Required parameters

Name /type	Description /example	Constraints
mode	The type of action to perform. `"js_challenge"`	max length: 12 valid values: block, challenge, js_challenge
configuration object	Target/Value pair to use for this rule. The value is the exact UserAgent to match `{ "target": "ua", "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/603.2.4 (KHTML, like Gecko) Version/10.1.1 Safari/603.2.4" }` An object with the following properties: Show definition »

Optional parameters

Name /type	Description /example	Constraints
id string	UA rule identifier `"372e67954025e0ba6aaa6d586b9e0b59"`	max length: 32 read only
paused boolean	Whether this UA rule is currently paused `false`	valid values: (true,false)
description string	Some useful information about this rule to help identify the purpose of it. `"Prevent access from abusive clients identified by this UserAgent to mitigate DDoS attack"`	max length: 1024

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/ua_rules" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"372e67954025e0ba6aaa6d586b9e0b59","paused":false,"description":"Prevent access from abusive clients identified by this UserAgent to mitigate DDoS attack","mode":"js_challenge","configuration":{"target":"ua","value":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/603.2.4 (KHTML, like Gecko) Version/10.1.1 Safari/603.2.4"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b59",
    "paused": false,
    "description": "Prevent access from abusive clients identified by this UserAgent to mitigate DDoS attack",
    "mode": "js_challenge",
    "configuration": {
      "target": "ua",
      "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/603.2.4 (KHTML, like Gecko) Version/10.1.1 Safari/603.2.4"
    }
  }
}

user-agent-blocking-rules-useragent-rule-details

GET UserAgent Rule Details
free
pro
business
enterprise

GET zones/:zone_identifier/firewall/ua_rules/:id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/ua_rules/372e67954025e0ba6aaa6d586b9e0b59" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b59",
    "paused": false,
    "description": "Prevent access from abusive clients identified by this UserAgent to mitigate DDoS attack",
    "mode": "js_challenge",
    "configuration": {
      "target": "ua",
      "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/603.2.4 (KHTML, like Gecko) Version/10.1.1 Safari/603.2.4"
    }
  }
}

user-agent-blocking-rules-update-useragent-rule

PUT Update UserAgent Rule
free
pro
business
enterprise

PUT zones/:zone_identifier/firewall/ua_rules/:id

Required parameters

Name /type	Description /example	Constraints
id string	UA rule identifier `"372e67954025e0ba6aaa6d586b9e0b59"`	max length: 32 read only
mode	The type of action to perform. `"js_challenge"`	max length: 12 valid values: block, challenge, js_challenge
configuration object	Target/Value pair to use for this rule. The value is the exact UserAgent to match `{ "target": "ua", "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/603.2.4 (KHTML, like Gecko) Version/10.1.1 Safari/603.2.4" }` An object with the following properties: Show definition »

Optional parameters

Name /type	Description /example	Constraints
paused boolean	Whether this UA rule is currently paused `false`	valid values: (true,false)
description string	Some useful information about this rule to help identify the purpose of it. `"Prevent access from abusive clients identified by this UserAgent to mitigate DDoS attack"`	max length: 1024

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/ua_rules/372e67954025e0ba6aaa6d586b9e0b59" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"372e67954025e0ba6aaa6d586b9e0b59","paused":false,"description":"Prevent access from abusive clients identified by this UserAgent to mitigate DDoS attack","mode":"js_challenge","configuration":{"target":"ua","value":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/603.2.4 (KHTML, like Gecko) Version/10.1.1 Safari/603.2.4"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b59",
    "paused": false,
    "description": "Prevent access from abusive clients identified by this UserAgent to mitigate DDoS attack",
    "mode": "js_challenge",
    "configuration": {
      "target": "ua",
      "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/603.2.4 (KHTML, like Gecko) Version/10.1.1 Safari/603.2.4"
    }
  }
}

user-agent-blocking-rules-delete-useragent-rule

DELETE Delete UserAgent Rule
free
pro
business
enterprise

DELETE zones/:zone_identifier/firewall/ua_rules/:id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/ua_rules/372e67954025e0ba6aaa6d586b9e0b59" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b59"
  }
}

User-Agent Blocking Rules error codes

Code	Description
10000	Invalid user
10001	UserAgent rule not found
10002	UserAgent rule not unique (edit the existing rather than adding a new)
10004	Invalid data submitted
10006	Auth missing
10007	Auth corrupt
10008	Auth expired
10009	Unauthorized
10011	Pagination results in empty page
10013	Patch values not valid
10014	Patch operation not valid
10015	Patch value not valid for given context
10016	Patch not valid

Zone Lockdown

Lock access to URLs in this zone to only permitted addresses or address ranges.

Ensure that part(s) of your site can only be accessed from permitted IP addresses or IP ranges. Zone Lockdown allows you to define one or more URLs (with wildcard matching on the domain or path) that will only permit access if the request originates from an IP address that matches a safelist of one or more IP addresses and/or IP ranges.

zone-lockdown

Object definition

View properties and constraints defined on the object

Show definition

zone-lockdown-list-lockdown-rules

GET List Lockdown Rules
free
pro
business
enterprise

List the lockdown rules on a zone.

GET zones/:zone_identifier/firewall/lockdowns

Optional parameters

Name /type	Description /example	Constraints
priority number	The priority of the rule to allow control of processing order. A lower number indicates high priority. If not provided, any rules with a priority will be sequenced before those without. `"5"`
ip_range string	A single IP range to search for `"1.2.3.0/16"`
ip string	A single IP address to search for `"1.2.3.4"`
uri string	A single URI to search for in the list of URLs `"/some/path"`
page number	Page number of paginated results `1`	default value: 1 min value:1
per_page number	Maximum number of results per page. This can only be provided as 1 or in multiples of 5 such as 5, 10, 15 or 20 `20`	default value: 20 min value:1 max value:1000
modified_on string (date-time)	When the lockdown rule was modified `"2014-01-01T05:20:00.12345Z"`	read only
created_on string (date-time)	When the lockdown rule was created `"2014-01-01T05:20:00.12345Z"`	read only
description string	A single string to search for in the description `"endpoints"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/lockdowns?page=1&per_page=20&description=endpoints&created_on=2014-01-01T05:20:00.12345Z&modified_on=2014-01-01T05:20:00.12345Z&uri=/some/path&ip=1.2.3.4&ip_range=1.2.3.0/16&priority=5" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "372e67954025e0ba6aaa6d586b9e0b59",
      "created_on": "2014-01-01T05:20:00.12345Z",
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "paused": false,
      "description": "Restrict access to these endpoints to requests from a known IP address",
      "urls": [
        "api.mysite.com/some/endpoint*"
      ],
      "configurations": [
        {
          "target": "ip",
          "value": "198.51.100.4"
        }
      ]
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

zone-lockdown-create-lockdown-rule

POST Create Lockdown Rule
free
pro
business
enterprise

Create a new lockdown rule for a zone. See the record object definitions for required attributes for each record type

POST zones/:zone_identifier/firewall/lockdowns

Required parameters

Name /type	Description /example	Constraints
urls array	URLs to be included in this rule definition. Wildcards are permitted. The URL pattern entered here will be escaped before use. This limits the URL to just simple wildcard patterns. `[ "api.mysite.com/some/endpoint*" ]` An array with items in the following form: Show definition »
configurations array	List of IP addresses or CIDR ranges to use for this rule. This can include any number of `ip` or `ip_range` configurations that can access the provided URLs. `[ { "target": "ip", "value": "198.51.100.4" } ]` An array with items in the following form: Any of the following: Show definition » Show definition » Show definition »

Optional parameters

Name /type	Description /example	Constraints
paused boolean	Whether this zone lockdown is currently paused `false`	valid values: (true,false)
description string	A note that you can use to describe the reason for a Lockdown rule. `"Restrict access to these endpoints to requests from a known IP address"`	max length: 1024

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/lockdowns" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"paused":false,"description":"Restrict access to these endpoints to requests from a known IP address","urls":["api.mysite.com/some/endpoint*"],"configurations":[{"target":"ip","value":"198.51.100.4"}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b59",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "paused": false,
    "description": "Restrict access to these endpoints to requests from a known IP address",
    "urls": [
      "api.mysite.com/some/endpoint*"
    ],
    "configurations": [
      {
        "target": "ip",
        "value": "198.51.100.4"
      }
    ]
  }
}

zone-lockdown-lockdown-rule-details

GET Lockdown Rule Details
free
pro
business
enterprise

GET zones/:zone_identifier/firewall/lockdowns/:id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/lockdowns/372e67954025e0ba6aaa6d586b9e0b59" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b59",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "paused": false,
    "description": "Restrict access to these endpoints to requests from a known IP address",
    "urls": [
      "api.mysite.com/some/endpoint*"
    ],
    "configurations": [
      {
        "target": "ip",
        "value": "198.51.100.4"
      }
    ]
  }
}

zone-lockdown-update-lockdown-rule

PUT Update Lockdown Rule
free
pro
business
enterprise

PUT zones/:zone_identifier/firewall/lockdowns/:id

Required parameters

Name /type	Description /example	Constraints
urls array	URLs to be included in this rule definition. Wildcards are permitted. The URL pattern entered here will be escaped before use. This limits the URL to just simple wildcard patterns. `[ "api.mysite.com/some/endpoint*" ]` An array with items in the following form: Show definition »
configurations array	List of IP addresses or CIDR ranges to use for this rule. This can include any number of `ip` or `ip_range` configurations that can access the provided URLs. `[ { "target": "ip", "value": "198.51.100.4" } ]` An array with items in the following form: Any of the following: Show definition » Show definition » Show definition »

Optional parameters

Name /type	Description /example	Constraints
paused boolean	Whether this zone lockdown is currently paused `false`	valid values: (true,false)
description string	A note that you can use to describe the reason for a Lockdown rule. `"Restrict access to these endpoints to requests from a known IP address"`	max length: 1024

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/lockdowns/372e67954025e0ba6aaa6d586b9e0b59" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"paused":false,"description":"Restrict access to these endpoints to requests from a known IP address","urls":["api.mysite.com/some/endpoint*"],"configurations":[{"target":"ip","value":"198.51.100.4"}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b59",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "paused": false,
    "description": "Restrict access to these endpoints to requests from a known IP address",
    "urls": [
      "api.mysite.com/some/endpoint*"
    ],
    "configurations": [
      {
        "target": "ip",
        "value": "198.51.100.4"
      }
    ]
  }
}

zone-lockdown-delete-lockdown-rule

DELETE Delete Lockdown Rule
free
pro
business
enterprise

DELETE zones/:zone_identifier/firewall/lockdowns/:id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/lockdowns/372e67954025e0ba6aaa6d586b9e0b59" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b59"
  }
}

Zone Lockdown error codes

Code	Description
10000	Invalid user
10001	lockdown rule not found
10002	lockdown rule not unique (edit the existing rather than adding a new)
10004	Invalid data submitted
10006	Auth missing
10007	Auth corrupt
10008	Auth expired
10009	Unauthorized
10011	Pagination results in empty page
10013	Patch values not valid
10014	Patch operation not valid
10015	Patch value not valid for given context
10016	Patch not valid

Firewall Events

Logs of the mitigations performed by Firewall features.

Provides a full log of the mitigations performed by the Cloudflare Firewall features including; Firewall Rules, Rate Limiting, Security Level, Access Rules (IP, IP Range, ASN, and Country), WAF (Web Application Firewall), User Agent Blocking, Zone Lockdown, and Advanced DDoS Protection. For all mitigated events you are able to access the time, IP, and URI of the request that triggered the mitigation and a list of other matches that were made against the request.

firewall-events

Object definition

View properties and constraints defined on the object

Show definition

firewall-events-list-events

GET List Events

Search, and filter Firewall events

GET zones/:zone_identifier/security/events

Optional parameters

Name /type	Description /example	Constraints
ip_class	IP class is a map of client IP to visitor classification `"clean"`	valid values: unknown, clean, badHost, searchEngine, whitelist, greylist, monitoringService, securityScanner, noRecord, scan, backupService, mobilePlatform, tor
method	The HTTP method of the request `"POST"`	valid values: GET, POST, DELETE, PUT, HEAD, PURGE, OPTIONS, PROPFIND, MKCOL, PATCH, ACL, BCOPY, BDELETE, BMOVE, BPROPFIND, BPROPPATCH, CHECKIN, CHECKOUT, CONNECT, COPY, LABEL, LOCK, MERGE, MKACTIVITY, MKWORKSPACE, MOVE, NOTIFY, ORDERPATCH, POLL, PROPPATCH, REPORT, SEARCH, SUBSCRIBE, TRACE, UNCHECKOUT, UNLOCK, UNSUBSCRIBE, UPDATE, VERSION-CONTROL, BASELINE-CONTROL, X-MS-ENUMATTS, RPC_OUT_DATA, RPC_IN_DATA, JSON, COOK, TRACK
scheme	The scheme of the uri `"https"`	valid values: unknown, http, https
ip string	The IPv4 or IPv6 address from which the request originated `"198.51.100.4"`
host string	The hostname the request attempted to access `"www.example.com"`
proto	The protocol of the request `"HTTP/2"`	valid values: UNK, HTTP/1.0, HTTP/1.1, HTTP/1.2, HTTP/2, SPDY/3.1
uri string	The URI requested from the hostname `"/myexploit.php"`
ua string	The client user agent that initiated the request `"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36"`
colo string	The 3-letter airport code of the Cloudflare data-center that handled the request `"SJC"`
ray_id string	Ray ID of the request. For more information on what a Ray ID is, please refer to: https://support.cloudflare.com/hc/en-us/articles/200169746-What-is-the-CF-RAY-header- `"187d944c61940c77"`	max length: 16
kind	`"firewall"`	valid values: firewall
action	What type of action was taken `"challenge"`	valid values: unknown, allow, drop, challenge, jschallenge, simulate, connectionClose, log
cursor string	Cursor position and direction for requesting next set of records when amount of results was limited by the limit parameter. A valid value for the cursor can be obtained from the cursors object in the result_info structure. `"6yDGxLKVeeHZZmORS_8XeSuhz9SjIJRaSa2lnsF01tQOHrfTGAP3R5X1Kv5iVUuMbNKhWNAXHOl6ePB0TUL8nw"`
country string	The 2-digit country code in which the request originated `"US"`	max length: 2
since string (date-time)	Start date and time of requesting data period in the ISO8601 format. Can't go back more than a year. `"2016-11-11T12:00:00Z"`
source string	Source of the event `"rateLimit"`	valid values: unknown, asn, country, ip, ipRange, securityLevel, zoneLockdown, waf, uaBlock, rateLimit, firewallRules, bic, hot, l7ddos
limit number	The number of events to return. The cursor attribute may be used to iterate over the next batch of events, if there are more events in the queried time range. Note that the scanned_range parameter in the result_info structure gives an indication until when events were considered in the current resultset if a limit was applied. `50`	default value: 50 min value:10 max value:1000
rule_id string	The ID of the rule that triggered the event, should be considered in the context of source. `"273954afcd654af1a7643b378899abba"`
until string (date-time)	End date and time of requesting data period in the ISO8601 format `"2016-11-11T12:00:00Z"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/security/events?action=challenge&colo=SJC&country=US&host=www.example.com&ip=198.51.100.4&ip_class=clean&kind=firewall&method=POST&proto=HTTP/2&ray_id=187d944c61940c77&rule_id=273954afcd654af1a7643b378899abba&scheme=https&source=rateLimit&ua=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36&uri=/myexploit.php&limit=50&since=2016-11-11T12:00:00Z&until=2016-11-11T12:00:00Z&cursor=6yDGxLKVeeHZZmORS_8XeSuhz9SjIJRaSa2lnsF01tQOHrfTGAP3R5X1Kv5iVUuMbNKhWNAXHOl6ePB0TUL8nw" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "ray_id": "187d944c61940c77",
      "kind": "firewall",
      "action": "challenge",
      "source": "rateLimit",
      "country": "US",
      "ip": "198.51.100.4",
      "ip_class": "clean",
      "proto": "HTTP/2",
      "method": "POST",
      "host": "www.example.com",
      "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36",
      "scheme": "https",
      "uri": "/myexploit.php",
      "rule_id": "273954afcd654af1a7643b378899abba",
      "colo": "SJC",
      "occurred_at": "2014-10-02T07:14:52Z",
      "matches": [
        {
          "rule_id": "273954afcd654af1a7643b378899abba",
          "source": "rateLimit",
          "action": "challenge"
        }
      ]
    }
  ],
  "result_info": {
    "cursors": {
      "after": "6yDGxLKVeeHZZmORS_8XeSuhz9SjIJRaSa2lnsF01tQOHrfTGAP3R5X1Kv5iVUuMbNKhWNAXHOl6ePB0TUL8nw",
      "before": "6yDGxLKVeeHZZmORS_8XeSuhz9SjIJRaSa2lnsF01tQOHrfTGAP3R5X1Kv5iVUuMbNKhWNAXHOl6ePB0TUL8nw"
    },
    "scanned_range": {
      "since": "2016-11-11T12:00:00Z",
      "until": "2016-11-11T12:00:00Z"
    }
  }
}

Firewall Events error codes

Code	Description
10007	Service temporarily unavailable.
10008	Query is estimated to take too long. Try to shrink the time range or reduce query complexity.
10009	Query reads too many rows. Try to shrink the time range.
10010	Quota exceeded. Try again later.

Load Balancer Monitors

User-level Monitor configurations. Monitors define whether we check over HTTP, HTTPS or TCP, the status code(s) we look for, the interval at which we check, timeouts and response body matching.

load-balancer-monitors

Object definition

View properties and constraints defined on the object

Show definition

load-balancer-monitors-list-monitors

GET List Monitors

List configured monitors for a user

GET user/load_balancers/monitors

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/user/load_balancers/monitors" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
      "created_on": "2014-01-01T05:20:00.12345Z",
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "type": "https",
      "description": "Login page monitor",
      "method": "GET",
      "path": "/health",
      "header": {
        "Host": [
          "example.com"
        ],
        "X-App-ID": [
          "abc123"
        ]
      },
      "port": 8080,
      "timeout": 3,
      "retries": 0,
      "interval": 90,
      "expected_body": "alive",
      "expected_codes": "2xx",
      "follow_redirects": true,
      "allow_insecure": true
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

load-balancer-monitors-create-monitor

POST Create Monitor

Create a configured monitor

POST user/load_balancers/monitors

Required parameters

Name /type	Description /example	Constraints
expected_codes string	The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors. `"2xx"`	default value: 200

Optional parameters

Name /type	Description /example	Constraints
port integer	Port number to connect to for the health check. Required for TCP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443). `8080`	default value: 0
method string	The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks. `"GET"`	default value: GET
timeout integer	The timeout (in seconds) before marking the health check as failed `3`	default value: 5
path string	The endpoint path to health check against. This parameter is only valid for HTTP and HTTPS monitors. `"/health"`	default value: /
interval integer	The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations. `90`	default value: 60
retries integer	The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately. `0`	default value: 2
follow_redirects boolean	Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors. `true`	default value: false valid values: (true,false)
expected_body string	A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors. `"alive"`
header object	The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors. `{ "Host": [ "example.com" ], "X-App-ID": [ "abc123" ] }`
allow_insecure boolean	Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors. `true`	default value: false valid values: (true,false)
type string	The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS' and 'TCP'. `"https"`	default value: http
description string	Object description `"Login page monitor"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/user/load_balancers/monitors" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"https","description":"Login page monitor","method":"GET","path":"/health","header":{"Host":["example.com"],"X-App-ID":["abc123"]},"port":8080,"timeout":3,"retries":0,"interval":90,"expected_body":"alive","expected_codes":"2xx","follow_redirects":true,"allow_insecure":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "type": "https",
    "description": "Login page monitor",
    "method": "GET",
    "path": "/health",
    "header": {
      "Host": [
        "example.com"
      ],
      "X-App-ID": [
        "abc123"
      ]
    },
    "port": 8080,
    "timeout": 3,
    "retries": 0,
    "interval": 90,
    "expected_body": "alive",
    "expected_codes": "2xx",
    "follow_redirects": true,
    "allow_insecure": true
  }
}

load-balancer-monitors-monitor-details

GET Monitor Details

List a single configured monitor for a user

GET user/load_balancers/monitors/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/user/load_balancers/monitors/f1aba936b94213e5b8dca0c0dbf1f9cc" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "type": "https",
    "description": "Login page monitor",
    "method": "GET",
    "path": "/health",
    "header": {
      "Host": [
        "example.com"
      ],
      "X-App-ID": [
        "abc123"
      ]
    },
    "port": 8080,
    "timeout": 3,
    "retries": 0,
    "interval": 90,
    "expected_body": "alive",
    "expected_codes": "2xx",
    "follow_redirects": true,
    "allow_insecure": true
  }
}

load-balancer-monitors-update-monitor

PUT Update Monitor

Modify a configured monitor

PUT user/load_balancers/monitors/:identifier

Required parameters

Name /type	Description /example	Constraints
expected_codes string	The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors. `"2xx"`	default value: 200

Optional parameters

Name /type	Description /example	Constraints
port integer	Port number to connect to for the health check. Required for TCP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443). `8080`	default value: 0
method string	The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks. `"GET"`	default value: GET
timeout integer	The timeout (in seconds) before marking the health check as failed `3`	default value: 5
path string	The endpoint path to health check against. This parameter is only valid for HTTP and HTTPS monitors. `"/health"`	default value: /
interval integer	The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations. `90`	default value: 60
retries integer	The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately. `0`	default value: 2
follow_redirects boolean	Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors. `true`	default value: false valid values: (true,false)
expected_body string	A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors. `"alive"`
header object	The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors. `{ "Host": [ "example.com" ], "X-App-ID": [ "abc123" ] }`
allow_insecure boolean	Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors. `true`	default value: false valid values: (true,false)
type string	The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS' and 'TCP'. `"https"`	default value: http
description string	Object description `"Login page monitor"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/user/load_balancers/monitors/f1aba936b94213e5b8dca0c0dbf1f9cc" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"https","description":"Login page monitor","method":"GET","path":"/health","header":{"Host":["example.com"],"X-App-ID":["abc123"]},"port":8080,"timeout":3,"retries":0,"interval":90,"expected_body":"alive","expected_codes":"2xx","follow_redirects":true,"allow_insecure":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "type": "https",
    "description": "Login page monitor",
    "method": "GET",
    "path": "/health",
    "header": {
      "Host": [
        "example.com"
      ],
      "X-App-ID": [
        "abc123"
      ]
    },
    "port": 8080,
    "timeout": 3,
    "retries": 0,
    "interval": 90,
    "expected_body": "alive",
    "expected_codes": "2xx",
    "follow_redirects": true,
    "allow_insecure": true
  }
}

load-balancer-monitors-delete-monitor

DELETE Delete Monitor

Delete a configured monitor

DELETE user/load_balancers/monitors/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/user/load_balancers/monitors/f1aba936b94213e5b8dca0c0dbf1f9cc" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f1aba936b94213e5b8dca0c0dbf1f9cc"
  }
}

Load Balancer Pools

User-level Load Balancer Pools

load-balancer-pools

Object definition

View properties and constraints defined on the object

Show definition

load-balancer-pools-list-pools

GET List Pools

List configured pools

GET user/load_balancers/pools

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/user/load_balancers/pools" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "17b5962d775c646f3f9725cbc7a53df4",
      "created_on": "2014-01-01T05:20:00.12345Z",
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "description": "Primary data center - Provider XYZ",
      "name": "primary-dc-1",
      "enabled": true,
      "minimum_origins": 2,
      "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
      "check_regions": [
        "WEU",
        "ENAM"
      ],
      "origins": [
        {
          "name": "app-server-1",
          "address": "0.0.0.0",
          "enabled": true,
          "weight": 0.56
        }
      ],
      "notification_email": "[email protected]"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

load-balancer-pools-create-pool

POST Create Pool

Create a new pool

POST user/load_balancers/pools

Required parameters

Name /type	Description /example	Constraints
name string	A short name (tag) for the pool. Only alphanumeric characters, hyphens and underscores are allowed. `"primary-dc-1"`
origins array	The list of origins within this pool. Traffic directed at this pool is balanced across all currently healthy origins, provided the pool itself is healthy. `[ { "name": "app-server-1", "address": "0.0.0.0", "enabled": true, "weight": 0.56 } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
description string	A human-readable description of the pool. `"Primary data center - Provider XYZ"`
enabled boolean	Whether to enable (the default) this pool. Disabled pools will not receive traffic and are excluded from health checks. Disabling a pool will cause any load balancers using it to failover to the next pool (if any). `true`	default value: true valid values: (true,false)
minimum_origins integer	The minimum number of origins that must be healthy for this pool to serve traffic. If the number of healthy origins falls below this number, the pool will be marked unhealthy and we wil failover to the next available pool. `2`	default value: 1
monitor string	The ID of the Monitor to use for health checking origins within this pool. `"f1aba936b94213e5b8dca0c0dbf1f9cc"`	max length: 32 read only
notification_email string	The email address to send health status notifications to. This can be an individual mailbox or a mailing list. `"[email protected]"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/user/load_balancers/pools" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Primary data center - Provider XYZ","name":"primary-dc-1","enabled":true,"minimum_origins":2,"monitor":"f1aba936b94213e5b8dca0c0dbf1f9cc","origins":[{"name":"app-server-1","address":"0.0.0.0","enabled":true,"weight":0.56}],"notification_email":"[email protected]"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "17b5962d775c646f3f9725cbc7a53df4",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "description": "Primary data center - Provider XYZ",
    "name": "primary-dc-1",
    "enabled": true,
    "minimum_origins": 2,
    "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "origins": [
      {
        "name": "app-server-1",
        "address": "0.0.0.0",
        "enabled": true,
        "weight": 0.56
      }
    ],
    "notification_email": "[email protected]"
  }
}

load-balancer-pools-pool-details

GET Pool Details

Fetch a single configured pool

GET user/load_balancers/pools/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/user/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4" \
     -H "X-Auth-Email: [email protected]xample.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "17b5962d775c646f3f9725cbc7a53df4",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "description": "Primary data center - Provider XYZ",
    "name": "primary-dc-1",
    "enabled": true,
    "minimum_origins": 2,
    "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "origins": [
      {
        "name": "app-server-1",
        "address": "0.0.0.0",
        "enabled": true,
        "weight": 0.56
      }
    ],
    "notification_email": "[email protected]"
  }
}

load-balancer-pools-pool-health-details

GET Pool Health Details

Fetch latest healthcheck details for a single pool

GET user/load_balancers/pools/:identifier/health

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/user/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4/health" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "pool_id": "17b5962d775c646f3f9725cbc7a53df4",
    "pop_health": {
      "Amsterdam, NL": {
        "healthy": true,
        "origins": [
          {
            "2001:DB8::5": {
              "healthy": true,
              "rtt": "12.1ms",
              "failure_reason": "No failures",
              "response_code": 401
            }
          }
        ]
      }
    }
  }
}

load-balancer-pools-update-pool

PUT Update Pool

Modify a configured pool

PUT user/load_balancers/pools/:identifier

Required parameters

Name /type	Description /example	Constraints
name string	A short name (tag) for the pool. Only alphanumeric characters, hyphens and underscores are allowed. `"primary-dc-1"`
origins array	The list of origins within this pool. Traffic directed at this pool is balanced across all currently healthy origins, provided the pool itself is healthy. `[ { "name": "app-server-1", "address": "0.0.0.0", "enabled": true, "weight": 0.56 } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
description string	A human-readable description of the pool. `"Primary data center - Provider XYZ"`
enabled boolean	Whether to enable (the default) this pool. Disabled pools will not receive traffic and are excluded from health checks. Disabling a pool will cause any load balancers using it to failover to the next pool (if any). `true`	default value: true valid values: (true,false)
monitor string	The ID of the Monitor to use for health checking origins within this pool. `"f1aba936b94213e5b8dca0c0dbf1f9cc"`	max length: 32 read only
notification_email string	The email address to send health status notifications to. This can be an individual mailbox or a mailing list. `"[email protected]"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/user/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Primary data center - Provider XYZ","name":"primary-dc-1","enabled":true,"monitor":"f1aba936b94213e5b8dca0c0dbf1f9cc","origins":[{"name":"app-server-1","address":"0.0.0.0","enabled":true,"weight":0.56}],"notification_email":"[email protected]"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "17b5962d775c646f3f9725cbc7a53df4",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "description": "Primary data center - Provider XYZ",
    "name": "primary-dc-1",
    "enabled": true,
    "minimum_origins": 2,
    "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "origins": [
      {
        "name": "app-server-1",
        "address": "0.0.0.0",
        "enabled": true,
        "weight": 0.56
      }
    ],
    "notification_email": "[email protected]"
  }
}

load-balancer-pools-delete-pool

DELETE Delete Pool

Delete a configured pool

DELETE user/load_balancers/pools/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/user/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "17b5962d775c646f3f9725cbc7a53df4"
  }
}

Load Balancer Healthcheck Events

User-level Load Balancing Healthcheck Events Log

load-balancer-healthcheck-events

Object definition

View properties and constraints defined on the object

Show definition

load-balancer-healthcheck-events-list-healthcheck-events

GET List Healthcheck Events

List origin health changes

GET user/load_balancing_analytics/events

Optional parameters

Name /type	Description /example	Constraints
since string (date-time)	Start date and time of requesting data period in the ISO8601 format `"2016-11-11T12:00:00Z"`
until string (date-time)	End date and time of requesting data period in the ISO8601 format `"2016-11-11T13:00:00Z"`
origin_name string	The name for the origin to filter for. `"primary-dc-1"`
pool_name string	The name for the pool to filter for. `"primary-dc"`
pool_id string	API item identifier tag `"17b5962d775c646f3f9725cbc7a53df4"`	max length: 32 read only
origin_healthy boolean	If true, filter events where the origin status is healthy, if false, filter events where the origin status is unhealthy. `true`	default value: true valid values: (true,false)
pool_healthy boolean	If true, filter events where the pool status is healthy, if false, filter events where the pool status is unhealthy. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/user/load_balancing_analytics/events?since=2016-11-11T12:00:00Z&until=2016-11-11T13:00:00Z&origin_name=primary-dc-1&pool_name=primary-dc&pool_id=17b5962d775c646f3f9725cbc7a53df4&origin_healthy=true&pool_healthy=true" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": 2,
      "timestamp": "2014-01-01T05:20:00.12345Z",
      "pool": {
        "id": "74bc6a8b9b0dda3d651707a2928bad0c",
        "name": "some-pool",
        "healthy": true,
        "changed": true,
        "minimum_origins": 1
      },
      "origins": [
        {
          "name": "some-origin",
          "address": "198.51.100.4",
          "ip": "198.51.100.4",
          "enabled": true,
          "healthy": true,
          "failure_reason": "No failures",
          "changed": true
        }
      ]
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

Account Load Balancer Monitors

Account-level Monitor configurations. Monitors define whether we check over HTTP, HTTPS or TCP, the status code(s) we look for, the interval at which we check, timeouts and response body matching.

account-load-balancer-monitors

Object definition

View properties and constraints defined on the object

Show definition

account-load-balancer-monitors-list-monitors

GET List Monitors

List configured monitors for an account

GET accounts/:account_identifier/load_balancers/monitors

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/monitors" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
      "created_on": "2014-01-01T05:20:00.12345Z",
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "type": "https",
      "description": "Login page monitor",
      "method": "GET",
      "path": "/health",
      "header": {
        "Host": [
          "example.com"
        ],
        "X-App-ID": [
          "abc123"
        ]
      },
      "port": 8080,
      "timeout": 3,
      "retries": 0,
      "interval": 90,
      "expected_body": "alive",
      "expected_codes": "2xx",
      "follow_redirects": true,
      "allow_insecure": true,
      "probe_zone": "example.com"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

account-load-balancer-monitors-create-monitor

POST Create Monitor

Create a configured monitor

POST accounts/:account_identifier/load_balancers/monitors

Required parameters

Name /type	Description /example	Constraints
expected_codes string	The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors. `"2xx"`	default value: 200

Optional parameters

Name /type	Description /example	Constraints
port integer	Port number to connect to for the health check. Required for TCP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443). `8080`	default value: 0
method string	The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks. `"GET"`	default value: GET
timeout integer	The timeout (in seconds) before marking the health check as failed `3`	default value: 5
path string	The endpoint path to health check against. This parameter is only valid for HTTP and HTTPS monitors. `"/health"`	default value: /
interval integer	The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations. `90`	default value: 60
retries integer	The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately. `0`	default value: 2
follow_redirects boolean	Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors. `true`	default value: false valid values: (true,false)
expected_body string	A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors. `"alive"`
header object	The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors. `{ "Host": [ "example.com" ], "X-App-ID": [ "abc123" ] }`
allow_insecure boolean	Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors. `true`	default value: false valid values: (true,false)
type string	The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS' and 'TCP'. `"https"`	default value: http
probe_zone string	Assign this monitor to emulate the specified zone while probing `"example.com"`
description string	Object description `"Login page monitor"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/monitors" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"https","description":"Login page monitor","method":"GET","path":"/health","header":{"Host":["example.com"],"X-App-ID":["abc123"]},"port":8080,"timeout":3,"retries":0,"interval":90,"expected_body":"alive","expected_codes":"2xx","follow_redirects":true,"allow_insecure":true,"probe_zone":"example.com"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "type": "https",
    "description": "Login page monitor",
    "method": "GET",
    "path": "/health",
    "header": {
      "Host": [
        "example.com"
      ],
      "X-App-ID": [
        "abc123"
      ]
    },
    "port": 8080,
    "timeout": 3,
    "retries": 0,
    "interval": 90,
    "expected_body": "alive",
    "expected_codes": "2xx",
    "follow_redirects": true,
    "allow_insecure": true,
    "probe_zone": "example.com"
  }
}

account-load-balancer-monitors-monitor-details

GET Monitor Details

List a single configured monitor for an account

GET accounts/:account_identifier/load_balancers/monitors/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/monitors/f1aba936b94213e5b8dca0c0dbf1f9cc" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "type": "https",
    "description": "Login page monitor",
    "method": "GET",
    "path": "/health",
    "header": {
      "Host": [
        "example.com"
      ],
      "X-App-ID": [
        "abc123"
      ]
    },
    "port": 8080,
    "timeout": 3,
    "retries": 0,
    "interval": 90,
    "expected_body": "alive",
    "expected_codes": "2xx",
    "follow_redirects": true,
    "allow_insecure": true,
    "probe_zone": "example.com"
  }
}

account-load-balancer-monitors-update-monitor

PUT Update Monitor

Modify a configured monitor

PUT accounts/:account_identifier/load_balancers/monitors/:identifier

Required parameters

Name /type	Description /example	Constraints
expected_codes string	The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors. `"2xx"`	default value: 200

Optional parameters

Name /type	Description /example	Constraints
port integer	Port number to connect to for the health check. Required for TCP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443). `8080`	default value: 0
method string	The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks. `"GET"`	default value: GET
timeout integer	The timeout (in seconds) before marking the health check as failed `3`	default value: 5
path string	The endpoint path to health check against. This parameter is only valid for HTTP and HTTPS monitors. `"/health"`	default value: /
interval integer	The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations. `90`	default value: 60
retries integer	The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately. `0`	default value: 2
follow_redirects boolean	Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors. `true`	default value: false valid values: (true,false)
expected_body string	A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors. `"alive"`
header object	The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors. `{ "Host": [ "example.com" ], "X-App-ID": [ "abc123" ] }`
allow_insecure boolean	Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors. `true`	default value: false valid values: (true,false)
type string	The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS' and 'TCP'. `"https"`	default value: http
probe_zone string	Assign this monitor to emulate the specified zone while probing `"example.com"`
description string	Object description `"Login page monitor"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/monitors/f1aba936b94213e5b8dca0c0dbf1f9cc" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"https","description":"Login page monitor","method":"GET","path":"/health","header":{"Host":["example.com"],"X-App-ID":["abc123"]},"port":8080,"timeout":3,"retries":0,"interval":90,"expected_body":"alive","expected_codes":"2xx","follow_redirects":true,"allow_insecure":true,"probe_zone":"example.com"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "type": "https",
    "description": "Login page monitor",
    "method": "GET",
    "path": "/health",
    "header": {
      "Host": [
        "example.com"
      ],
      "X-App-ID": [
        "abc123"
      ]
    },
    "port": 8080,
    "timeout": 3,
    "retries": 0,
    "interval": 90,
    "expected_body": "alive",
    "expected_codes": "2xx",
    "follow_redirects": true,
    "allow_insecure": true,
    "probe_zone": "example.com"
  }
}

account-load-balancer-monitors-delete-monitor

DELETE Delete Monitor

Delete a configured monitor

DELETE accounts/:account_identifier/load_balancers/monitors/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/monitors/f1aba936b94213e5b8dca0c0dbf1f9cc" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f1aba936b94213e5b8dca0c0dbf1f9cc"
  }
}

Account Load Balancer Pools

Account-level Load Balancer Pools

account-load-balancer-pools

Object definition

View properties and constraints defined on the object

Show definition

account-load-balancer-pools-list-pools

GET List Pools

List configured pools

GET accounts/:account_identifier/load_balancers/pools

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/pools" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "17b5962d775c646f3f9725cbc7a53df4",
      "created_on": "2014-01-01T05:20:00.12345Z",
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "description": "Primary data center - Provider XYZ",
      "name": "primary-dc-1",
      "enabled": true,
      "minimum_origins": 2,
      "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
      "check_regions": [
        "WEU",
        "ENAM"
      ],
      "origins": [
        {
          "name": "app-server-1",
          "address": "0.0.0.0",
          "enabled": true,
          "weight": 0.56
        }
      ],
      "notification_email": "[email protected]"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

account-load-balancer-pools-create-pool

POST Create Pool

Create a new pool

POST accounts/:account_identifier/load_balancers/pools

Required parameters

Name /type	Description /example	Constraints
name string	A short name (tag) for the pool. Only alphanumeric characters, hyphens and underscores are allowed. `"primary-dc-1"`
origins array	The list of origins within this pool. Traffic directed at this pool is balanced across all currently healthy origins, provided the pool itself is healthy. `[ { "name": "app-server-1", "address": "0.0.0.0", "enabled": true, "weight": 0.56 } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
description string	A human-readable description of the pool. `"Primary data center - Provider XYZ"`
enabled boolean	Whether to enable (the default) this pool. Disabled pools will not receive traffic and are excluded from health checks. Disabling a pool will cause any load balancers using it to failover to the next pool (if any). `true`	default value: true valid values: (true,false)
minimum_origins integer	The minimum number of origins that must be healthy for this pool to serve traffic. If the number of healthy origins falls below this number, the pool will be marked unhealthy and we wil failover to the next available pool. `2`	default value: 1
monitor string	The ID of the Monitor to use for health checking origins within this pool. `"f1aba936b94213e5b8dca0c0dbf1f9cc"`	max length: 32 read only
notification_email string	The email address to send health status notifications to. This can be an individual mailbox or a mailing list. `"[email protected]"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/pools" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Primary data center - Provider XYZ","name":"primary-dc-1","enabled":true,"minimum_origins":2,"monitor":"f1aba936b94213e5b8dca0c0dbf1f9cc","origins":[{"name":"app-server-1","address":"0.0.0.0","enabled":true,"weight":0.56}],"notification_email":"[email protected]"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "17b5962d775c646f3f9725cbc7a53df4",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "description": "Primary data center - Provider XYZ",
    "name": "primary-dc-1",
    "enabled": true,
    "minimum_origins": 2,
    "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "origins": [
      {
        "name": "app-server-1",
        "address": "0.0.0.0",
        "enabled": true,
        "weight": 0.56
      }
    ],
    "notification_email": "[email protected]"
  }
}

account-load-balancer-pools-pool-details

GET Pool Details

Fetch a single configured pool

GET accounts/:account_identifier/load_balancers/pools/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "17b5962d775c646f3f9725cbc7a53df4",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "description": "Primary data center - Provider XYZ",
    "name": "primary-dc-1",
    "enabled": true,
    "minimum_origins": 2,
    "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "origins": [
      {
        "name": "app-server-1",
        "address": "0.0.0.0",
        "enabled": true,
        "weight": 0.56
      }
    ],
    "notification_email": "[email protected]"
  }
}

account-load-balancer-pools-pool-health-details

GET Pool Health Details

Fetch latest healthcheck details for a single pool

GET accounts/:account_identifier/load_balancers/pools/:identifier/health

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4/health" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "pool_id": "17b5962d775c646f3f9725cbc7a53df4",
    "pop_health": {
      "Amsterdam, NL": {
        "healthy": true,
        "origins": [
          {
            "2001:DB8::5": {
              "healthy": true,
              "rtt": "12.1ms",
              "failure_reason": "No failures",
              "response_code": 401
            }
          }
        ]
      }
    }
  }
}

account-load-balancer-pools-update-pool

PUT Update Pool

Modify a configured pool

PUT accounts/:account_identifier/load_balancers/pools/:identifier

Required parameters

Name /type	Description /example	Constraints
name string	A short name (tag) for the pool. Only alphanumeric characters, hyphens and underscores are allowed. `"primary-dc-1"`
origins array	The list of origins within this pool. Traffic directed at this pool is balanced across all currently healthy origins, provided the pool itself is healthy. `[ { "name": "app-server-1", "address": "0.0.0.0", "enabled": true, "weight": 0.56 } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
description string	A human-readable description of the pool. `"Primary data center - Provider XYZ"`
enabled boolean	Whether to enable (the default) this pool. Disabled pools will not receive traffic and are excluded from health checks. Disabling a pool will cause any load balancers using it to failover to the next pool (if any). `true`	default value: true valid values: (true,false)
monitor string	The ID of the Monitor to use for health checking origins within this pool. `"f1aba936b94213e5b8dca0c0dbf1f9cc"`	max length: 32 read only
notification_email string	The email address to send health status notifications to. This can be an individual mailbox or a mailing list. `"[email protected]"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Primary data center - Provider XYZ","name":"primary-dc-1","enabled":true,"monitor":"f1aba936b94213e5b8dca0c0dbf1f9cc","origins":[{"name":"app-server-1","address":"0.0.0.0","enabled":true,"weight":0.56}],"notification_email":"[email protected]"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "17b5962d775c646f3f9725cbc7a53df4",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "description": "Primary data center - Provider XYZ",
    "name": "primary-dc-1",
    "enabled": true,
    "minimum_origins": 2,
    "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "origins": [
      {
        "name": "app-server-1",
        "address": "0.0.0.0",
        "enabled": true,
        "weight": 0.56
      }
    ],
    "notification_email": "[email protected]"
  }
}

account-load-balancer-pools-delete-pool

DELETE Delete Pool

Delete a configured pool

DELETE accounts/:account_identifier/load_balancers/pools/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "17b5962d775c646f3f9725cbc7a53df4"
  }
}

Organization Load Balancer Monitors

Organization-level Monitor configurations. Monitors define whether we check over HTTP, HTTPS or TCP, the status code(s) we look for, the interval at which we check, timeouts and response body matching.

organization-load-balancer-monitors

Object definition

View properties and constraints defined on the object

Show definition

organization-load-balancer-monitors-list-monitors

GET List Monitors

List configured monitors for an organization

GET organizations/:organization_identifier/load_balancers/monitors

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/load_balancers/monitors" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
      "created_on": "2014-01-01T05:20:00.12345Z",
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "type": "https",
      "description": "Login page monitor",
      "method": "GET",
      "path": "/health",
      "header": {
        "Host": [
          "example.com"
        ],
        "X-App-ID": [
          "abc123"
        ]
      },
      "port": 8080,
      "timeout": 3,
      "retries": 0,
      "interval": 90,
      "expected_body": "alive",
      "expected_codes": "2xx",
      "follow_redirects": true,
      "allow_insecure": true
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

organization-load-balancer-monitors-create-monitor

POST Create Monitor

Create a configured monitor

POST organizations/:organization_identifier/load_balancers/monitors

Required parameters

Name /type	Description /example	Constraints
expected_codes string	The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors. `"2xx"`	default value: 200

Optional parameters

Name /type	Description /example	Constraints
port integer	Port number to connect to for the health check. Required for TCP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443). `8080`	default value: 0
method string	The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks. `"GET"`	default value: GET
timeout integer	The timeout (in seconds) before marking the health check as failed `3`	default value: 5
path string	The endpoint path to health check against. This parameter is only valid for HTTP and HTTPS monitors. `"/health"`	default value: /
interval integer	The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations. `90`	default value: 60
retries integer	The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately. `0`	default value: 2
follow_redirects boolean	Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors. `true`	default value: false valid values: (true,false)
expected_body string	A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors. `"alive"`
header object	The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors. `{ "Host": [ "example.com" ], "X-App-ID": [ "abc123" ] }`
allow_insecure boolean	Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors. `true`	default value: false valid values: (true,false)
type string	The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS' and 'TCP'. `"https"`	default value: http
description string	Object description `"Login page monitor"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/load_balancers/monitors" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"https","description":"Login page monitor","method":"GET","path":"/health","header":{"Host":["example.com"],"X-App-ID":["abc123"]},"port":8080,"timeout":3,"retries":0,"interval":90,"expected_body":"alive","expected_codes":"2xx","follow_redirects":true,"allow_insecure":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "type": "https",
    "description": "Login page monitor",
    "method": "GET",
    "path": "/health",
    "header": {
      "Host": [
        "example.com"
      ],
      "X-App-ID": [
        "abc123"
      ]
    },
    "port": 8080,
    "timeout": 3,
    "retries": 0,
    "interval": 90,
    "expected_body": "alive",
    "expected_codes": "2xx",
    "follow_redirects": true,
    "allow_insecure": true
  }
}

organization-load-balancer-monitors-monitor-details

GET Monitor Details

List a single configured monitor for an organization

GET organizations/:organization_identifier/load_balancers/monitors/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/load_balancers/monitors/f1aba936b94213e5b8dca0c0dbf1f9cc" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "type": "https",
    "description": "Login page monitor",
    "method": "GET",
    "path": "/health",
    "header": {
      "Host": [
        "example.com"
      ],
      "X-App-ID": [
        "abc123"
      ]
    },
    "port": 8080,
    "timeout": 3,
    "retries": 0,
    "interval": 90,
    "expected_body": "alive",
    "expected_codes": "2xx",
    "follow_redirects": true,
    "allow_insecure": true
  }
}

organization-load-balancer-monitors-update-monitor

PUT Update Monitor

Modify a configured monitor

PUT organizations/:organization_identifier/load_balancers/monitors/:identifier

Required parameters

Name /type	Description /example	Constraints
expected_codes string	The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors. `"2xx"`	default value: 200

Optional parameters

Name /type	Description /example	Constraints
port integer	Port number to connect to for the health check. Required for TCP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443). `8080`	default value: 0
method string	The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks. `"GET"`	default value: GET
timeout integer	The timeout (in seconds) before marking the health check as failed `3`	default value: 5
path string	The endpoint path to health check against. This parameter is only valid for HTTP and HTTPS monitors. `"/health"`	default value: /
interval integer	The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations. `90`	default value: 60
retries integer	The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately. `0`	default value: 2
follow_redirects boolean	Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors. `true`	default value: false valid values: (true,false)
expected_body string	A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors. `"alive"`
header object	The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors. `{ "Host": [ "example.com" ], "X-App-ID": [ "abc123" ] }`
allow_insecure boolean	Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors. `true`	default value: false valid values: (true,false)
type string	The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS' and 'TCP'. `"https"`	default value: http
description string	Object description `"Login page monitor"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/load_balancers/monitors/f1aba936b94213e5b8dca0c0dbf1f9cc" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"https","description":"Login page monitor","method":"GET","path":"/health","header":{"Host":["example.com"],"X-App-ID":["abc123"]},"port":8080,"timeout":3,"retries":0,"interval":90,"expected_body":"alive","expected_codes":"2xx","follow_redirects":true,"allow_insecure":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "type": "https",
    "description": "Login page monitor",
    "method": "GET",
    "path": "/health",
    "header": {
      "Host": [
        "example.com"
      ],
      "X-App-ID": [
        "abc123"
      ]
    },
    "port": 8080,
    "timeout": 3,
    "retries": 0,
    "interval": 90,
    "expected_body": "alive",
    "expected_codes": "2xx",
    "follow_redirects": true,
    "allow_insecure": true
  }
}

organization-load-balancer-monitors-delete-monitor

DELETE Delete Monitor

Delete a configured monitor

DELETE organizations/:organization_identifier/load_balancers/monitors/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/load_balancers/monitors/f1aba936b94213e5b8dca0c0dbf1f9cc" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f1aba936b94213e5b8dca0c0dbf1f9cc"
  }
}

Organization Load Balancer Pools

Organization-level Load Balancer Pools

organization-load-balancer-pools

Object definition

View properties and constraints defined on the object

Show definition

organization-load-balancer-pools-list-pools

GET List Pools

List configured pools

GET organizations/:organization_identifier/load_balancers/pools

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/load_balancers/pools" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "17b5962d775c646f3f9725cbc7a53df4",
      "created_on": "2014-01-01T05:20:00.12345Z",
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "description": "Primary data center - Provider XYZ",
      "name": "primary-dc-1",
      "enabled": true,
      "minimum_origins": 2,
      "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
      "check_regions": [
        "WEU",
        "ENAM"
      ],
      "origins": [
        {
          "name": "app-server-1",
          "address": "0.0.0.0",
          "enabled": true,
          "weight": 0.56
        }
      ],
      "notification_email": "[email protected]"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

organization-load-balancer-pools-create-pool

POST Create Pool

Create a new pool

POST organizations/:organization_identifier/load_balancers/pools

Required parameters

Name /type	Description /example	Constraints
name string	A short name (tag) for the pool. Only alphanumeric characters, hyphens and underscores are allowed. `"primary-dc-1"`
origins array	The list of origins within this pool. Traffic directed at this pool is balanced across all currently healthy origins, provided the pool itself is healthy. `[ { "name": "app-server-1", "address": "0.0.0.0", "enabled": true, "weight": 0.56 } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
description string	A human-readable description of the pool. `"Primary data center - Provider XYZ"`
enabled boolean	Whether to enable (the default) this pool. Disabled pools will not receive traffic and are excluded from health checks. Disabling a pool will cause any load balancers using it to failover to the next pool (if any). `true`	default value: true valid values: (true,false)
minimum_origins integer	The minimum number of origins that must be healthy for this pool to serve traffic. If the number of healthy origins falls below this number, the pool will be marked unhealthy and we wil failover to the next available pool. `2`	default value: 1
monitor string	The ID of the Monitor to use for health checking origins within this pool. `"f1aba936b94213e5b8dca0c0dbf1f9cc"`	max length: 32 read only
notification_email string	The email address to send health status notifications to. This can be an individual mailbox or a mailing list. `"[email protected]"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/load_balancers/pools" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Primary data center - Provider XYZ","name":"primary-dc-1","enabled":true,"minimum_origins":2,"monitor":"f1aba936b94213e5b8dca0c0dbf1f9cc","origins":[{"name":"app-server-1","address":"0.0.0.0","enabled":true,"weight":0.56}],"notification_email":"[email protected]"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "17b5962d775c646f3f9725cbc7a53df4",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "description": "Primary data center - Provider XYZ",
    "name": "primary-dc-1",
    "enabled": true,
    "minimum_origins": 2,
    "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "origins": [
      {
        "name": "app-server-1",
        "address": "0.0.0.0",
        "enabled": true,
        "weight": 0.56
      }
    ],
    "notification_email": "[email protected]"
  }
}

organization-load-balancer-pools-pool-details

GET Pool Details

Fetch a single configured pool

GET organizations/:organization_identifier/load_balancers/pools/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "17b5962d775c646f3f9725cbc7a53df4",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "description": "Primary data center - Provider XYZ",
    "name": "primary-dc-1",
    "enabled": true,
    "minimum_origins": 2,
    "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "origins": [
      {
        "name": "app-server-1",
        "address": "0.0.0.0",
        "enabled": true,
        "weight": 0.56
      }
    ],
    "notification_email": "[email protected]"
  }
}

organization-load-balancer-pools-pool-health-details

GET Pool Health Details

Fetch latest healthcheck details for a single pool

GET organizations/:organization_identifier/load_balancers/pools/:identifier/health

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4/health" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "pool_id": "17b5962d775c646f3f9725cbc7a53df4",
    "pop_health": {
      "Amsterdam, NL": {
        "healthy": true,
        "origins": [
          {
            "2001:DB8::5": {
              "healthy": true,
              "rtt": "12.1ms",
              "failure_reason": "No failures",
              "response_code": 401
            }
          }
        ]
      }
    }
  }
}

organization-load-balancer-pools-update-pool

PUT Update Pool

Modify a configured pool

PUT organizations/:organization_identifier/load_balancers/pools/:identifier

Required parameters

Name /type	Description /example	Constraints
name string	A short name (tag) for the pool. Only alphanumeric characters, hyphens and underscores are allowed. `"primary-dc-1"`
origins array	The list of origins within this pool. Traffic directed at this pool is balanced across all currently healthy origins, provided the pool itself is healthy. `[ { "name": "app-server-1", "address": "0.0.0.0", "enabled": true, "weight": 0.56 } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
description string	A human-readable description of the pool. `"Primary data center - Provider XYZ"`
enabled boolean	Whether to enable (the default) this pool. Disabled pools will not receive traffic and are excluded from health checks. Disabling a pool will cause any load balancers using it to failover to the next pool (if any). `true`	default value: true valid values: (true,false)
monitor string	The ID of the Monitor to use for health checking origins within this pool. `"f1aba936b94213e5b8dca0c0dbf1f9cc"`	max length: 32 read only
notification_email string	The email address to send health status notifications to. This can be an individual mailbox or a mailing list. `"[email protected]"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Primary data center - Provider XYZ","name":"primary-dc-1","enabled":true,"monitor":"f1aba936b94213e5b8dca0c0dbf1f9cc","origins":[{"name":"app-server-1","address":"0.0.0.0","enabled":true,"weight":0.56}],"notification_email":"[email protected]"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "17b5962d775c646f3f9725cbc7a53df4",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "description": "Primary data center - Provider XYZ",
    "name": "primary-dc-1",
    "enabled": true,
    "minimum_origins": 2,
    "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "origins": [
      {
        "name": "app-server-1",
        "address": "0.0.0.0",
        "enabled": true,
        "weight": 0.56
      }
    ],
    "notification_email": "[email protected]"
  }
}

organization-load-balancer-pools-delete-pool

DELETE Delete Pool

Delete a configured pool

DELETE organizations/:organization_identifier/load_balancers/pools/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "17b5962d775c646f3f9725cbc7a53df4"
  }
}

Load Balancers

Zone-level Load Balancers

load-balancers

Object definition

View properties and constraints defined on the object

Show definition

load-balancers-list-load-balancers

GET List Load Balancers

List configured load balancers

GET zones/:identifier/load_balancers

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/load_balancers" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "699d98642c564d2e855e9661899b7252",
      "created_on": "2014-01-01T05:20:00.12345Z",
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "description": "Load Balancer for www.example.com",
      "name": "www.example.com",
      "enabled": true,
      "ttl": 30,
      "fallback_pool": "17b5962d775c646f3f9725cbc7a53df4",
      "default_pools": [
        "17b5962d775c646f3f9725cbc7a53df4",
        "9290f38c5d07c2e2f4df57b1f61d4196",
        "00920f38ce07c2e2f4df50b1f61d4194"
      ],
      "region_pools": {
        "WNAM": [
          "de90f38ced07c2e2f4df50b1f61d4194",
          "9290f38c5d07c2e2f4df57b1f61d4196"
        ],
        "ENAM": [
          "00920f38ce07c2e2f4df50b1f61d4194"
        ]
      },
      "pop_pools": {
        "LAX": [
          "de90f38ced07c2e2f4df50b1f61d4194",
          "9290f38c5d07c2e2f4df57b1f61d4196"
        ],
        "LHR": [
          "abd90f38ced07c2e2f4df50b1f61d4194",
          "f9138c5d07c2e2f4df57b1f61d4196"
        ],
        "SJC": [
          "00920f38ce07c2e2f4df50b1f61d4194"
        ]
      },
      "proxied": true,
      "steering_policy": "dynamic_latency",
      "session_affinity": "cookie",
      "session_affinity_ttl": 5000
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

load-balancers-create-load-balancer

POST Create Load Balancer

Create a new load balancer

POST zones/:identifier/load_balancers

Required parameters

Name /type	Description /example	Constraints
name string	The DNS hostname to associate with your Load Balancer. If this hostname already exists as a DNS record in Cloudflare's DNS, the Load Balancer will take precedence and the DNS record will not be used. `"www.example.com"`
default_pools array	A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. `[ "17b5962d775c646f3f9725cbc7a53df4", "9290f38c5d07c2e2f4df57b1f61d4196", "00920f38ce07c2e2f4df50b1f61d4194" ]`
fallback_pool string	The pool ID to use when all other pools are detected as unhealthy. `"17b5962d775c646f3f9725cbc7a53df4"`	max length: 32 read only

Optional parameters

Name /type	Description /example	Constraints
steering_policy string	Steering Policy for this load balancer. "off": use default_pools, "geo": use region_pools/pop_pools, "random": select a pool randomly, "dynamic_latency": use round trip time to select the closest pool in default_pools (requires pool health checks), "": will map to "geo" if you use region_pools/pop_pools otherwise "off" `"dynamic_latency"`	default value: "" valid values: off, geo, random, dynamic_latency, ""
pop_pools object	(Enterprise only): A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using default_pools. `{ "LAX": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "LHR": [ "abd90f38ced07c2e2f4df50b1f61d4194", "f9138c5d07c2e2f4df57b1f61d4196" ], "SJC": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }`
ttl number	Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. `30`
region_pools object	A mapping of region/country codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. `{ "WNAM": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "ENAM": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }`
session_affinity string	The session_affinity specifies the type of session affinity the loadbalancer should use unless specified as "none" or ""(default). The supported types are "cookie" and "ip_cookie". "cookie" - On the first request to a proxied load balancer, a cookie is generated, encoding information of which origin the request will be forwarded to. Subsequent requests, by the same client to the same load balancer, will be sent to the origin server the cookie encodes, for the duration of the cookie and as long as the origin server remains healthy. If the cookie has expired or the origin server is unhealthy then a new origin server is calculated and used. "ip_cookie" behaves the same as "cookie" except the initial origin selection is stable and based on the client’s ip address. `"cookie"`	default value: "" valid values: none, cookie, ip_cookie, ""
description string	Object description `"Load Balancer for www.example.com"`
proxied boolean	Whether the hostname should be gray clouded (false) or orange clouded (true). `true`	default value: false valid values: (true,false)
session_affinity_ttl number	Time, in seconds, until this load balancers session affinity cookie expires after being created. This parameter is ignored unless a supported session affinity policy is set. The current default of 23 hours will be used unless session_affinity_ttl is explicitly set. The accepted range of values is between [1800, 604800]. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. `5000`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/load_balancers" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Load Balancer for www.example.com","name":"www.example.com","ttl":30,"fallback_pool":"17b5962d775c646f3f9725cbc7a53df4","default_pools":["17b5962d775c646f3f9725cbc7a53df4","9290f38c5d07c2e2f4df57b1f61d4196","00920f38ce07c2e2f4df50b1f61d4194"],"region_pools":{"WNAM":["de90f38ced07c2e2f4df50b1f61d4194","9290f38c5d07c2e2f4df57b1f61d4196"],"ENAM":["00920f38ce07c2e2f4df50b1f61d4194"]},"pop_pools":{"LAX":["de90f38ced07c2e2f4df50b1f61d4194","9290f38c5d07c2e2f4df57b1f61d4196"],"LHR":["abd90f38ced07c2e2f4df50b1f61d4194","f9138c5d07c2e2f4df57b1f61d4196"],"SJC":["00920f38ce07c2e2f4df50b1f61d4194"]},"proxied":true,"steering_policy":"dynamic_latency","session_affinity":"cookie","session_affinity_ttl":5000}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "699d98642c564d2e855e9661899b7252",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "description": "Load Balancer for www.example.com",
    "name": "www.example.com",
    "enabled": true,
    "ttl": 30,
    "fallback_pool": "17b5962d775c646f3f9725cbc7a53df4",
    "default_pools": [
      "17b5962d775c646f3f9725cbc7a53df4",
      "9290f38c5d07c2e2f4df57b1f61d4196",
      "00920f38ce07c2e2f4df50b1f61d4194"
    ],
    "region_pools": {
      "WNAM": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "9290f38c5d07c2e2f4df57b1f61d4196"
      ],
      "ENAM": [
        "00920f38ce07c2e2f4df50b1f61d4194"
      ]
    },
    "pop_pools": {
      "LAX": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "9290f38c5d07c2e2f4df57b1f61d4196"
      ],
      "LHR": [
        "abd90f38ced07c2e2f4df50b1f61d4194",
        "f9138c5d07c2e2f4df57b1f61d4196"
      ],
      "SJC": [
        "00920f38ce07c2e2f4df50b1f61d4194"
      ]
    },
    "proxied": true,
    "steering_policy": "dynamic_latency",
    "session_affinity": "cookie",
    "session_affinity_ttl": 5000
  }
}

load-balancers-load-balancer-details

GET Load Balancer Details

Fetch a single configured load balancer

GET zones/:identifier/load_balancers/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/load_balancers/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "699d98642c564d2e855e9661899b7252",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "description": "Load Balancer for www.example.com",
    "name": "www.example.com",
    "enabled": true,
    "ttl": 30,
    "fallback_pool": "17b5962d775c646f3f9725cbc7a53df4",
    "default_pools": [
      "17b5962d775c646f3f9725cbc7a53df4",
      "9290f38c5d07c2e2f4df57b1f61d4196",
      "00920f38ce07c2e2f4df50b1f61d4194"
    ],
    "region_pools": {
      "WNAM": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "9290f38c5d07c2e2f4df57b1f61d4196"
      ],
      "ENAM": [
        "00920f38ce07c2e2f4df50b1f61d4194"
      ]
    },
    "pop_pools": {
      "LAX": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "9290f38c5d07c2e2f4df57b1f61d4196"
      ],
      "LHR": [
        "abd90f38ced07c2e2f4df50b1f61d4194",
        "f9138c5d07c2e2f4df57b1f61d4196"
      ],
      "SJC": [
        "00920f38ce07c2e2f4df50b1f61d4194"
      ]
    },
    "proxied": true,
    "steering_policy": "dynamic_latency",
    "session_affinity": "cookie",
    "session_affinity_ttl": 5000
  }
}

load-balancers-update-load-balancer

PUT Update Load Balancer

Update a configured load balancer

PUT zones/:identifier/load_balancers/:identifier

Required parameters

Name /type	Description /example	Constraints
name string	The DNS hostname to associate with your Load Balancer. If this hostname already exists as a DNS record in Cloudflare's DNS, the Load Balancer will take precedence and the DNS record will not be used. `"www.example.com"`
default_pools array	A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. `[ "17b5962d775c646f3f9725cbc7a53df4", "9290f38c5d07c2e2f4df57b1f61d4196", "00920f38ce07c2e2f4df50b1f61d4194" ]`
fallback_pool string	The pool ID to use when all other pools are detected as unhealthy. `"17b5962d775c646f3f9725cbc7a53df4"`	max length: 32 read only

Optional parameters

Name /type	Description /example	Constraints
steering_policy string	Steering Policy for this load balancer. "off": use default_pools, "geo": use region_pools/pop_pools, "random": select a pool randomly, "dynamic_latency": use round trip time to select the closest pool in default_pools (requires pool health checks), "": will map to "geo" if you use region_pools/pop_pools otherwise "off" `"dynamic_latency"`	default value: "" valid values: off, geo, random, dynamic_latency, ""
enabled boolean	Whether to enable (the default) this load balancer. `true`	default value: true valid values: (true,false)
pop_pools object	(Enterprise only): A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using default_pools. `{ "LAX": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "LHR": [ "abd90f38ced07c2e2f4df50b1f61d4194", "f9138c5d07c2e2f4df57b1f61d4196" ], "SJC": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }`
ttl number	Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. `30`
region_pools object	A mapping of region/country codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. `{ "WNAM": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "ENAM": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }`
session_affinity string	The session_affinity specifies the type of session affinity the loadbalancer should use unless specified as "none" or ""(default). The supported types are "cookie" and "ip_cookie". "cookie" - On the first request to a proxied load balancer, a cookie is generated, encoding information of which origin the request will be forwarded to. Subsequent requests, by the same client to the same load balancer, will be sent to the origin server the cookie encodes, for the duration of the cookie and as long as the origin server remains healthy. If the cookie has expired or the origin server is unhealthy then a new origin server is calculated and used. "ip_cookie" behaves the same as "cookie" except the initial origin selection is stable and based on the client’s ip address. `"cookie"`	default value: "" valid values: none, cookie, ip_cookie, ""
description string	Object description `"Load Balancer for www.example.com"`
proxied boolean	Whether the hostname should be gray clouded (false) or orange clouded (true). `true`	default value: false valid values: (true,false)
session_affinity_ttl number	Time, in seconds, until this load balancers session affinity cookie expires after being created. This parameter is ignored unless a supported session affinity policy is set. The current default of 23 hours will be used unless session_affinity_ttl is explicitly set. The accepted range of values is between [1800, 604800]. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. `5000`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/load_balancers/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Load Balancer for www.example.com","name":"www.example.com","ttl":30,"fallback_pool":"17b5962d775c646f3f9725cbc7a53df4","default_pools":["17b5962d775c646f3f9725cbc7a53df4","9290f38c5d07c2e2f4df57b1f61d4196","00920f38ce07c2e2f4df50b1f61d4194"],"region_pools":{"WNAM":["de90f38ced07c2e2f4df50b1f61d4194","9290f38c5d07c2e2f4df57b1f61d4196"],"ENAM":["00920f38ce07c2e2f4df50b1f61d4194"]},"pop_pools":{"LAX":["de90f38ced07c2e2f4df50b1f61d4194","9290f38c5d07c2e2f4df57b1f61d4196"],"LHR":["abd90f38ced07c2e2f4df50b1f61d4194","f9138c5d07c2e2f4df57b1f61d4196"],"SJC":["00920f38ce07c2e2f4df50b1f61d4194"]},"proxied":true,"enabled":true,"steering_policy":"dynamic_latency","session_affinity":"cookie","session_affinity_ttl":5000}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "699d98642c564d2e855e9661899b7252",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "description": "Load Balancer for www.example.com",
    "name": "www.example.com",
    "enabled": true,
    "ttl": 30,
    "fallback_pool": "17b5962d775c646f3f9725cbc7a53df4",
    "default_pools": [
      "17b5962d775c646f3f9725cbc7a53df4",
      "9290f38c5d07c2e2f4df57b1f61d4196",
      "00920f38ce07c2e2f4df50b1f61d4194"
    ],
    "region_pools": {
      "WNAM": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "9290f38c5d07c2e2f4df57b1f61d4196"
      ],
      "ENAM": [
        "00920f38ce07c2e2f4df50b1f61d4194"
      ]
    },
    "pop_pools": {
      "LAX": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "9290f38c5d07c2e2f4df57b1f61d4196"
      ],
      "LHR": [
        "abd90f38ced07c2e2f4df50b1f61d4194",
        "f9138c5d07c2e2f4df57b1f61d4196"
      ],
      "SJC": [
        "00920f38ce07c2e2f4df50b1f61d4194"
      ]
    },
    "proxied": true,
    "steering_policy": "dynamic_latency",
    "session_affinity": "cookie",
    "session_affinity_ttl": 5000
  }
}

load-balancers-delete-load-balancer

DELETE Delete Load Balancer

Delete a configured load balancer

DELETE zones/:identifier/load_balancers/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/load_balancers/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "699d98642c564d2e855e9661899b7252"
  }
}

Railgun

Cloudflare Railgun

railgun

Object definition

View properties and constraints defined on the object

Show definition

railgun-list-railguns

GET List Railguns
free
pro
business
enterprise

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: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "e928d310693a83094309acf9ead50448",
      "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": 1,
    "total_count": 2000
  }
}

railgun-create-railgun

POST Create Railgun
free
pro
business
enterprise

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: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"My Railgun"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": []
}

railgun-railgun-details

GET Railgun Details
free
pro
business
enterprise

GET railguns/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/railguns/e928d310693a83094309acf9ead50448" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": []
}

railgun-enable-or-disable-a-railgun

PATCH Enable or Disable a Railgun
free
pro
business
enterprise

Enable or disable a Railgun for all zones connected to it

PATCH railguns/:identifier

Required parameters

Name /type	Description /example	Constraints
enabled boolean	Flag to determine if the Railgun is accepting connections `true`	default value: false valid values: (true,false)

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/railguns/e928d310693a83094309acf9ead50448" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"enabled":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": []
}

railgun-delete-railgun

DELETE Delete Railgun
free
pro
business
enterprise

Disable and delete a Railgun. This will immediately disable the Railgun for any connected zones

DELETE railguns/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/railguns/e928d310693a83094309acf9ead50448" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "e928d310693a83094309acf9ead50448"
  }
}

railgun-list-railgun-zones

GET List Railgun Zones
free
pro
business
enterprise

The zones that are currently using this Railgun

GET railguns/:identifier/zones

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/railguns/e928d310693a83094309acf9ead50448/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": "023e105f4ecef8ad9ca31a8372d0c353",
      "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",
      "activated_on": "2014-01-02T00:01:00.12345Z"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

Railgun Connections for a Zone

Railguns associated with a zone

railgun-connections-for-a-zone

Object definition

View properties and constraints defined on the object

Show definition

railgun-connections-for-a-zone-list-available-railguns

GET List Available Railguns permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/railguns" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "e928d310693a83094309acf9ead50448",
      "name": "My Railgun",
      "enabled": true,
      "connected": true
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

railgun-connections-for-a-zone-railgun-details

GET Railgun Details permission needed: #zone_settings:read
free
pro
business
enterprise

Details about a specific Railgun

GET zones/:zone_identifier/railguns/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/railguns/e928d310693a83094309acf9ead50448" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "e928d310693a83094309acf9ead50448",
    "name": "My Railgun",
    "enabled": true,
    "connected": true
  }
}

railgun-connections-for-a-zone-connect-or-disconnect-a-railgun

PATCH Connect or Disconnect a Railgun permission needed: #zone_settings:edit
free
pro
business
enterprise

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`	default value: false valid values: (true,false)

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/railguns/e928d310693a83094309acf9ead50448" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"connected":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "e928d310693a83094309acf9ead50448",
    "name": "My Railgun",
    "enabled": true,
    "connected": true
  }
}

railgun-connections-for-a-zone-test-railgun-connection

GET Test Railgun Connection permission needed: #zone_settings:read
free
pro
business
enterprise

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/023e105f4ecef8ad9ca31a8372d0c353/railguns/e928d310693a83094309acf9ead50448/diagnose" \
     -H "X-Auth-Email: [email protected]" \
     -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
  }
}

Account Railguns

Cloudflare Railguns available to Accounts

account-railguns

Object definition

View properties and constraints defined on the object

Show definition

account-railguns-list-railguns

GET List Railguns permission needed: #organization:read
free
pro
business
enterprise

List, search, sort and filter your Railguns

GET accounts/:account_identifier/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	Direction to order Railguns `"desc"`	valid values: asc, desc

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/railguns?page=1&per_page=20&direction=desc" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "e928d310693a83094309acf9ead50448",
      "name": "My Railgun",
      "status": "active",
      "enabled": true,
      "zones_connected": 2,
      "created_on": "2014-01-01T05:20:00Z",
      "modified_on": "2014-01-01T05:20:00Z",
      "activation": {
        "key": "e4edc00281cb56ebac22c81be9bac8f3",
        "activated_on": "2014-01-02T02:20:00Z",
        "version": {
          "number": "2.1",
          "build": "b1234",
          "revision": "123"
        }
      }
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

account-railguns-create-railgun

POST Create Railgun
free
pro
business
enterprise

POST accounts/:account_identifier/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/accounts/01a7362d577a6c3019a474fd6f485823/railguns" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"My Railgun"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": []
}

account-railguns-railgun-details

GET Railgun Details permission needed: #organization:read
free
pro
business
enterprise

GET accounts/:account_identifier/railguns/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/railguns/e928d310693a83094309acf9ead50448" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": []
}

account-railguns-update-railgun

PUT Update Railgun permission needed: #organization:edit
free
pro
business
enterprise

Update a Railgun

PUT accounts/:account_identifier/railguns/:identifier

Required parameters

Name /type	Description /example	Constraints
enabled boolean	Flag to determine if the Railgun is accepting connections `true`	default value: false valid values: (true,false)
name string	Readable identifier of the railgun `"My Railgun"`	max length: 160
zones_connected number	The number of zones using this railgun `2`	read only
status string	Status of the railgun `"active"`	valid values: initializing, active read only
activation object	`{ "key": "e4edc00281cb56ebac22c81be9bac8f3", "activated_on": "2014-01-02T02:20:00Z", "version": { "number": "2.1", "build": "b1234", "revision": "123" } }` An object with the following properties: Show definition »	read only
id string	Railgun identifier tag `"e928d310693a83094309acf9ead50448"`	max length: 32 read only

Optional parameters

Name /type	Description /example	Constraints
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" }` An object with the following properties: Show definition »
modified_on string (date-time)	When the Railgun was last modified `"2014-01-01T05:20:00Z"`	read only
created_on string (date-time)	When the Railgun was created `"2014-01-01T05:20:00Z"`	read only

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/railguns/e928d310693a83094309acf9ead50448" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"e928d310693a83094309acf9ead50448","name":"My Railgun","status":"active","enabled":true,"zones_connected":2,"created_on":"2014-01-01T05:20:00Z","modified_on":"2014-01-01T05:20:00Z","activation":{"key":"e4edc00281cb56ebac22c81be9bac8f3","activated_on":"2014-01-02T02:20:00Z","version":{"number":"2.1","build":"b1234","revision":"123"}}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": []
}

account-railguns-delete-railgun

DELETE Delete Railgun permission needed: #organization:edit
free
pro
business
enterprise

Disable and delete a Railgun. This will immediately disable the Railgun for any connected zones

DELETE accounts/:account_identifier/railguns/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/railguns/e928d310693a83094309acf9ead50448" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "e928d310693a83094309acf9ead50448"
  }
}

Railgun Connections

A Railgun connection associates a zone with the Railgun

railgun-connections

Object definition

View properties and constraints defined on the object

Show definition

railgun-connections-list-connections

GET List Connections permission needed: #organization:read
free
pro
business
enterprise

List connections associated with the Railgun

GET accounts/:account_identifier/railguns/:railgun_identifier/connections

Optional parameters

Name /type	Description /example	Constraints
page number	Requested page within paginated list of results `1`
per_page number	Maximum number of results requested `20`
enabled boolean	A value indicating whether the connection is enabled or not `true`	default value: false valid values: (true,false)

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/railguns/e928d310693a83094309acf9ead50448/connections?page=1&per_page=20&enabled=true" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "c4a7362d577a6c3019a474fd6f485821",
      "zone": {
        "id": "023e105f4ecef8ad9ca31a8372d0c353",
        "name": "example.com"
      },
      "enabled": true,
      "created_on": "2017-06-14T00:00:00Z",
      "modified_on": "2017-06-14T05:20:00Z"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

railgun-connections-connection-details

GET Connection Details permission needed: #organization:read
free
pro
business
enterprise

Get a connection by ID

GET accounts/:account_identifier/railguns/:railgun_identifier/connections/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/railguns/e928d310693a83094309acf9ead50448/connections/c4a7362d577a6c3019a474fd6f485821" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "c4a7362d577a6c3019a474fd6f485821",
    "zone": {
      "id": "023e105f4ecef8ad9ca31a8372d0c353",
      "name": "example.com"
    },
    "enabled": true,
    "created_on": "2017-06-14T00:00:00Z",
    "modified_on": "2017-06-14T05:20:00Z"
  }
}

railgun-connections-update-connection

PUT Update Connection permission needed: #organization:edit
free
pro
business
enterprise

Enable or disable a connection

PUT accounts/:account_identifier/railguns/:railgun_identifier/connections/:identifier

Required parameters

Name /type	Description /example	Constraints
id string	Connection identifier tag `"c4a7362d577a6c3019a474fd6f485821"`	max length: 32 read only
zone object	`{ "id": "023e105f4ecef8ad9ca31a8372d0c353", "name": "example.com" }` An object with the following properties: Show definition »
enabled boolean	A value indicating whether the connection is enabled or not `true`	default value: false valid values: (true,false)

Optional parameters

Name /type	Description /example	Constraints
created_on string (date-time)	When the connection was created `"2017-06-14T00:00:00Z"`	read only
modified_on string (date-time)	When the connection was last modified `"2017-06-14T05:20:00Z"`	read only

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/railguns/e928d310693a83094309acf9ead50448/connections/c4a7362d577a6c3019a474fd6f485821" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"c4a7362d577a6c3019a474fd6f485821","zone":{"id":"023e105f4ecef8ad9ca31a8372d0c353","name":"example.com"},"enabled":true,"created_on":"2017-06-14T00:00:00Z","modified_on":"2017-06-14T05:20:00Z"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "c4a7362d577a6c3019a474fd6f485821",
    "zone": {
      "id": "023e105f4ecef8ad9ca31a8372d0c353",
      "name": "example.com"
    },
    "enabled": true,
    "created_on": "2017-06-14T00:00:00Z",
    "modified_on": "2017-06-14T05:20:00Z"
  }
}

railgun-connections-delete-connection

DELETE Delete Connection permission needed: #organization:edit
free
pro
business
enterprise

Disable and remove the connection to a zone

DELETE accounts/:account_identifier/railguns/:railgun_identifier/connections/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/railguns/e928d310693a83094309acf9ead50448/connections/c4a7362d577a6c3019a474fd6f485821" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "c4a7362d577a6c3019a474fd6f485821"
  }
}

railgun-connections-create-connection

POST Create Connection permission needed: #organization:edit
free
pro
business
enterprise

Associates a zone to the Railgun

POST accounts/:account_identifier/railguns/:railgun_identifier/connections

Required parameters

Name /type	Description /example	Constraints
zone	`{ "id": "023e105f4ecef8ad9ca31a8372d0c353" }` An object with the following properties: Show definition »

Optional parameters

Name /type	Description /example	Constraints
enabled boolean	A value indicating whether the connection is enabled or not `true`	default value: false valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/railguns/e928d310693a83094309acf9ead50448/connections" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"zone":{"id":"023e105f4ecef8ad9ca31a8372d0c353"},"enabled":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "c4a7362d577a6c3019a474fd6f485821",
    "zone": {
      "id": "023e105f4ecef8ad9ca31a8372d0c353",
      "name": "example.com"
    },
    "enabled": true,
    "created_on": "2017-06-14T00:00:00Z",
    "modified_on": "2017-06-14T05:20:00Z"
  }
}

Railgun Connections error codes

Code	Description

Organization Railgun

Cloudflare Railgun for Organizations

organization-railgun

Object definition

View properties and constraints defined on the object

Show definition

organization-railgun-list-railguns

GET List Railguns
free
pro
business
enterprise

List, search, sort and filter your Railguns

GET organizations/:organization_identifier/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	Direction to order Railguns `"desc"`	valid values: asc, desc

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/railguns?page=1&per_page=20&direction=desc" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "e928d310693a83094309acf9ead50448",
      "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": 1,
    "total_count": 2000
  }
}

organization-railgun-create-railgun

POST Create Railgun
free
pro
business
enterprise

POST organizations/:organization_identifier/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/organizations/01a7362d577a6c3019a474fd6f485823/railguns" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"My Railgun"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": []
}

organization-railgun-railgun-details

GET Railgun Details
free
pro
business
enterprise

GET organizations/:organization_identifier/railguns/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/railguns/e928d310693a83094309acf9ead50448" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": []
}

organization-railgun-enable-or-disable-a-railgun

PATCH Enable or Disable a Railgun
free
pro
business
enterprise

Enable or disable a Railgun for all zones connected to it

PATCH organizations/:organization_identifier/railguns/:identifier

Required parameters

Name /type	Description /example	Constraints
enabled boolean	Flag to determine if the Railgun is accepting connections `true`	default value: false valid values: (true,false)

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/railguns/e928d310693a83094309acf9ead50448" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"enabled":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": []
}

organization-railgun-delete-railgun

DELETE Delete Railgun
free
pro
business
enterprise

Disable and delete a Railgun. This will immediately disable the Railgun for any connected zones

DELETE organizations/:organization_identifier/railguns/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/railguns/e928d310693a83094309acf9ead50448" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "e928d310693a83094309acf9ead50448"
  }
}

organization-railgun-get-railgun-zones

GET Get Railgun Zones
free
pro
business
enterprise

The zones that are currently using this Railgun

GET organizations/:organization_identifier/railguns/:identifier/zones

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/organizations/01a7362d577a6c3019a474fd6f485823/railguns/e928d310693a83094309acf9ead50448/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": "023e105f4ecef8ad9ca31a8372d0c353",
      "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",
      "activated_on": "2014-01-02T00:01:00.12345Z"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

AML

Accelerated Mobile Links

aml

Object definition

View properties and constraints defined on the object

Show definition

aml-aml-viewer-details

GET AML Viewer Details permission needed: #zone_settings:edit
free
pro
business
enterprise

Fetch AML configuration for a zone

GET zones/:zone_identifier/amp/viewer

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/amp/viewer" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "enabled": false,
    "subdomains": [],
    "prepend_links_with": null
  }
}

aml-update-aml-viewer

PUT Update AML Viewer permission needed: #zone_settings:edit
free
pro
business
enterprise

Update AML configuration for a zone

PUT zones/:zone_identifier/amp/viewer

Required parameters

Name /type	Description /example	Constraints
enabled boolean	Enable Accelerated Mobile Links on mobile browsers. `false`	default value: false valid values: (true,false)
subdomains array	List of subdomains to apply AML to. If value is empty, AML will apply to entire zone. `[]`	default value: List []

Optional parameters

Name /type	Description /example	Constraints
prepend_links_with string	Prepend AML links with a string. If value is null, links are prepended with AMP symbol. `null`	default value: null

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/amp/viewer" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"enabled":false,"subdomains":[],"prepend_links_with":null}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "enabled": false,
    "subdomains": [],
    "prepend_links_with": null
  }
}

Custom Pages (Account)

Custom pages at the account level

custom-pages-account-

Object definitions

View properties and constraints defined on the object

Show definitions

custom-pages-account--list-custom-pages

GET List Custom Pages permission needed: #organization:read
free
pro
business
enterprise

A list of available account-level Custom Pages

GET accounts/:account_identifier/custom_pages

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/custom_pages" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "basic_challenge",
      "created_on": "2014-01-01T05:20:00.12345Z",
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "url": "http://www.example.com",
      "state": "default",
      "required_tokens": [
        "::CAPTCHA_BOX::"
      ],
      "preview_target": "preview:target",
      "description": true
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

custom-pages-account--custom-page-details

GET Custom Page Details permission needed: #organization:read
free
pro
business
enterprise

Details about a specific Custom page details

GET accounts/:account_identifier/custom_pages/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/custom_pages/basic_challenge" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "basic_challenge",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "url": "http://www.example.com",
    "state": "default",
    "required_tokens": [
      "::CAPTCHA_BOX::"
    ],
    "preview_target": "preview:target",
    "description": true
  }
}

custom-pages-account--update-custom-page

PUT Update Custom Page permission needed: #organization:edit
free
pro
business
enterprise

Update custom page

PUT accounts/:account_identifier/custom_pages/:identifier

Required parameters

Name /type	Description /example	Constraints
url string (url)	A URL that is associated with the Custom Page. `"http://www.example.com"`	default value:
state	The Custom Page state `"default"`	valid values: default, customized

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/custom_pages/basic_challenge" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"url":"http://www.example.com","state":"default"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "basic_challenge",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "url": "http://www.example.com",
    "state": "default",
    "required_tokens": [
      "::CAPTCHA_BOX::"
    ],
    "preview_target": "preview:target",
    "description": true
  }
}

Custom Pages (Account) error codes

Code	Description
1000	Invalid user
1001	Invalid request. Could not connect to database
1002	Validator dispatcher expects an array
1006	Cannot find a valid customization page
1007	Invalid validation method being called
1200	A URL is required
1201	The URL provided seems to be irregular
1202	Unable to grab the content for the URL provided. Please try again.
1203	Your custom page must be larger than <characters> characters
1204	Your custom page must be smaller than <characters> characters
1205	A <token> token was not detected on the error page, and must be added before this page can be integrated into Cloudflare. The default error page will show until this is corrected and rescanned.
1206	Could not find a valid zone
1207	That customization page is not modifiable
1208	An unknown error has occurred and has been logged. We will fix this problem promptly. We apologize for the inconvenience.
1209	Could not find a valid customization page for this operation
1210	That operation is no longer allowed for that domain.
1211	Could not find a valid customization page to disable
1212	An undocumented error has occurred and has been logged.
1213	That operation has already been performed for this challenge/error.
1214	Rate limit reached for this operation. Please try again in a minute
1215	Rate limit reached for this operation. Please try again in a minute
1217	Invalid state passed
1218	Missing Custom Page state
1219	Please upgrade to access this feature
1220	We were unable to scan the page provided. Please ensure it is accessible publicly and is larger than 100 characters

Access Applications

Access Applications define the routes that Access will block.

access-applications

Object definition

View properties and constraints defined on the object

Show definition

access-applications-list-access-applications

GET List Access Applications

List Access Applications for a zone

GET zones/:identifier/access/apps

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/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": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z",
      "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893",
      "name": "Admin Site",
      "domain": "test.example.com/admin",
      "session_duration": "24h"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

access-applications-access-applications-details

GET Access Applications Details

Fetch a single Access Application

GET zones/:identifier/access/apps/:uuid

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893",
    "name": "Admin Site",
    "domain": "test.example.com/admin",
    "session_duration": "24h"
  }
}

access-applications-create-access-application

POST Create Access Application

Create a new Access Application

POST zones/:identifier/access/apps

Required parameters

Name /type	Description /example	Constraints
name string	The name of the Application. `"Admin Site"`
domain string	The domain and path that Access will block `"test.example.com/admin"`

Optional parameters

Name /type	Description /example	Constraints
session_duration string	Defines the amount of time that the tokens issued for this application will be valid `"24h"`	valid values: 30m, 6h, 12h, 24h, 168h, 730h

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Admin Site","domain":"test.example.com/admin","session_duration":"24h"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893",
    "name": "Admin Site",
    "domain": "test.example.com/admin",
    "session_duration": "24h"
  }
}

access-applications-update-access-application

PUT Update Access Application

Update a configured Access Application

PUT zones/:identifier/access/apps/:uuid

Required parameters

Name /type	Description /example	Constraints
name string	The name of the Application. `"Admin Site"`
domain string	The domain and path that Access will block `"test.example.com/admin"`

Optional parameters

Name /type	Description /example	Constraints
session_duration string	Defines the amount of time that the tokens issued for this application will be valid `"24h"`	valid values: 30m, 6h, 12h, 24h, 168h, 730h

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Admin Site","domain":"test.example.com/admin","session_duration":"24h"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893",
    "name": "Admin Site",
    "domain": "test.example.com/admin",
    "session_duration": "24h"
  }
}

access-applications-delete-access-application

DELETE Delete Access Application

Delete an Access Application

DELETE zones/:identifier/access/apps/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
  }
}

access-applications-revoke-access-tokens

POST Revoke Access Tokens

Revoke any outstanding tokens issued for the Application.

POST zones/:identifier/access/apps/:uuid/revoke-tokens

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/revoke-tokens" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true
}

Access Policy

Access Policies define the users or groups who can, or cannot, reach the Application Resource.

https://developers.cloudflare.com/access/setting-up-access/configuring-access-policies/

access-policy

Object definition

View properties and constraints defined on the object

Show definition

access-policy-list-access-policies

GET List Access Policies

List Access Policies for an Access Application

GET zones/:identifier/access/apps/:uuid/policies

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/policies" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "precedence": "1",
      "decision": "allow",
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z",
      "name": "Allow devs",
      "include": [
        {
          "email": {
            "email": "[email protected]"
          }
        }
      ],
      "exclude": [
        {
          "email": {
            "email": "[email protected]"
          }
        }
      ],
      "require": [
        {
          "email": {
            "email": "[email protected]"
          }
        }
      ]
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

access-policy-access-policy-details

GET Access Policy Details

Fetch a single Access Policy

GET zones/:identifier/access/apps/:uuid/policies/:uuid

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/policies/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "precedence": "1",
    "decision": "allow",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "name": "Allow devs",
    "include": [
      {
        "email": {
          "email": "[email protected]"
        }
      }
    ],
    "exclude": [
      {
        "email": {
          "email": "[email protected]"
        }
      }
    ],
    "require": [
      {
        "email": {
          "email": "[email protected]"
        }
      }
    ]
  }
}

access-policy-create-access-policy

POST Create Access Policy

Create a new Access Policy

POST zones/:identifier/access/apps/:uuid/policies

Required parameters

Name /type	Description /example	Constraints
decision string	Defines the action Access will take if the policy matches the user. `"allow"`	valid values: allow, deny, bypass
name string	The name of the policy. Only used in the UI. `"Allow devs"`
include array	The include policy works like an OR logical operator. The user must satisfy one of the rules in includes. `[ { "email": { "email": "[email protected]" } } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
precedence integer	The unique precedence for policies on a single application `"1"`
exclude array	The exclude policy works like a NOT logical operator. The user must not satisfy all of the rules in exclude. `[ { "email": { "email": "[email protected]" } } ]` An array with items in the following form: Show definition »
require array	The require policy works like a AND logical operator. The user must satisfy all of the rules in require. `[ { "email": { "email": "[email protected]" } } ]` An array with items in the following form: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/policies" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"precedence":"1","decision":"allow","name":"Allow devs","include":[{"email":{"email":"[email protected]"}}],"exclude":[{"email":{"email":"[email protected]"}}],"require":[{"email":{"email":"[email protected]"}}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "precedence": "1",
    "decision": "allow",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "name": "Allow devs",
    "include": [
      {
        "email": {
          "email": "[email protected]"
        }
      }
    ],
    "exclude": [
      {
        "email": {
          "email": "[email protected]"
        }
      }
    ],
    "require": [
      {
        "email": {
          "email": "[email protected]"
        }
      }
    ]
  }
}

access-policy-update-access-policy

PUT Update Access Policy

Update a configured Access Policy

PUT zones/:identifier/access/apps/:uuid/policies/:uuid

Required parameters

Name /type	Description /example	Constraints
decision string	Defines the action Access will take if the policy matches the user. `"allow"`	valid values: allow, deny, bypass
name string	The name of the policy. Only used in the UI. `"Allow devs"`
include array	The include policy works like an OR logical operator. The user must satisfy one of the rules in includes. `[ { "email": { "email": "[email protected]" } } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
precedence integer	The unique precedence for policies on a single application `"1"`
exclude array	The exclude policy works like a NOT logical operator. The user must not satisfy all of the rules in exclude. `[ { "email": { "email": "[email protected]" } } ]` An array with items in the following form: Show definition »
require array	The require policy works like a AND logical operator. The user must satisfy all of the rules in require. `[ { "email": { "email": "[email protected]" } } ]` An array with items in the following form: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/policies/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"precedence":"1","decision":"allow","name":"Allow devs","include":[{"email":{"email":"[email protected]"}}],"exclude":[{"email":{"email":"[email protected]"}}],"require":[{"email":{"email":"[email protected]"}}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "precedence": "1",
    "decision": "allow",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "name": "Allow devs",
    "include": [
      {
        "email": {
          "email": "[email protected]"
        }
      }
    ],
    "exclude": [
      {
        "email": {
          "email": "[email protected]"
        }
      }
    ],
    "require": [
      {
        "email": {
          "email": "[email protected]"
        }
      }
    ]
  }
}

access-policy-delete-access-policy

DELETE Delete Access Policy

Delete an Access Policy

DELETE zones/:identifier/access/apps/:uuid/policies/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/policies/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
  }
}

Registrar Domains

Manage Domains Names

registrar-domains

Object definition

View properties and constraints defined on the object

Show definition

registrar-domains-list-domains

POST List Domains

List domains handled by registrar

POST accounts/:account_identifier/registrar/domains

Required parameters

Name /type	Description /example	Constraints
id array	List of domain names `[ "cloudflare.com", "cloudflare.net" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/registrar/domains" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":["cloudflare.com","cloudflare.net"]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "ea95132c15732412d22c1476fa83f27a",
      "available": false,
      "supported_tld": true,
      "can_register": false,
      "transfer_in": {
        "unlock_domain": "ok",
        "disable_privacy": "ok",
        "enter_auth_code": "needed",
        "approve_transfer": "unknown",
        "accept_foa": "needed",
        "can_cancel_transfer": true
      },
      "current_registrar": "Cloudflare",
      "expires_at": "2019-08-28T23:59:59Z",
      "registry_statuses": "ok,serverTransferProhibited",
      "locked": false,
      "created_at": "2018-08-28T17:26:26Z",
      "updated_at": "2018-08-28T17:26:26Z",
      "registrant_contact": {
        "id": "ea95132c15732412d22c1476fa83f27a",
        "first_name": "John",
        "last_name": "Appleseed",
        "organization": "Cloudflare, Inc.",
        "address": "123 Sesame St.",
        "address2": "Suite 430",
        "city": "Austin",
        "state": "TX",
        "zip": "12345",
        "country": "US",
        "phone": "+1 123-123-1234",
        "email": "[email protected]",
        "fax": "123-867-5309"
      }
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

registrar-domains-get-domain

GET Get Domain

Show individual domain

GET accounts/:account_identifier/registrar/domains/:domain_name

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/registrar/domains/cloudflare.com" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "ea95132c15732412d22c1476fa83f27a",
    "available": false,
    "supported_tld": true,
    "can_register": false,
    "transfer_in": {
      "unlock_domain": "ok",
      "disable_privacy": "ok",
      "enter_auth_code": "needed",
      "approve_transfer": "unknown",
      "accept_foa": "needed",
      "can_cancel_transfer": true
    },
    "current_registrar": "Cloudflare",
    "expires_at": "2019-08-28T23:59:59Z",
    "registry_statuses": "ok,serverTransferProhibited",
    "locked": false,
    "created_at": "2018-08-28T17:26:26Z",
    "updated_at": "2018-08-28T17:26:26Z",
    "registrant_contact": {
      "id": "ea95132c15732412d22c1476fa83f27a",
      "first_name": "John",
      "last_name": "Appleseed",
      "organization": "Cloudflare, Inc.",
      "address": "123 Sesame St.",
      "address2": "Suite 430",
      "city": "Austin",
      "state": "TX",
      "zip": "12345",
      "country": "US",
      "phone": "+1 123-123-1234",
      "email": "[email protected]",
      "fax": "123-867-5309"
    }
  }
}

registrar-domains-update-domain

PUT Update Domain

Update individual domain

PUT accounts/:account_identifier/registrar/domains/:domain_name

Optional parameters

Name /type	Description /example	Constraints
name_servers array	List of name servers `[ "preston.ns.cloudflare.com", "oli.ns.cloudflare.com" ]` An array with items in the following form: Show definition »
privacy boolean	Privacy option controls redacting WHOIS information `true`	valid values: (true,false)
locked boolean	Whether a registrar lock in place for this domain `false`	valid values: (true,false)
auto_renew boolean	Auto-renew controls whether subscription is automatically renewed upon domain expiration `true`	valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/registrar/domains/cloudflare.com" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name_servers":["preston.ns.cloudflare.com","oli.ns.cloudflare.com"],"privacy":true,"locked":false,"auto_renew":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "ea95132c15732412d22c1476fa83f27a",
    "available": false,
    "supported_tld": true,
    "can_register": false,
    "transfer_in": {
      "unlock_domain": "ok",
      "disable_privacy": "ok",
      "enter_auth_code": "needed",
      "approve_transfer": "unknown",
      "accept_foa": "needed",
      "can_cancel_transfer": true
    },
    "current_registrar": "Cloudflare",
    "expires_at": "2019-08-28T23:59:59Z",
    "registry_statuses": "ok,serverTransferProhibited",
    "locked": false,
    "created_at": "2018-08-28T17:26:26Z",
    "updated_at": "2018-08-28T17:26:26Z",
    "registrant_contact": {
      "id": "ea95132c15732412d22c1476fa83f27a",
      "first_name": "John",
      "last_name": "Appleseed",
      "organization": "Cloudflare, Inc.",
      "address": "123 Sesame St.",
      "address2": "Suite 430",
      "city": "Austin",
      "state": "TX",
      "zip": "12345",
      "country": "US",
      "phone": "+1 123-123-1234",
      "email": "[email protected]",
      "fax": "123-867-5309"
    }
  }
}

registrar-domains-transfer-domain

POST Transfer Domain

Initiate domain transfer to Cloudflare Registrar

POST zones/:zone_identifier/registrar/domains/:domain_name/transfer

Optional parameters

Name /type	Description /example	Constraints
privacy boolean	Privacy option controls redacting WHOIS information `true`	valid values: (true,false)
auto_renew boolean	Auto-renew controls whether subscription is automatically renewed upon domain expiration `true`	valid values: (true,false)
years number	Number of years to extend current expiration date `1`	min value:1
registrant_contact_id string	Contact Identifier `"ea95132c15732412d22c1476fa83f27a"`	max length: 32 read only

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/registrar/domains/cloudflare.com/transfer" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"privacy":true,"auto_renew":true,"years":1,"registrant_contact_id":"ea95132c15732412d22c1476fa83f27a"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "ea95132c15732412d22c1476fa83f27a",
      "available": false,
      "supported_tld": true,
      "can_register": false,
      "transfer_in": {
        "unlock_domain": "ok",
        "disable_privacy": "ok",
        "enter_auth_code": "needed",
        "approve_transfer": "unknown",
        "accept_foa": "needed",
        "can_cancel_transfer": true
      },
      "current_registrar": "Cloudflare",
      "expires_at": "2019-08-28T23:59:59Z",
      "registry_statuses": "ok,serverTransferProhibited",
      "locked": false,
      "created_at": "2018-08-28T17:26:26Z",
      "updated_at": "2018-08-28T17:26:26Z",
      "registrant_contact": {
        "id": "ea95132c15732412d22c1476fa83f27a",
        "first_name": "John",
        "last_name": "Appleseed",
        "organization": "Cloudflare, Inc.",
        "address": "123 Sesame St.",
        "address2": "Suite 430",
        "city": "Austin",
        "state": "TX",
        "zip": "12345",
        "country": "US",
        "phone": "+1 123-123-1234",
        "email": "[email protected]",
        "fax": "123-867-5309"
      }
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

registrar-domains-cancel-transfer

POST Cancel transfer

Cancel previously intitiated transfer request

POST accounts/:account_identifier/registrar/domains/:domain_name/cancel_transfer

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/registrar/domains/cloudflare.com/cancel_transfer" \
     -H "X-Auth-Email: [email protected]" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "ea95132c15732412d22c1476fa83f27a",
      "available": false,
      "supported_tld": true,
      "can_register": false,
      "transfer_in": {
        "unlock_domain": "ok",
        "disable_privacy": "ok",
        "enter_auth_code": "needed",
        "approve_transfer": "unknown",
        "accept_foa": "needed",
        "can_cancel_transfer": true
      },
      "current_registrar": "Cloudflare",
      "expires_at": "2019-08-28T23:59:59Z",
      "registry_statuses": "ok,serverTransferProhibited",
      "locked": false,
      "created_at": "2018-08-28T17:26:26Z",
      "updated_at": "2018-08-28T17:26:26Z",
      "registrant_contact": {
        "id": "ea95132c15732412d22c1476fa83f27a",
        "first_name": "John",
        "last_name": "Appleseed",
        "organization": "Cloudflare, Inc.",
        "address": "123 Sesame St.",
        "address2": "Suite 430",
        "city": "Austin",
        "state": "TX",
        "zip": "12345",
        "country": "US",
        "phone": "+1 123-123-1234",
        "email": "[email protected]",
        "fax": "123-867-5309"
      }
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

Registrar Domains error codes

Code	Description
10000	Internal Server Error
10001	Authentication Failure

Cloudflare API documentation v4

Getting started

What is Cloudflare?

Audience for APIs

Do's and Don'ts

What can you build with Cloudflare APIs?

What should you avoid doing with Cloudflare APIs?

Endpoints

Requests

Required parameters

Example request

Auth-Email cURL (example)

User-Service cURL (example)

Pagination

cURL (example)

Responses

Format

Success Response (example)

Error Response (example)

HTTP Content-Type

HTTP response codes

How to get a Zone ID, User ID, or Organization ID

How to Get a Zone ID

GET User Details freeprobusinessenterprise

free

pro

business

enterprise

cURL (example)

Response (example)

PATCH Edit User freeprobusinessenterprise

free

pro

business

enterprise

Optional parameters

cURL (example)

Response (example)

GET List Memberships

Optional parameters

cURL (example)

Response (example)

GET Membership Details

cURL (example)

Response (example)

PUT Update Membership

Required parameters

cURL (example)

Response (example)

DELETE Delete Membership

cURL (example)

Response (example)

GET List Accounts permission needed: #organization:readfreeprobusinessenterprise

free

pro

business

enterprise

Optional parameters

cURL (example)

Response (example)

GET Account Details permission needed: #organization:readfreeprobusinessenterprise

free

pro

business

enterprise

cURL (example)

Response (example)

PUT Update Account permission needed: #organization:editfreeprobusinessenterprise

free

pro

business

enterprise

Optional parameters

cURL (example)

Response (example)

GET List Members permission needed: #organization:readfreeprobusinessenterprise

free

pro

business

enterprise

GET User Details
free
pro
business
enterprise

PATCH Edit User
free
pro
business
enterprise

GET List Accounts permission needed: #organization:read
free
pro
business
enterprise

GET Account Details permission needed: #organization:read
free
pro
business
enterprise

PUT Update Account permission needed: #organization:edit
free
pro
business
enterprise

GET List Members permission needed: #organization:read
free
pro
business
enterprise

POST Add Member permission needed: #organization:edit
free
pro
business
enterprise

GET Member Details permission needed: #organization:read
free
pro
business
enterprise

PUT Update Member permission needed: #organization:edit
free
pro
business
enterprise

DELETE Remove Member permission needed: #organization:edit
free
pro
business
enterprise

GET List Subscriptions permission needed: #billing:read
free
pro
business
enterprise

POST Create Subscription permission needed: #billing:read#billing:edit
free
pro
business
enterprise