Cloudflare API v4 Documentation

Name	Format	Description
API Token	Authorization: Bearer <token>	API Token generated from the User Profile 'API Tokens' page

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.

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

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)

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

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

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

Name /type	Description /example	Constraints
name string	Token name `"readonly token"`	max length: 120
policies array	List of access policies assigned to the token `[ { "id": "f267e341f3dd4697bd3b9f71dd96247f", "effect": "allow", "resources": { "com.cloudflare.api.account.zone.eb78d65290b24279ba6f44721b3ea3c4": "", "com.cloudflare.api.account.zone.22b1de5f1c0e4b3ea97bb1e963b06a43": "" }, "permission_groups": [ { "id": "c8fed203ed3043cba015a93ad1616f1f", "name": "Zone Read" }, { "id": "82e64a83756745bbbb1c9c2701bf816b", "name": "DNS Read" } ] } ]` An array with items in the following form: Show definition »

Name /type	Description /example	Constraints
not_before string (date-time)	The time before which the token MUST NOT be accepted for processing `"2018-07-01T05:20:00Z"`
expires_on string (date-time)	The expiration time on or after which the JWT MUST NOT be accepted for processing `"2020-01-01T00:00:00Z"`
condition object	Defines the extra limitation on how and/or where the token can be used `{ "request.ip": { "in": [ "199.27.128.0/21", "2400:cb00::/32" ], "not_in": [ "199.27.128.0/21", "2400:cb00::/32" ] } }` An object with the following properties: Show definition »

Name /type	Description /example	Constraints
expires_on string (date-time)	The expiration time on or after which the JWT MUST NOT be accepted for processing `"2020-01-01T00:00:00Z"`
not_before string (date-time)	The time before which the token MUST NOT be accepted for processing `"2018-07-01T05:20:00Z"`
name string	Token name `"readonly token"`	max length: 120
policies array	List of access policies assigned to the token `[ { "id": "f267e341f3dd4697bd3b9f71dd96247f", "effect": "allow", "resources": { "com.cloudflare.api.account.zone.eb78d65290b24279ba6f44721b3ea3c4": "", "com.cloudflare.api.account.zone.22b1de5f1c0e4b3ea97bb1e963b06a43": "" }, "permission_groups": [ { "id": "c8fed203ed3043cba015a93ad1616f1f", "name": "Zone Read" }, { "id": "82e64a83756745bbbb1c9c2701bf816b", "name": "DNS Read" } ] } ]` An array with items in the following form: Show definition »
status string	Status of the token `"active"`	valid values: active, disabled, expired
issued_on string (date-time)	The time on which the token was created `"2018-07-01T05:20:00Z"`	read only
modified_on string (date-time)	Last time the token was modified `"2018-07-02T05:20:00Z"`	read only
id string	Token identifier tag `"ed17574386854bf78a67040be0a770b0"`	max length: 32 read only
condition object	Defines the extra limitation on how and/or where the token can be used `{ "request.ip": { "in": [ "199.27.128.0/21", "2400:cb00::/32" ], "not_in": [ "199.27.128.0/21", "2400:cb00::/32" ] } }` An object with the following properties: Show definition »

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

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

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

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
name string	Name of the account `"example.com"`	read only

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, "use_account_custom_ns_by_default": false }` An object with the following properties: Show definition »
created_on string (date-time)	describes when account was created `"2014-03-01T12:21:02.0000Z"`	read only

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

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

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

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

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": "user@example.com", "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 »

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

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

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

Name /type	Description /example	Constraints
invited_member_email string	Email address of the user to be added to the Organization `"user@example.com"`	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 »

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)

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 »

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 »

Name /type	Description /example	Constraints
status	Status of your response to the invitation (rejected or accepted) `"accepted"`	valid values: accepted, rejected

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

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

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

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

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

Name /type	Description /example	Constraints
actor.ip string	Filters 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)	Filters by the email address of the actor that made the change. `"alice@example.com"`
hide_user_logs boolean	Indicates whether or not to hide user level audit logs. `false`	default value: false valid values: (true,false)
zone.name string	Filters by the name of the zone associated to the change. `"example.com"`
page number	Defines which page of results to return. `50`	default value: 1 min value:1
per_page number	Sets the number of results to return per page. `25`	default value: 100 min value:1 max value:1000
action.type string	Filters 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)	Limits 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	Finds a specific log by its ID. `"f174be97-19b1-40d6-954d-70cd5fbd52db"`
direction string	Changes the direction of the chronological sorting. `"desc"`	default value: desc valid values: desc, asc
before string (date-time)	Limits 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"`

Name /type	Description /example	Constraints
actor.ip string	Filters 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)	Filters by the email address of the actor that made the change. `"alice@example.com"`
hide_user_logs boolean	Indicates whether or not to hide user level audit logs. `false`	default value: false valid values: (true,false)
zone.name string	Filters by the name of the zone associated to the change. `"example.com"`
page number	Defines which page of results to return. `50`	default value: 1 min value:1
per_page number	Sets the number of results to return per page. `25`	default value: 100 min value:1 max value:1000
action.type string	Filters 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)	Limits 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	Finds a specific log by its ID. `"f174be97-19b1-40d6-954d-70cd5fbd52db"`
direction string	Changes the direction of the chronological sorting. `"desc"`	default value: desc valid values: desc, asc
before string (date-time)	Limits 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"`

Name /type	Description /example	Constraints
actor.ip string	Filters 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)	Filters by the email address of the actor that made the change. `"alice@example.com"`
hide_user_logs boolean	Indicates whether or not to hide user level audit logs. `false`	default value: false valid values: (true,false)
zone.name string	Filters by the name of the zone associated to the change. `"example.com"`
page number	Defines which page of results to return. `50`	default value: 1 min value:1
per_page number	Sets the number of results to return per page. `25`	default value: 100 min value:1 max value:1000
action.type string	Filters 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)	Limits 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	Finds a specific log by its ID. `"f174be97-19b1-40d6-954d-70cd5fbd52db"`
direction string	Changes the direction of the chronological sorting. `"desc"`	default value: desc valid values: desc, asc
before string (date-time)	Limits 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"`

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

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

Name /type	Description /example	Constraints
properties array	Requests information about certain properties. `[ "auth_id_characteristics" ]` An array with items in the following form: Show definition »	unique items

Name /type	Description /example	Constraints
auth_id_characteristics array	Characteristics define properties across which auth-ids can be computed in a privacy-preserving manner. `[ { "type": "header", "name": "authorization" } ]` An array with items in the following form: Show definition »	max items: 10 unique items

Name /type	Description /example	Constraints
feature array	Add feature(s) to the results. The feature name that is given here corresponds to the resulting feature object. Have a look at the top-level object description for more details on the specific meaning. `[ "thresholds" ]` An array with items in the following form: Show definition »	unique items

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
feature array	Add feature(s) to the results. The feature name that is given here corresponds to the resulting feature object. Have a look at the top-level object description for more details on the specific meaning. `[ "thresholds" ]` An array with items in the following form: Show definition »	unique items
order string	Field to order by. When requesting a feature, the feature keys are available for ordering as well, e.g., thresholds.suggested_threshold `"method"`	valid values: method, host, endpoint, thresholds.$key
direction string	Direction to order results `"desc"`	valid values: asc, desc
host array	Filter results to only include the specified hosts. `[ "api.cloudflare.com" ]` An array with items in the following form: Show definition »	unique items
method array	Filter results to only include the specified HTTP methods. `[ "GET" ]` An array with items in the following form: Show definition »	unique items
endpoint string	Filter results to only include endpoints containing this pattern. `"/api/v1"`

Name /type	Description /example	Constraints
host string (hostname)	RFC3986-compliant host. `"www.example.com"`	max length: 255
method string	The HTTP method used to access the endpoint. `"GET"`	valid values: GET, POST, HEAD, OPTIONS, PUT, DELETE, CONNECT, PATCH, TRACE
endpoint string (uri-template)	The endpoint which can contain path parameter templates in curly braces, each will be replaced from left to right with {varN}, starting with {var1}, during insertion. This will further be Cloudflare-normalized upon insertion. See: https://developers.cloudflare.com/rules/normalization/how-it-works/ `"/api/v1/users/{var1}"`	max length: 4096 pattern: ^/.*$

Name /type	Description /example	Constraints
feature array	Add feature(s) to the results. The feature name that is given here corresponds to the resulting feature object. Have a look at the top-level object description for more details on the specific meaning. `[ "thresholds" ]` An array with items in the following form: Show definition »	unique items
host array	Receive schema only for the given host(s). `[ "www.example.com" ]` An array with items in the following form: Show definition »	unique items

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: user@example.com" \
     -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-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	Account of which the zone is created in `{ "id": "01a7362d577a6c3019a474fd6f485823" }` An object with the following properties: Show definition »

Optional parameters

Name /type	Description /example	Constraints
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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"example.com","account":{"id":"01a7362d577a6c3019a474fd6f485823"},"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: user@example.com" \
     -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 »
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. This parameter is only available to Enterprise customers or if it has been explicitly enabled on a zone. `"full"`	valid values: full, partial

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353" \
     -H "X-Auth-Email: user@example.com" \
     -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"},"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-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: user@example.com" \
     -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: user@example.com" \
     -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: #cache_purge: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: user@example.com" \
     -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: #cache_purge: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, however, FREE can only purge 1000 URLs per minute.

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.

NB: When including the Origin header, be sure to include the scheme and hostname. The port number can be omitted if it is the default port (80 for http, 443 for https), but must be included otherwise.

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": "https://www.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: user@example.com" \
     -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":"https://www.cloudflare.com","CF-IPCountry":"US","CF-Device-Type":"desktop"}}]}'

Response (example)

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

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

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

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

NB: Cache-Tag, host and prefix purging each have a rate limit of 30,000 purge API calls in every 24 hour period. You may purge up to 30 tags, hosts, or prefixes 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
prefixes array	Any assets at URLs that match the prefix will be purged from the Cloudflare cache. For instance, a.com/b will purge a.com/b/c/d.png but not a.com/bc.png. The prefixes a.com/b and a.com/b/c are redundant. `[ "www.example.com/foo", "images.example.com/bar/baz" ]` 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"tags":["some-tag","another-tag"],"hosts":["www.example.com","images.example.com"],"prefixes":["www.example.com/foo","images.example.com/bar/baz"]}'

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', 'hosts' or 'prefixes'
1013	'purge_everything' must be true
1014	'files', 'tags', 'hosts' or 'prefixes' 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>', which is an invalid 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', 'hosts' or 'prefixes'
1094	Exceeded maximum amount of files that can be purged on a single request for your plan type.
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 web property cannot be added to Cloudflare at this time. If you are an Enterprise customer, please contact your Customer Success Manager. Otherwise, please email abusereply@cloudflare.com with the name of the web property and a detailed explanation of your association with this web property.
1098	This web property is temporarily restricted from being added to Cloudflare at this time. Please try again later, or contact Cloudflare Support with any questions.
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 web property is temporarily restricted from being added to Cloudflare at this time. Please try again later, or contact Cloudflare Support with any questions.
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
1116	No prefixes were provided in the request. Must provide at least 1 prefixes.
1117	Exceeded maximum amount of 30 prefixes that can be purged on a single request.
1118	Empty prefix provided. Prefixes must not be empty.
1119	URI scheme provided in prefix '<prefix>'. URI schemes must not be provided.
1120	URI host was not provided in prefix '<prefix>'. Host must be provided in each prefix.
1121	URI host in prefix '<prefix>' exceeds maximum length of 200 characters.
1122	URI host in prefix '<prefix>' has a segment exceeding maximum length of 63 characters.
1123	URI Query string was provided in prefix '<prefix>'. Query strings must not be provided.
1124	URI fragment was provided in prefix '<prefix>'. Fragments must not be provided.
1125	URI host in prefix '<prefix>' is not a domain. Host must be a valid domain or IPV4 address.
1126	URI host in prefix '<prefix>' contains an invalid top level domain.
1127	Invalid prefix '<prefix>'. Invalid Url.
1128	Prefix '<prefix>' overlaps with another prefix. Prefixes must not be redundant.
1129	Could not purge prefix '<prefix>'. Internal error.
1130	Only enterprise zones can purge by prefix.
1131	Unable to purge by prefix, rate limit reached. Please wait if you need to perform more operations
1132	Unable to purge '<url>'. Resized images cannot be purged. Purge the original image instead.
1133	Path too deep in '<prefix>', maximum path depth is 31.
1134	Unable to purge '<url>'. URL headers must not contain reserved cf header: '<header name>'.
1135	Unable to purge: '<url>'. URL contains a newline.
1136	Unable to purge: '<url>'. URL has invalid scheme "<scheme>".
1137	Unable to purge: '<url>'. URL host is too long.
1138	Unable to purge: '<url>'. URL host has a zero-length label.
1139	Unable to purge: '<url>'. Host has a label exceeding '<max host label length>' characters.
1140	Unable to purge: '<url>'. Host contains invalid top level domain: '<top level domain>'.
1141	Unable to purge: '<url>'. Host is an invalid domain.
1142	Unable to purge '<url>', cdn-cgi endpoints cannot be purged.

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

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: user@example.com" \
     -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, Cloudflare serves limited copies of web pages available from the Internet Archive's Wayback Machine if your server is offline. Refer to Always Online for more information.

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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

zone-settings-get-orange-to-orange-o2o-

GET Get Orange to Orange (O2O) permission needed: #zone_settings:read
free
pro
business
enterprise

Orange to Orange (O2O) allows zones on Cloudflare to CNAME to other zones also on Cloudflare.

GET zones/:zone_identifier/settings/orange_to_orange

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/orange_to_orange" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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-early-hints-setting

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

When enabled, Cloudflare will attempt to speed up overall page loads by serving 103 responses with Link headers from the final response. Refer to Early Hints for more information.

GET zones/:zone_identifier/settings/early_hints

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/early_hints" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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. Refer to Using Cloudflare Auto Minify for more information.

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: user@example.com" \
     -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. Refer to Understanding Cloudflare Mobile Redirect for more information.

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: user@example.com" \
     -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. Refer to our blog post for more information.

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: user@example.com" \
     -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: user@example.com" \
     -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

Gets Opportunistic Encryption setting.

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: user@example.com" \
     -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

Removes 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: user@example.com" \
     -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, and WebP offers a performance advantage over the original image format, Cloudflare will serve a WebP version of the original image.

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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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 that prioritises rendering 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). This 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. Refer to Understanding Rocket Loader for more information.

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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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-ssl/tls-recommender-enrollment

GET Get SSL/TLS Recommender enrollment permission needed: #zone_settings:read
free
pro
business
enterprise

Enrollment in the SSL/TLS Recommender service which tries to detect and recommend (by sending periodic emails) the most secure SSL/TLS setting your origin servers support.

GET zones/:zone_identifier/settings/ssl_recommender

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/ssl_recommender" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "ssl_recommender",
    "enabled": false,
    "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

Gets Minimum TLS Version setting.

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

zone-settings-get-ciphers-setting

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

Gets ciphers setting.

GET zones/:zone_identifier/settings/ciphers

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/ciphers" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

zone-settings-get-tls-1.3-setting-enabled-for-a-zone

GET Get TLS 1.3 setting enabled for a zone permission needed: #zone_settings:edit
free
pro
business
enterprise

Gets TLS 1.3 setting enabled for a 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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

zone-settings-get-proxy-read-timeout-setting

GET Get Proxy Read Timeout setting permission needed: #zone_settings:read
free
pro
business
enterprise

Maximum time between two read operations from origin

GET zones/:zone_identifier/settings/proxy_read_timeout

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/proxy_read_timeout" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

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: user@example.com" \
     -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: user@example.com" \
     -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-http3-setting

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

Value of the HTTP3 setting.

GET zones/:zone_identifier/settings/http3

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/http3" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

zone-settings-get-origin-max-http-version-setting

GET Get Origin Max HTTP version setting permission needed: #zone_settings:read
free
pro
business
enterprise

Value of the Origin Max HTTP version setting (Note that the default value for Enterprise is "1")

GET zones/:zone_identifier/origin_max_http_version

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/origin_max_http_version" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

zone-settings-get-0-rtt-session-resumption-setting

GET Get 0-RTT session resumption setting permission needed: #zone_settings:read
free
pro
business
enterprise

Gets 0-RTT session resumption setting.

GET zones/:zone_identifier/settings/0rtt

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/0rtt" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "0rtt",
    "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: user@example.com" \
     -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

Gets Websockets setting. For more information about Websockets, please refer to Using 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: user@example.com" \
     -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: user@example.com" \
     -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

Gets HTTP/2 Edge Prioritization setting.

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: user@example.com" \
     -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-get-automatic-platform-optimization-for-wordpress-settings

GET Get Automatic Platform Optimization for WordPress settings permission needed: #zone_settings:read
free
pro
business
enterprise

Automatic Platform Optimization for WordPress serves your WordPress site from Cloudflare's edge network and caches third-party fonts.

GET zones/:zone_identifier/settings/automatic_platform_optimization

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/automatic_platform_optimization" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "automatic_platform_optimization",
    "value": {
      "enabled": true,
      "cf": true,
      "wordpress": true,
      "wp_plugin": true,
      "hostnames": [
        "www.example.com",
        "example.com",
        "shop.example.com"
      ],
      "cache_by_device_type": false
    },
    "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: user@example.com" \
     -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": []
}

zone-settings-change-always-online-setting

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

When enabled, Cloudflare serves limited copies of web pages available from the Internet Archive's Wayback Machine if your server is offline. Refer to Always Online for more information.

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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

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

zone-settings-change-orange-to-orange-o2o-

PATCH Change Orange to Orange (O2O) permission needed: #zone_settings:edit
free
pro
business
enterprise

Orange to Orange (O2O) allows zones on Cloudflare to CNAME to other zones also on Cloudflare.

PATCH zones/:zone_identifier/settings/orange_to_orange

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/orange_to_orange" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"on"}'

Response (example)

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

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: user@example.com" \
     -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: 0, 30, 60, 120, 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: Setting a TTL of 0 is equivalent to selecting `Respect Existing Headers`

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/browser_cache_ttl" \
     -H "X-Auth-Email: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":1800}'

Response (example)

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

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

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

zone-settings-change-early-hints-setting

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

When enabled, Cloudflare will attempt to speed up overall page loads by serving 103 responses with Link headers from the final response. Refer to Early Hints for more information.

PATCH zones/:zone_identifier/settings/early_hints

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/early_hints" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

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

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"on"}'

Response (example)

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

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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"on"}'

Response (example)

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

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

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

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. Refer to Using Cloudflare Auto Minify for more information.

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":{"css":"off","html":"off","js":"off"}}'

Response (example)

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

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. Refer to Understanding Cloudflare Mobile Redirect for more information.

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":{"status":"off","mobile_subdomain":"m","strip_uri":false}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "mobile_redirect",
    "value": {
      "status": "off",
      "mobile_subdomain": "m",
      "strip_uri": false
    },
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

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. Refer to our blog post for more information.

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

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

zone-settings-change-opportunistic-encryption-setting

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

Changes Opportunistic Encryption setting.

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: user@example.com" \
     -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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

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

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, and WebP offers a performance advantage over the original image format, Cloudflare will serve a WebP version of the original image.

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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

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

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":{"strict_transport_security":{"enabled":true,"max_age":86400,"include_subdomains":true,"nosniff":true}}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "security_header",
    "value": {
      "strict_transport_security": {
        "enabled": true,
        "max_age": 86400,
        "include_subdomains": true,
        "nosniff": true
      }
    },
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"medium"}'

Response (example)

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

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"on"}'

Response (example)

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

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

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

zone-settings-change-ssl/tls-recommender-enrollment

PATCH Change SSL/TLS Recommender enrollment permission needed: #zone_settings:edit
free
pro
business
enterprise

Enrollment in the SSL/TLS Recommender service which tries to detect and recommend (by sending periodic emails) the most secure SSL/TLS setting your origin servers support.

PATCH zones/:zone_identifier/settings/ssl_recommender

Required parameters

Name /type	Description /example	Constraints
enabled boolean	ssl-recommender enrollment setting `false`	default value: false valid values: (true,false)

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/ssl_recommender" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"enabled":false}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "ssl_recommender",
    "enabled": false,
    "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: user@example.com" \
     -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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

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

zone-settings-change-proxy-read-timeout-setting

PATCH Change Proxy Read Timeout setting permission needed: #zone_settings:edit
free
pro
business
enterprise

Maximum time between two read operations from origin

PATCH zones/:zone_identifier/settings/proxy_read_timeout

Required parameters

Name /type	Description /example	Constraints
value number	Value of the zone setting `100`	default value: 100 notes: Value must be between 1 and 6000

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/proxy_read_timeout" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":100}'

Response (example)

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

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

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

Changes Minimum TLS Version setting.

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: user@example.com" \
     -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-ciphers-setting

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

Changes ciphers setting.

PATCH zones/:zone_identifier/settings/ciphers

Required parameters

Name /type	Description /example	Constraints
value array	Value of the zone setting. `[ "ECDHE-RSA-AES128-GCM-SHA256", "AES128-SHA" ]` An array with items in the following form: Show definition »	default value: List [] unique items

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/ciphers" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":["ECDHE-RSA-AES128-GCM-SHA256","AES128-SHA"]}'

Response (example)

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

zone-settings-change-tls-1.3-setting

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

Changes TLS 1.3 setting.

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: user@example.com" \
     -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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

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

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: user@example.com" \
     -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-http3-setting

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

Value of the HTTP3 setting.

PATCH zones/:zone_identifier/settings/http3

Required parameters

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

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/http3" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

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

zone-settings-change-origin-max-http-version-setting

PATCH Change Origin Max HTTP version setting permission needed: #zone_settings:edit
free
pro
business
enterprise

The highest HTTP version Cloudflare will attempt to use with your origin. This setting allows Cloudflare to make HTTP/2 requests to your origin. (Refer to Enable HTTP/2 to Origin, for more information.)

PATCH zones/:zone_identifier/origin_max_http_version

Required parameters

Name /type	Description /example	Constraints
value string	Value of the Origin Max HTTP version setting (Note that the default value for Enterprise is "1") `"2"`	default value: 2 valid values: 1, 2

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/origin_max_http_version" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"2"}'

Response (example)

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

zone-settings-change-0-rtt-session-resumption-setting

PATCH Change 0-RTT session resumption setting permission needed: #zone_settings:edit
free
pro
business
enterprise

Changes the 0-RTT session resumption setting.

PATCH zones/:zone_identifier/settings/0rtt

Required parameters

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

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/0rtt" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "0rtt",
    "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: user@example.com" \
     -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

Changes Websockets setting. For more information about Websockets, please refer to Using Cloudflare with WebSockets.

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: user@example.com" \
     -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	Whether the feature is enabled, disabled, or enabled in 'open proxy' mode `"off"`	default value: off valid values: on, off, open

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/image_resizing" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":"off"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "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

Changes HTTP/2 Edge Prioritization setting.

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: user@example.com" \
     -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-settings-change-automatic-platform-optimization-for-wordpress-settings

PATCH Change Automatic Platform Optimization for WordPress settings permission needed: #zone_settings:edit
free
pro
business
enterprise

Automatic Platform Optimization for WordPress serves your WordPress site from Cloudflare's edge network and caches third-party fonts.

PATCH zones/:zone_identifier/settings/automatic_platform_optimization

Required parameters

Name /type	Description /example	Constraints
value object	Automatic Platform Optimization for WordPress serves your WordPress site from Cloudflare's edge network and caches third-party fonts. `{ "enabled": true, "cf": true, "wordpress": true, "wp_plugin": true, "hostnames": [ "www.example.com", "example.com", "shop.example.com" ], "cache_by_device_type": false }` An object with the following properties: Show definition »

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/settings/automatic_platform_optimization" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":{"enabled":true,"cf":true,"wordpress":true,"wp_plugin":true,"hostnames":["www.example.com","example.com","shop.example.com"],"cache_by_device_type":false}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "automatic_platform_optimization",
    "value": {
      "enabled": true,
      "cf": true,
      "wordpress": true,
      "wp_plugin": true,
      "hostnames": [
        "www.example.com",
        "example.com",
        "shop.example.com"
      ],
      "cache_by_device_type": false
    },
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

Zone Cache Settings

Zone level settings controlling how the Zone works in relation to the caching features of Cloudflare.

zone-cache-settings

Object definitions

View properties and constraints defined on the object

Show definitions

zone-cache-settings-get-variants-setting

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

Variant support enables caching variants of images with certain file extensions in addition to the original. This only applies when the origin server sends the 'Vary: Accept' response header. If the origin server sends 'Vary: Accept' but does not serve the variant requested, the response will not be cached. This will be indicated with BYPASS cache status in the response headers.

GET zones/:zone_identifier/cache/variants

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/cache/variants" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "variants",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "value": {
      "avif": [
        "image/webp",
        "image/jpeg"
      ],
      "bmp": [
        "image/webp",
        "image/jpeg"
      ],
      "gif": [
        "image/webp",
        "image/jpeg"
      ],
      "jpeg": [
        "image/webp",
        "image/avif"
      ],
      "jpg": [
        "image/webp",
        "image/avif"
      ],
      "jpg2": [
        "image/webp",
        "image/avif"
      ],
      "jp2": [
        "image/webp",
        "image/avif"
      ],
      "png": [
        "image/webp",
        "image/avif"
      ],
      "tiff": [
        "image/webp",
        "image/avif"
      ],
      "tif": [
        "image/webp",
        "image/avif"
      ],
      "webp": [
        "image/jpeg",
        "image/avif"
      ]
    }
  }
}

zone-cache-settings-change-variants-setting

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

PATCH zones/:zone_identifier/cache/variants

Required parameters

Name /type	Description /example	Constraints
value object	Value of the zone setting `{ "avif": [ "image/webp", "image/jpeg" ], "bmp": [ "image/webp", "image/jpeg" ], "gif": [ "image/webp", "image/jpeg" ], "jpeg": [ "image/webp", "image/avif" ], "jpg": [ "image/webp", "image/avif" ], "jpg2": [ "image/webp", "image/avif" ], "jp2": [ "image/webp", "image/avif" ], "png": [ "image/webp", "image/avif" ], "tiff": [ "image/webp", "image/avif" ], "tif": [ "image/webp", "image/avif" ], "webp": [ "image/jpeg", "image/avif" ] }` An object with the following properties: Show definition »

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/cache/variants" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"value":{"avif":["image/webp","image/jpeg"],"bmp":["image/webp","image/jpeg"],"gif":["image/webp","image/jpeg"],"jpeg":["image/webp","image/avif"],"jpg":["image/webp","image/avif"],"jpg2":["image/webp","image/avif"],"jp2":["image/webp","image/avif"],"png":["image/webp","image/avif"],"tiff":["image/webp","image/avif"],"tif":["image/webp","image/avif"],"webp":["image/jpeg","image/avif"]}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "variants",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "value": {
      "avif": [
        "image/webp",
        "image/jpeg"
      ],
      "bmp": [
        "image/webp",
        "image/jpeg"
      ],
      "gif": [
        "image/webp",
        "image/jpeg"
      ],
      "jpeg": [
        "image/webp",
        "image/avif"
      ],
      "jpg": [
        "image/webp",
        "image/avif"
      ],
      "jpg2": [
        "image/webp",
        "image/avif"
      ],
      "jp2": [
        "image/webp",
        "image/avif"
      ],
      "png": [
        "image/webp",
        "image/avif"
      ],
      "tiff": [
        "image/webp",
        "image/avif"
      ],
      "tif": [
        "image/webp",
        "image/avif"
      ],
      "webp": [
        "image/jpeg",
        "image/avif"
      ]
    }
  }
}

zone-cache-settings-delete-variants-setting

DELETE Delete variants setting permission needed: #zone_settings:edit
free
pro
business
enterprise

DELETE zones/:zone_identifier/cache/variants

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/cache/variants" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Zone Cache Settings error codes

Code	Description
1134	Unable to parse zone setting value.
1135	Sorry, this zone setting is not available for your plan type.
1136	Sorry, you do not have access to this zone setting for that zone id or that zone id is invalid.
1137	Unable to process request. Internal error.
1138	Unable to retrieve <zone_cache_setting_id> setting value. Internal error.
1140	Unable to update <zone_cache_setting_id> setting value. Internal error.
1141	Unable to delete <zone_cache_setting_id> setting. Internal error.
1142	Unable to retrieve <zone_cache_setting_id> setting value. The zone setting does not exist.
1144	Unable to delete <zone_cache_setting_id> setting. The zone setting does not exist.
1146	The value provided for <zone_cache_setting_id> setting is not valid.

Zone Analytics

Analytics data for a zone

zone-analytics

Object definitions

View properties and constraints defined on the object

Show definitions

Deprecation Warning

End of life Date: March 1, 2021

Please use the new GraphQL Analytics API instead: https://developers.cloudflare.com/analytics/graphql-api/. It provides equivalent data and more features, including the ability to select only the metrics you need. Migration guide: https://developers.cloudflare.com/analytics/migration-guides/zone-analytics/.

zone-analytics-get-dashboard

GET 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "totals": {
      "since": "2015-01-01T12:23:00Z",
      "until": "2015-01-02T12:23:00Z",
      "requests": {
        "all": 1234085328,
        "cached": 1234085328,
        "uncached": 13876154,
        "content_type": {
          "css": 15343,
          "html": 1234213,
          "javascript": 318236,
          "gif": 23178,
          "jpeg": 1982048
        },
        "country": {
          "US": 4181364,
          "AG": 37298,
          "GI": 293846
        },
        "ssl": {
          "encrypted": 12978361,
          "unencrypted": 781263
        },
        "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
  }
}

Deprecation Warning

End of life Date: March 1, 2021

zone-analytics-get-analytics-by-co-locations

GET 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "colo_id": "SFO",
      "timeseries": [
        {
          "since": "2015-01-01T12:23:00Z",
          "until": "2015-01-02T12:23:00Z",
          "requests": {
            "all": 1234085328,
            "cached": 1234085328,
            "uncached": 13876154,
            "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-get-log-retention-flag

GET Get log retention flag permission needed: #logs:edit
free
pro
business
enterprise

Gets log retention flag for Logpull API.

GET zones/:zone_identifier/logs/control/retention/flag

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/logs/control/retention/flag" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

logs-received-update-log-retention-flag

POST Update log retention flag permission needed: #logs:edit
free
pro
business
enterprise

Updates log retention flag for Logpull API.

POST zones/:zone_identifier/logs/control/retention/flag

Required parameters

Name /type	Description /example	Constraints
flag boolean	The log retention flag for Logpull API. `true`	valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/logs/control/retention/flag" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"flag":true}'

Response (example)

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

logs-received-get-logs-received

GET 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	Sets 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 seven days. `"2018-05-20T10:00:00Z"`
end stringinteger	Sets 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 five minutes earlier than now and must be later than `start`. Difference between `start` and `end` must be not greater than one hour. `"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 five will be returned. When there are 1000 records, seven will be returned. When there are 10,000 records, seven 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 does not 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 that `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: user@example.com" \
     -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-get-logs-rayids

GET 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 zero, one, 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 does not 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 that `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: user@example.com" \
     -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-list-fields

GET List fields permission needed: #logs:read
free
pro
business
enterprise

Lists 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: user@example.com" \
     -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, the appropriate status code will be set and an 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

Lists 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": 1,
      "enabled": false,
      "name": "example.com",
      "dataset": "http_requests",
      "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,
      "frequency": "high"
    }
  ]
}

logpush-jobs-list-logpush-jobs-for-a-dataset

GET List Logpush jobs for a dataset permission needed: #logs:edit
free
pro
business
enterprise

Lists Logpush jobs for a zone for a dataset.

GET zones/:zone_identifier/logpush/datasets/:dataset/jobs

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/logpush/datasets/http_requests/jobs" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": 1,
      "enabled": false,
      "name": "example.com",
      "dataset": "http_requests",
      "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,
      "frequency": "high"
    }
  ]
}

logpush-jobs-list-fields

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

Lists all fields available for a dataset. The response result is an object with key-value pairs, where keys are field names, and values are descriptions.

GET zones/:zone_identifier/logpush/datasets/:dataset/fields

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/logpush/datasets/http_requests/fields" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

logpush-jobs-get-ownership-challenge

POST Get ownership challenge permission needed: #logs:edit
free
pro
business
enterprise

Gets 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: user@example.com" \
     -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

Validates 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: user@example.com" \
     -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

Validates 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. It specifies things like requested fields and timestamp formats. If migrating from the logpull api, copy the url (full url or just the query string) of your call 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: user@example.com" \
     -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

Creates 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

Optional parameters

Name /type	Description /example	Constraints
name stringnull	Optional human readable job name. Not unique. Cloudflare suggests that you set this to a meaningful string, like the domain name, to make it easier to identify your job. `"example.com"`	max length: 512 pattern: ^[a-zA-Z0-9\-\.]*$
enabled boolean	Flag that indicates if the job was enabled. `false`	valid values: (true,false)
dataset stringnull	Dataset to be pulled. `"http_requests"`	max length: 256 pattern: ^[a-zA-Z0-9_\-]*$
logpull_options stringnull (uri)	Configuration string. It specifies things like requested fields and timestamp formats. If migrating from the logpull api, copy the url (full url or just the query string) of your call 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
ownership_challenge string	Ownership challenge token to prove destination ownership. `"00000000000000000000"`	max length: 4096 pattern: ^[a-zA-Z0-9/\+\.\-_]*$
frequency stringnull	The frequency at which Cloudflare sends batches of logs to your destination. Setting frequency to high sends your logs in larger quantities of smaller files. Setting frequency to low sends logs in smaller quantities of larger files. `"high"`	default value: high valid values: high, low

cURL (example)

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

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": 1,
    "enabled": false,
    "name": "example.com",
    "dataset": "http_requests",
    "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,
    "frequency": "high"
  }
}

logpush-jobs-get-logpush-job-details

GET Get Logpush job details permission needed: #logs:edit
free
pro
business
enterprise

Gets 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": 1,
    "enabled": false,
    "name": "example.com",
    "dataset": "http_requests",
    "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,
    "frequency": "high"
  }
}

logpush-jobs-update-logpush-job

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

Updates a Logpush job.

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

Optional parameters

Name /type	Description /example	Constraints
enabled boolean	Flag that indicates if the job was enabled. `false`	valid values: (true,false)
logpull_options stringnull (uri)	Configuration string. It specifies things like requested fields and timestamp formats. If migrating from the logpull api, copy the url (full url or just the query string) of your call 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/\+\.\-_]*$
frequency stringnull	The frequency at which Cloudflare sends batches of logs to your destination. Setting frequency to high sends your logs in larger quantities of smaller files. Setting frequency to low sends logs in smaller quantities of larger files. `"high"`	default value: high valid values: high, low

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/logpush/jobs/1" \
     -H "X-Auth-Email: user@example.com" \
     -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","frequency":"high"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": 1,
    "enabled": false,
    "name": "example.com",
    "dataset": "http_requests",
    "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,
    "frequency": "high"
  }
}

logpush-jobs-delete-logpush-job

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

Deletes 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: user@example.com" \
     -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

Checks 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: user@example.com" \
     -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
  }
}

Logpush Jobs error codes

Code	Description
1000	Not Found
1001	Internal Server Error
1002	Bad Request
1003	Request Entity Too Large
1004	Forbidden

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
match string	Whether to match all search requirements or at least one (any) `"all"`	default value: all valid values: any, all
name string	DNS record name (or @ for the zone apex) `"example.com"`	max length: 255
order string	Field to order records by `"type"`	valid values: type, name, content, ttl, proxied
page number	Page number of paginated results `1`	default value: 1 min value:1
per_page number	Number of DNS records per page `100`	default value: 100 min value:5 max value:5000
content string	DNS record content `"127.0.0.1"`
type string	DNS record type `"A"`	valid values: A, AAAA, CNAME, HTTPS, TXT, SRV, LOC, MX, NS, CERT, DNSKEY, DS, NAPTR, SMIMEA, SSHFP, SVCB, TLSA, URI read only
proxied boolean	DNS record proxied status `false`	valid values: (true,false)
direction string	Direction to order domains `"desc"`	valid values: asc, desc

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&proxied=false&page=1&per_page=100&order=type&direction=desc&match=all" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "372e67954025e0ba6aaa6d586b9e0b59",
      "type": "A",
      "name": "example.com",
      "content": "198.51.100.4",
      "proxiable": true,
      "proxied": false,
      "ttl": 3600,
      "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": {},
      "meta": {
        "auto_added": true,
        "source": "primary"
      }
    }
  ]
}

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, HTTPS, TXT, SRV, LOC, MX, NS, CERT, DNSKEY, DS, NAPTR, SMIMEA, SSHFP, SVCB, TLSA, URI read only
name string	DNS record name (or @ for the zone apex) `"example.com"`	max length: 255
content string	DNS record content `"127.0.0.1"`
ttl number	Time to live, in seconds, of the DNS record. Must be between 60 and 86400, or 1 for 'automatic' `3600` Any of the following: Show definition » Show definition »

Optional parameters

Name /type	Description /example	Constraints
priority number	Required for MX, SRV and URI records; unused by other record types. Records with lower priorities are preferred `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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"A","name":"example.com","content":"127.0.0.1","ttl":3600,"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": 3600,
    "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": {},
    "meta": {
      "auto_added": true,
      "source": "primary"
    }
  }
}

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: user@example.com" \
     -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": 3600,
    "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": {},
    "meta": {
      "auto_added": true,
      "source": "primary"
    }
  }
}

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, HTTPS, TXT, SRV, LOC, MX, NS, CERT, DNSKEY, DS, NAPTR, SMIMEA, SSHFP, SVCB, TLSA, URI read only
name string	DNS record name (or @ for the zone apex) `"example.com"`	max length: 255
content string	DNS record content `"127.0.0.1"`
ttl number	Time to live, in seconds, of the DNS record. Must be between 60 and 86400, or 1 for 'automatic' `3600` Any of the following: Show definition » Show definition »

Optional parameters

Name /type	Description /example	Constraints
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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"A","name":"example.com","content":"127.0.0.1","ttl":3600,"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": 3600,
    "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": {},
    "meta": {
      "auto_added": true,
      "source": "primary"
    }
  }
}

dns-records-for-a-zone-patch-dns-record

PATCH Patch DNS Record permission needed: #dns_records:edit
free
pro
business
enterprise

PATCH zones/:zone_identifier/dns_records/:identifier

Optional parameters

Name /type	Description /example	Constraints
type string	DNS record type `"A"`	valid values: A, AAAA, CNAME, HTTPS, TXT, SRV, LOC, MX, NS, CERT, DNSKEY, DS, NAPTR, SMIMEA, SSHFP, SVCB, TLSA, URI read only
name string	DNS record name (or @ for the zone apex) `"example.com"`	max length: 255
content string	DNS record content `"127.0.0.1"`
ttl number	Time to live, in seconds, of the DNS record. Must be between 60 and 86400, or 1 for 'automatic' `3600` Any 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 PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/dns_records/372e67954025e0ba6aaa6d586b9e0b59" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"A","name":"example.com","content":"127.0.0.1","ttl":3600,"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": 3600,
    "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": {},
    "meta": {
      "auto_added": true,
      "source": "primary"
    }
  }
}

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

dns-records-for-a-zone-scan-dns-records

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

Scan for common DNS records on your domain and automatically add them to your zone. Useful if you haven't updated your nameservers yet.

POST zones/:zone_identifier/dns_records/scan

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/dns_records/scan" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

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-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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     --form 'file=@bind_config.txt' \
     --form '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: user@example.com" \
     -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
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 60 and 86400 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 to filter on. For example: queryName
operator — defines the type of filter match to use. Operators are specific to dimensions.
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	`dimension>1000`	Return results where a dimension is higher than `1000`	`%3E`
`<`	Less than	`dimension<1000`	Return results where a dimension is lower than `1000`	`%3C`
`>=`	Greater than or equal to	`dimension>=1000`	Return results where a dimension is higher than or equal to `1000`	`%3E%3D`
`<=`	Less than or equal to	`dimension<=1000`	Return results where a dimension 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. Note that the semicolon is a reserved character in URLs (rfc1738) and needs to be percent-encoded as %3B.

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 permission needed: #analytics:read

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: user@example.com" \
     -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 permission needed: #analytics:read

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: user@example.com" \
     -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
  }
}

DNSSEC

Manage DNSSEC for a zone

dnssec

Object definition

View properties and constraints defined on the object

Show definition

dnssec-dnssec-details

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

Details about DNSSEC status and configuration

GET zones/:zone_identifier/dnssec

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/dnssec" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "status": "active",
    "flags": 257,
    "algorithm": "13",
    "key_type": "ECDSAP256SHA256",
    "digest_type": "2",
    "digest_algorithm": "SHA256",
    "digest": "48E939042E82C22542CB377B580DFDC52A361CEFDC72E7F9107E2B6BD9306A45",
    "ds": "example.com. 3600 IN DS 16953 13 2 48E939042E82C22542CB377B580DFDC52A361CEFDC72E7F9107E2B6BD9306A45",
    "key_tag": 42,
    "public_key": "oXiGYrSTO+LSCJ3mohc8EP+CzF9KxBj8/ydXJ22pKuZP3VAC3/Md/k7xZfz470CoRyZJ6gV6vml07IC3d8xqhA==",
    "modified_on": "2014-01-01T05:20:00Z"
  }
}

dnssec-edit-dnssec-status

PATCH Edit DNSSEC Status permission needed: #zone_settings:edit
free
pro
business
enterprise

Enable or disable DNSSEC

PATCH zones/:zone_identifier/dnssec

Required parameters

Name /type	Description /example	Constraints
status	Status of DNSSEC, based on user-desired state and presence of necessary records `"active"`	valid values: active, disabled

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/dnssec" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"status":"active"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "status": "active",
    "flags": 257,
    "algorithm": "13",
    "key_type": "ECDSAP256SHA256",
    "digest_type": "2",
    "digest_algorithm": "SHA256",
    "digest": "48E939042E82C22542CB377B580DFDC52A361CEFDC72E7F9107E2B6BD9306A45",
    "ds": "example.com. 3600 IN DS 16953 13 2 48E939042E82C22542CB377B580DFDC52A361CEFDC72E7F9107E2B6BD9306A45",
    "key_tag": 42,
    "public_key": "oXiGYrSTO+LSCJ3mohc8EP+CzF9KxBj8/ydXJ22pKuZP3VAC3/Md/k7xZfz470CoRyZJ6gV6vml07IC3d8xqhA==",
    "modified_on": "2014-01-01T05:20:00Z"
  }
}

dnssec-delete-dnssec-records

DELETE Delete DNSSEC records permission needed: #zone_settings:edit
free
pro
business
enterprise

Delete DNSSEC

DELETE zones/:zone_identifier/dnssec

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/dnssec" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

DNS Firewall

DNS Firewall cluster management

dns-firewall

Object definition

View properties and constraints defined on the object

Show definition

dns-firewall-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/dns_firewall

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 DNS records per page `20`	default value: 20 min value:5 max value:100

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/dns_firewall?page=1&per_page=20" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "9a7806061c88ada191ed06f989cc3dac",
      "name": "My Awesome DNS Firewall cluster",
      "origin_ips": [
        "192.0.2.1",
        "198.51.100.1",
        "2001:DB8:100::CF"
      ],
      "dns_firewall_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,
      "negative_cache_ttl": 900,
      "deprecate_any_requests": true,
      "ecs_fallback": false,
      "ratelimit": 600,
      "attack_mitigation": {
        "enabled": true,
        "only_when_origin_unhealthy": false
      },
      "modified_on": "2014-01-01T05:20:00.12345Z"
    }
  ]
}

dns-firewall-dns-firewall-cluster-details

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

Show a single configured DNS Firewall cluster for an account

GET accounts/:account_identifier/dns_firewall/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/dns_firewall/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "name": "My Awesome DNS Firewall cluster",
    "origin_ips": [
      "192.0.2.1",
      "198.51.100.1",
      "2001:DB8:100::CF"
    ],
    "dns_firewall_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,
    "negative_cache_ttl": 900,
    "deprecate_any_requests": true,
    "ecs_fallback": false,
    "ratelimit": 600,
    "attack_mitigation": {
      "enabled": true,
      "only_when_origin_unhealthy": false
    },
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

dns-firewall-update-dns-firewall-cluster

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

Modify a DNS Firewall Cluster configuration

PATCH accounts/:account_identifier/dns_firewall/:identifier

Optional parameters

Name /type	Description /example	Constraints
dns_firewall_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 »
negative_cache_ttl numbernull	Negative DNS Cache TTL `900`	default value: null min value:30 max value:36000
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
attack_mitigation objectnull	Attack mitigation settings `{ "enabled": true, "only_when_origin_unhealthy": false }` An object with the following properties: Show definition »
id string	API item identifier tag `"9a7806061c88ada191ed06f989cc3dac"`	max length: 32 read only
ratelimit numbernull	Ratelimit in queries per second per datacenter (applies to DNS queries sent to the origin nameservers configured on the cluster). `600`	default value: null min value:100 max value:1000000000
minimum_cache_ttl number	Minimum DNS Cache TTL `60`	default value: 60 min value:30 max value:36000

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/dns_firewall/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: user@example.com" \
     -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"],"dns_firewall_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,"negative_cache_ttl":900,"deprecate_any_requests":true,"ecs_fallback":false,"ratelimit":600,"attack_mitigation":{"enabled":true,"only_when_origin_unhealthy":false},"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"
    ],
    "dns_firewall_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,
    "negative_cache_ttl": 900,
    "deprecate_any_requests": true,
    "ecs_fallback": false,
    "ratelimit": 600,
    "attack_mitigation": {
      "enabled": true,
      "only_when_origin_unhealthy": false
    },
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

dns-firewall-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/dns_firewall/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/dns_firewall/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

dns-firewall-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/dns_firewall

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
negative_cache_ttl numbernull	Negative DNS Cache TTL `900`	default value: null 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 numbernull	Ratelimit in queries per second per datacenter (applies to DNS queries sent to the origin nameservers configured on the cluster). `600`	default value: null min value:100 max value:1000000000

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/dns_firewall" \
     -H "X-Auth-Email: user@example.com" \
     -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,"negative_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"
    ],
    "dns_firewall_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,
    "negative_cache_ttl": 900,
    "deprecate_any_requests": true,
    "ecs_fallback": false,
    "ratelimit": 600,
    "attack_mitigation": {
      "enabled": true,
      "only_when_origin_unhealthy": false
    },
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

DNS Firewall (Legacy)

Legacy DNS Firewall routes

dns-firewall-legacy-

Object definition

View properties and constraints defined on the object

Show definition

dns-firewall-legacy--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

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 DNS records per page `20`	default value: 20 min value:5 max value:100

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/virtual_dns?page=1&per_page=20" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "9a7806061c88ada191ed06f989cc3dac",
      "name": "My 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,
      "negative_cache_ttl": 900,
      "deprecate_any_requests": true,
      "ecs_fallback": false,
      "ratelimit": 600,
      "modified_on": "2014-01-01T05:20:00.12345Z"
    }
  ]
}

dns-firewall-legacy--dns-firewall-cluster-details

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

Show a single configured DNS Firewall cluster 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: user@example.com" \
     -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,
    "negative_cache_ttl": 900,
    "deprecate_any_requests": true,
    "ecs_fallback": false,
    "ratelimit": 600,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

dns-firewall-legacy--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 »
negative_cache_ttl numbernull	Negative 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)
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 per datacenter (applies to DNS queries sent to the origin nameservers configured on the cluster). `600`	max value:100000000 notes: A ratelimit of 0 turns off the ratelimit. Otherwise the minimum is 100.
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: user@example.com" \
     -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,"negative_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,
    "negative_cache_ttl": 900,
    "deprecate_any_requests": true,
    "ecs_fallback": false,
    "ratelimit": 600,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

dns-firewall-legacy--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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

dns-firewall-legacy--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
negative_cache_ttl numbernull	Negative 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 per datacenter (applies to DNS queries sent to the origin nameservers configured on the cluster). `600`	max value:100000000 notes: A ratelimit of 0 turns off the ratelimit. Otherwise the minimum is 100.

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/virtual_dns" \
     -H "X-Auth-Email: user@example.com" \
     -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,"negative_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,
    "negative_cache_ttl": 900,
    "deprecate_any_requests": true,
    "ecs_fallback": false,
    "ratelimit": 600,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

DNS Firewall Analytics

Analytics for a DNS Firewall cluster

$dns-firewall-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 to filter on. For example: queryName
operator — defines the type of filter match to use. Operators are specific to dimensions.
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	`dimension>1000`	Return results where a dimension is higher than `1000`	`%3E`
`<`	Less than	`dimension<1000`	Return results where a dimension is lower than `1000`	`%3C`
`>=`	Greater than or equal to	`dimension>=1000`	Return results where a dimension is higher than or equal to `1000`	`%3E%3D`
`<=`	Less than or equal to	`dimension<=1000`	Return results where a dimension 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

Examples:

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

dns-firewall-analytics-table

GET Table permission needed: #analytics:read

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

GET accounts/:account_identifier/dns_firewall/: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/dns_firewall/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: user@example.com" \
     -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-by-time

GET By Time permission needed: #analytics:read

Retrieves a list of aggregate metrics grouped by time interval.

GET accounts/:account_identifier/dns_firewall/: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/dns_firewall/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: user@example.com" \
     -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 (Legacy)

Legacy DNS Firewall Analytics routes

dns-firewall-analytics-legacy-

Object definition

View properties and constraints defined on the object

Show definition

dns-firewall-analytics-legacy--table

GET Table permission needed: #analytics:read

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: user@example.com" \
     -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-legacy--by-time

GET By Time permission needed: #analytics:read

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: user@example.com" \
     -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 Zone)

Configure Secondary DNS for the Secondary Zone (Cloudflare as Secondary).

secondary-dns-secondary-zone-

Object definition

View properties and constraints defined on the object

Show definition

secondary-dns-secondary-zone--secondary-zone-configuration-details

GET Secondary Zone Configuration Details permission needed: #dns_records:read
free
pro
business
enterprise

Get secondary zone configuration for incoming zone transfers

GET zones/:identifier/secondary_dns/incoming

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/269d8f4853475ca241c4e730be286b20/secondary_dns/incoming" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "269d8f4853475ca241c4e730be286b20",
    "name": "www.example.com.",
    "peers": [
      "23ff594956f20c2a721606e94745a8aa",
      "00920f38ce07c2e2f4df50b1f61d4194"
    ],
    "auto_refresh_seconds": 86400,
    "soa_serial": 2019102400,
    "created_time": "2019-10-24T17:09:42.883908+01:00",
    "checked_time": "2019-10-24T17:09:42.883908+01:00",
    "modified_time": "2019-10-24T17:09:42.883908+01:00"
  }
}

secondary-dns-secondary-zone--update-secondary-zone-configuration

PUT Update Secondary Zone Configuration permission needed: #dns_records:edit
free
pro
business
enterprise

Update secondary zone configuration for incoming zone transfers

PUT zones/:identifier/secondary_dns/incoming

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."`
peers array	A list of peer tags `[ "23ff594956f20c2a721606e94745a8aa", "00920f38ce07c2e2f4df50b1f61d4194" ]`
auto_refresh_seconds number	How often should a secondary zone auto refresh regardless of DNS NOTIFY. Not applicable for primary zones. `86400`

cURL (example)

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

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "269d8f4853475ca241c4e730be286b20",
    "name": "www.example.com.",
    "peers": [
      "23ff594956f20c2a721606e94745a8aa",
      "00920f38ce07c2e2f4df50b1f61d4194"
    ],
    "auto_refresh_seconds": 86400,
    "soa_serial": 2019102400,
    "created_time": "2019-10-24T17:09:42.883908+01:00",
    "checked_time": "2019-10-24T17:09:42.883908+01:00",
    "modified_time": "2019-10-24T17:09:42.883908+01:00"
  }
}

secondary-dns-secondary-zone--delete-secondary-zone-configuration

DELETE Delete Secondary Zone Configuration permission needed: #dns_records:edit
free
pro
business
enterprise

Delete secondary zone configuration for incoming zone transfers

DELETE zones/:identifier/secondary_dns/incoming

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/269d8f4853475ca241c4e730be286b20/secondary_dns/incoming" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

secondary-dns-secondary-zone--create-secondary-zone-configuration

POST Create Secondary Zone Configuration permission needed: #dns_records:edit
free
pro
business
enterprise

Create secondary zone configuration for incoming zone transfers

POST zones/:identifier/secondary_dns/incoming

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."`
peers array	A list of peer tags `[ "23ff594956f20c2a721606e94745a8aa", "00920f38ce07c2e2f4df50b1f61d4194" ]`
auto_refresh_seconds number	How often should a secondary zone auto refresh regardless of DNS NOTIFY. Not applicable for primary zones. `86400`

cURL (example)

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

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "269d8f4853475ca241c4e730be286b20",
    "name": "www.example.com.",
    "peers": [
      "23ff594956f20c2a721606e94745a8aa",
      "00920f38ce07c2e2f4df50b1f61d4194"
    ],
    "auto_refresh_seconds": 86400,
    "soa_serial": 2019102400,
    "created_time": "2019-10-24T17:09:42.883908+01:00",
    "checked_time": "2019-10-24T17:09:42.883908+01:00",
    "modified_time": "2019-10-24T17:09:42.883908+01:00"
  }
}

secondary-dns-secondary-zone--force-axfr

POST Force AXFR permission needed: #dns_records:edit
free
pro
business
enterprise

Sends AXFR zone transfer request to primary nameserver(s).

POST zones/:identifier/secondary_dns/force_axfr

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/269d8f4853475ca241c4e730be286b20/secondary_dns/force_axfr" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Secondary DNS (Primary Zone)

Configure Secondary DNS for the Primary Zone (Cloudflare as Primary).

secondary-dns-primary-zone-

Object definition

View properties and constraints defined on the object

Show definition

secondary-dns-primary-zone--primary-zone-configuration-details

GET Primary Zone Configuration Details
free
pro
business
enterprise

Get primary zone configuration for outgoing zone transfers

GET zones/:identifier/secondary_dns/outgoing

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/269d8f4853475ca241c4e730be286b20/secondary_dns/outgoing" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "269d8f4853475ca241c4e730be286b20",
    "name": "www.example.com.",
    "peers": [
      "23ff594956f20c2a721606e94745a8aa",
      "00920f38ce07c2e2f4df50b1f61d4194"
    ],
    "soa_serial": 2019102400,
    "created_time": "2019-10-24T17:09:42.883908+01:00",
    "checked_time": "2019-10-24T17:09:42.883908+01:00",
    "last_transferred_time": "2019-10-24T17:09:42.883908+01:00"
  }
}

secondary-dns-primary-zone--update-primary-zone-configuration

PUT Update Primary Zone Configuration
free
pro
business
enterprise

Update primary zone configuration for outgoing zone transfers

PUT zones/:identifier/secondary_dns/outgoing

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."`
peers array	A list of peer tags `[ "23ff594956f20c2a721606e94745a8aa", "00920f38ce07c2e2f4df50b1f61d4194" ]`

cURL (example)

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

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "269d8f4853475ca241c4e730be286b20",
    "name": "www.example.com.",
    "peers": [
      "23ff594956f20c2a721606e94745a8aa",
      "00920f38ce07c2e2f4df50b1f61d4194"
    ],
    "soa_serial": 2019102400,
    "created_time": "2019-10-24T17:09:42.883908+01:00",
    "checked_time": "2019-10-24T17:09:42.883908+01:00",
    "last_transferred_time": "2019-10-24T17:09:42.883908+01:00"
  }
}

secondary-dns-primary-zone--delete-primary-zone-configuration

DELETE Delete Primary Zone Configuration
free
pro
business
enterprise

Delete primary zone configuration for outgoing zone transfers

DELETE zones/:identifier/secondary_dns/outgoing

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/269d8f4853475ca241c4e730be286b20/secondary_dns/outgoing" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

secondary-dns-primary-zone--create-primary-zone-configuration

POST Create Primary Zone Configuration
free
pro
business
enterprise

Create primary zone configuration for outgoing zone transfers

POST zones/:identifier/secondary_dns/outgoing

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."`
peers array	A list of peer tags `[ "23ff594956f20c2a721606e94745a8aa", "00920f38ce07c2e2f4df50b1f61d4194" ]`

cURL (example)

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

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "269d8f4853475ca241c4e730be286b20",
    "name": "www.example.com.",
    "peers": [
      "23ff594956f20c2a721606e94745a8aa",
      "00920f38ce07c2e2f4df50b1f61d4194"
    ],
    "soa_serial": 2019102400,
    "created_time": "2019-10-24T17:09:42.883908+01:00",
    "checked_time": "2019-10-24T17:09:42.883908+01:00",
    "last_transferred_time": "2019-10-24T17:09:42.883908+01:00"
  }
}

secondary-dns-primary-zone--enable-outgoing-zone-transfers

POST Enable Outgoing Zone Transfers
free
pro
business
enterprise

Enable outgoing zone transfers for primary zone

POST zones/:identifier/secondary_dns/outgoing/enable

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/269d8f4853475ca241c4e730be286b20/secondary_dns/outgoing/enable" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

secondary-dns-primary-zone--disable-outgoing-zone-transfers

POST Disable Outgoing Zone Transfers
free
pro
business
enterprise

Disable outgoing zone transfers for primary zone and clears IXFR backlog of primary zone.

POST zones/:identifier/secondary_dns/outgoing/disable

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/269d8f4853475ca241c4e730be286b20/secondary_dns/outgoing/disable" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

secondary-dns-primary-zone--get-outgoing-zone-transfer-status

GET Get Outgoing Zone Transfer Status
free
pro
business
enterprise

Get primary zone transfer status

GET zones/:identifier/secondary_dns/outgoing/status

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/269d8f4853475ca241c4e730be286b20/secondary_dns/outgoing/status" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

secondary-dns-primary-zone--force-dns-notify

POST Force DNS NOTIFY
free
pro
business
enterprise

Notifies the secondary nameserver(s) and clears IXFR backlog of primary zone.

POST zones/:identifier/secondary_dns/outgoing/force_notify

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/269d8f4853475ca241c4e730be286b20/secondary_dns/outgoing/force_notify" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

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 permission needed: #dns_records:read#organization:read
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: user@example.com" \
     -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--tsig-details

GET TSIG Details permission needed: #dns_records:read#organization:read
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: user@example.com" \
     -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 permission needed: #dns_records:edit#organization:read
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: user@example.com" \
     -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 permission needed: #dns_records:edit#organization:read
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: user@example.com" \
     -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 permission needed: #dns_records:edit#organization:read
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."`
algo string	TSIG algorithm `"hmac-sha512."`

Optional parameters

Name /type	Description /example	Constraints
secret string	TSIG secret. If none specified a new one will be generated at create time. `"caf79a7804b04337c9c66ccd7bef9190a1e1679b5dd03d8aa10f7ad45e1a9dab92b417896c15d4d007c7c14194538d2a5d0feffdecc5a7f0e1c570cfa700837c"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/secondary_dns/tsigs" \
     -H "X-Auth-Email: user@example.com" \
     -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 (Peer)

Peer nameservers for secondary DNS

secondary-dns-peer-

Object definition

View properties and constraints defined on the object

Show definition

secondary-dns-peer--list-peers

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

List Peers

GET accounts/:account_identifier/secondary_dns/peers

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/secondary_dns/peers" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

secondary-dns-peer--peer-details

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

Get Peer

GET accounts/:account_identifier/secondary_dns/peers/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/secondary_dns/peers/23ff594956f20c2a721606e94745a8aa" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

secondary-dns-peer--update-peer

PUT Update Peer permission needed: #dns_records:edit#organization:read
free
pro
business
enterprise

Modify Peer

PUT accounts/:account_identifier/secondary_dns/peers/:identifier

Required parameters

Name /type	Description /example	Constraints
id string	API item identifier tag `"23ff594956f20c2a721606e94745a8aa"`	max length: 32 read only
name string	The name of the peer `"my-peer-1"`

Optional parameters

Name /type	Description /example	Constraints
ip string	IPv4/IPv6 address of primary or secondary nameserver, depending on what zone this peer is linked to. For primary zones this IP defines the IP of the secondary nameserver Cloudflare will NOTIFY upon zone changes. For secondary zones this IP defines the IP of the primary nameserver Cloudflare will send AXFR/IXFR requests to. `"192.0.2.53"`
port number	DNS port of primary or secondary nameserver, depending on what zone this peer is linked to. `53`
ixfr_enable boolean	Enable IXFR transfer protocol, default is AXFR. Only applicable to secondary zones. `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/peers/23ff594956f20c2a721606e94745a8aa" \
     -H "X-Auth-Email: user@example.com" \
     -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","name":"my-peer-1"}'

Response (example)

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

secondary-dns-peer--delete-peer

DELETE Delete Peer permission needed: #dns_records:edit#organization:read
free
pro
business
enterprise

Delete Peer

DELETE accounts/:account_identifier/secondary_dns/peers/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/secondary_dns/peers/23ff594956f20c2a721606e94745a8aa" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

secondary-dns-peer--create-peer

POST Create Peer permission needed: #dns_records:edit#organization:read
free
pro
business
enterprise

Create Peer

POST accounts/:account_identifier/secondary_dns/peers

Required parameters

Name /type	Description /example	Constraints
name string	The name of the peer `"my-peer-1"`

Optional parameters

Name /type	Description /example	Constraints
ip string	IPv4/IPv6 address of primary or secondary nameserver, depending on what zone this peer is linked to. For primary zones this IP defines the IP of the secondary nameserver Cloudflare will NOTIFY upon zone changes. For secondary zones this IP defines the IP of the primary nameserver Cloudflare will send AXFR/IXFR requests to. `"192.0.2.53"`
port number	DNS port of primary or secondary nameserver, depending on what zone this peer is linked to. `53`
ixfr_enable boolean	Enable IXFR transfer protocol, default is AXFR. Only applicable to secondary zones. `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/peers" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"ip":"192.0.2.53","port":53,"ixfr_enable":false,"tsig_id":"69cd1e104af3e6ed3cb344f263fd0d5a","name":"my-peer-1"}'

Response (example)

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

Secondary DNS (ACL)

Access Control List (ACL) management for secondary DNS

secondary-dns-acl-

Object definition

View properties and constraints defined on the object

Show definition

secondary-dns-acl--list-acls

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

List ACLs

GET accounts/:account_identifier/secondary_dns/acls

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/secondary_dns/acls" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "23ff594956f20c2a721606e94745a8aa",
      "ip_range": "192.0.2.53/28",
      "name": "my-acl-1"
    }
  ]
}

secondary-dns-acl--acl-details

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

Get ACL

GET accounts/:account_identifier/secondary_dns/acls/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/secondary_dns/acls/23ff594956f20c2a721606e94745a8aa" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "23ff594956f20c2a721606e94745a8aa",
    "ip_range": "192.0.2.53/28",
    "name": "my-acl-1"
  }
}

secondary-dns-acl--update-acl

PUT Update ACL permission needed: #dns_records:edit#organization:read
free
pro
business
enterprise

Modify ACL

PUT accounts/:account_identifier/secondary_dns/acls/:identifier

Required parameters

Name /type	Description /example	Constraints
id string	API item identifier tag `"23ff594956f20c2a721606e94745a8aa"`	max length: 32 read only
ip_range string	Allowed IPv4/IPv6 address range of primary or secondary nameservers. This will be applied for the entire account. The IP range is used to allow additional NOTIFY IPs for secondary zones and IPs Cloudflare allows AXFR/IXFR requests from for primary zones. CIDRs are limited to a maximum of /24 for IPv4 and /64 for IPv6 respectively. `"192.0.2.53/28"`
name string	The name of the acl `"my-acl-1"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/secondary_dns/acls/23ff594956f20c2a721606e94745a8aa" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"23ff594956f20c2a721606e94745a8aa","ip_range":"192.0.2.53/28","name":"my-acl-1"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "23ff594956f20c2a721606e94745a8aa",
    "ip_range": "192.0.2.53/28",
    "name": "my-acl-1"
  }
}

secondary-dns-acl--delete-acl

DELETE Delete ACL permission needed: #dns_records:edit#organization:read
free
pro
business
enterprise

Delete ACL

DELETE accounts/:account_identifier/secondary_dns/acls/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/secondary_dns/acls/23ff594956f20c2a721606e94745a8aa" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

secondary-dns-acl--create-acl

POST Create ACL permission needed: #dns_records:edit#organization:read
free
pro
business
enterprise

Create ACL

POST accounts/:account_identifier/secondary_dns/acls

Required parameters

Name /type	Description /example	Constraints
id string	API item identifier tag `"23ff594956f20c2a721606e94745a8aa"`	max length: 32 read only
ip_range string	Allowed IPv4/IPv6 address range of primary or secondary nameservers. This will be applied for the entire account. The IP range is used to allow additional NOTIFY IPs for secondary zones and IPs Cloudflare allows AXFR/IXFR requests from for primary zones. CIDRs are limited to a maximum of /24 for IPv4 and /64 for IPv6 respectively. `"192.0.2.53/28"`
name string	The name of the acl `"my-acl-1"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/secondary_dns/acls" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"23ff594956f20c2a721606e94745a8aa","ip_range":"192.0.2.53/28","name":"my-acl-1"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "23ff594956f20c2a721606e94745a8aa",
    "ip_range": "192.0.2.53/28",
    "name": "my-acl-1"
  }
}

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"
    ],
    "etag": "a8e453d9d129a3769407127936edfdb0"
  }
}

Account-Level Custom Nameservers

Configure custom nameservers that can be used by multiple zones in the account

account-level-custom-nameservers

Object definitions

View properties and constraints defined on the object

Show definitions

account-level-custom-nameservers-list-account-custom-nameservers

GET List Account Custom Nameservers permission needed: #organization:read
free
pro
business
enterprise

List an account's custom nameservers

GET accounts/:identifier/custom_ns

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/372e67954025e0ba6aaa6d586b9e0b59/custom_ns" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "dns_records": [
        {
          "type": "A",
          "value": "1.1.1.1"
        }
      ],
      "ns_name": "ns1.example.com",
      "status": "verified",
      "zone_tag": "023e105f4ecef8ad9ca31a8372d0c353"
    }
  ]
}

account-level-custom-nameservers-add-account-custom-nameserver

POST Add Account Custom Nameserver permission needed: #organization:edit
free
pro
business
enterprise

POST accounts/:identifier/custom_ns

Required parameters

Name /type	Description /example	Constraints
ns_name string (hostname)	The FQDN of the name server `"ns1.example.com"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/372e67954025e0ba6aaa6d586b9e0b59/custom_ns" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"ns_name":"ns1.example.com"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "dns_records": [
      {
        "type": "A",
        "value": "1.1.1.1"
      }
    ],
    "ns_name": "ns1.example.com",
    "status": "verified",
    "zone_tag": "023e105f4ecef8ad9ca31a8372d0c353"
  }
}

account-level-custom-nameservers-verify-account-custom-nameserver-glue-records

POST Verify Account Custom Nameserver Glue Records permission needed: #organization:edit
free
pro
business
enterprise

POST accounts/:identifier/custom_ns/verify

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/372e67954025e0ba6aaa6d586b9e0b59/custom_ns/verify" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "dns_records": [
        {
          "type": "A",
          "value": "1.1.1.1"
        }
      ],
      "ns_name": "ns1.example.com",
      "status": "verified",
      "zone_tag": "023e105f4ecef8ad9ca31a8372d0c353"
    }
  ]
}

account-level-custom-nameservers-delete-account-custom-nameserver

DELETE Delete Account Custom Nameserver permission needed: #organization:edit
free
pro
business
enterprise

DELETE accounts/:identifier/custom_ns/:ns_name

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/372e67954025e0ba6aaa6d586b9e0b59/custom_ns/ns1.example.com" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

account-level-custom-nameservers-get-eligible-zones-for-account-custom-nameservers

GET Get Eligible Zones for Account Custom Nameservers permission needed: #organization:read
free
pro
business
enterprise

GET accounts/:identifier/custom_ns/availability

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/372e67954025e0ba6aaa6d586b9e0b59/custom_ns/availability" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Account-Level Custom Nameservers error codes

Code	Description
1000	Unknown error
1001	Invalid request
1002	Account does not have access to this feature
1003	Not found

Account-Level Custom Nameservers Notes

If you want new zones in the account to use account custom nameservers by default, use PUT /accounts/:identifier to set the account setting use_account_custom_ns_by_default to true.

Account-Level Custom Nameservers Usage for a Zone

Per-zone usage of Cloudflare account-level custom nameservers

account-level-custom-nameservers-usage-for-a-zone

Object definitions

View properties and constraints defined on the object

Show definitions

GET Get Account Custom Nameserver Related Zone Metadata permission needed: #zone:read
free
pro
business
enterprise

GET zones/:zone_identifier/custom_ns

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_ns" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

PUT Set Account Custom Nameserver Related Zone Metadata permission needed: #zone:edit
free
pro
business
enterprise

PUT zones/:zone_identifier/custom_ns

Optional parameters

Name /type	Description /example	Constraints
enabled boolean	Whether zone uses account-level custom nameservers `true`	valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_ns" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"enabled":true}'

Response (example)

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

Account-Level Custom Nameservers Usage for a Zone error codes

Code	Description
1000	Unknown error
1001	Invalid request
1002	Account does not have access to this feature
1003	Not found

Custom pages for a zone

Custom pages configuration at the zone level.

custom-pages-for-a-zone

Object definitions

View properties and constraints defined on the object

Show definitions

custom-pages-for-a-zone-get-custom-pages

GET Get custom pages permission needed: #zone_settings:read
free
pro
business
enterprise

Fetches all the custom pages at the zone level.

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: user@example.com" \
     -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-get-a-custom-page

GET Get a custom page permission needed: #zone_settings:read
free
pro
business
enterprise

Fetches the details of a custom page.

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: user@example.com" \
     -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-a-custom-page

PUT Update a custom page permission needed: #zone_settings:edit
free
pro
business
enterprise

Updates the configuration of an existing custom page.

PUT zones/:zone_identifier/custom_pages/:identifier

Required parameters

Name /type	Description /example	Constraints
url string (url)	The URL 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: user@example.com" \
     -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 higher priority will break ties across overlapping 'legacy_custom' certificates, but 'legacy_custom' certificates will always supercede 'sni_custom' certificates.

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: user@example.com" \
     -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"
      },
      "policy": "(country: US) or (region: EU)",
      "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-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 »
policy string	Specify the policy that determines the region where your private key will be held locally. 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. Any combination of countries, specified by their two letter country code (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) can be chosen, such as 'country: IN', as well as 'region: EU' which refers to the EU region. If there are too few data centers satisfying the policy, it will be rejected. `"(country: US) or (region: EU)"`
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: user@example.com" \
     -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"},"policy":"(country: US) or (region: EU)","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"
    },
    "policy": "(country: US) or (region: EU)",
    "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: user@example.com" \
     -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"
    },
    "policy": "(country: US) or (region: EU)",
    "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 »
policy string	Specify the policy that determines the region where your private key will be held locally. 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. Any combination of countries, specified by their two letter country code (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) can be chosen, such as 'country: IN', as well as 'region: EU' which refers to the EU region. If there are too few data centers satisfying the policy, it will be rejected. `"(country: US) or (region: EU)"`

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_certificates/2458ce5a-0c35-4c7f-82c7-8e9487d3ff60" \
     -H "X-Auth-Email: user@example.com" \
     -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"},"policy":"(country: US) or (region: EU)"}'

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"
    },
    "policy": "(country: US) or (region: EU)",
    "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

Remove a SSL certificate from a zone.

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: user@example.com" \
     -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. The higher priority will break ties across overlapping 'legacy_custom' certificates.

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: user@example.com" \
     -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"
      },
      "policy": "(country: US) or (region: EU)",
      "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 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: user@example.com" \
     -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": {
        "id": "0d89c70d-ad9f-4843-b99f-6cc0252067e9",
        "status": "pending_validation",
        "method": "txt",
        "type": "dv",
        "validation_records": [
          {
            "txt_name": "_acme-challenge.app.example.com",
            "txt_value": "810b7d5f01154524b961ba0cd578acc2",
            "http_url": "http://app.example.com/.well-known/pki-validation/ca3-da12a1c25e7b48cf80408c6c1763b8a2.txt",
            "http_body": "ca3-574923932a82475cb8592200f1a2a23d",
            "emails": [
              "administrator@example.com",
              "webmaster@example.com"
            ]
          }
        ],
        "validation_errors": [
          {
            "message": "SERVFAIL looking up CAA for app.example.com"
          }
        ],
        "hosts": [
          "app.example.com",
          "*.app.example.com"
        ],
        "issuer": "DigiCertInc",
        "serial_number": "6743787633689793699141714808227354901",
        "signature": "SHA256WithRSA",
        "uploaded_on": "2020-02-06T18:11:23.531995Z",
        "expires_on": "2021-02-06T18:11:23.531995Z",
        "custom_csr_id": "7b163417-1d2b-4c84-a38a-2fb7a0cd7752",
        "settings": {
          "http2": "on",
          "min_tls_version": "1.2",
          "tls_1_3": "on",
          "ciphers": [
            "ECDHE-RSA-AES128-GCM-SHA256",
            "AES128-SHA"
          ],
          "early_hints": "on"
        },
        "bundle_method": "ubiquitous",
        "wildcard": false,
        "certificate_authority": "digicert",
        "custom_certificate": "-----BEGIN CERTIFICATE-----\\nMIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN\\nMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E...SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O\\nOeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7\\n-----END CERTIFICATE-----\\n",
        "custom_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"
      },
      "custom_metadata": {
        "key": "value"
      },
      "custom_origin_server": "origin2.example.com",
      "custom_origin_sni": "sni.example.com",
      "status": "pending",
      "verification_errors": [
        "None of the A or AAAA records are owned by this account and the pre-generated ownership verification token was not found."
      ],
      "ownership_verification": {
        "type": "txt",
        "name": "_cf-custom-hostname.app.example.com",
        "value": "5cc07c04-ea62-4a5a-95f0-419334a875a4"
      },
      "ownership_verification_http": {
        "http_url": "http://custom.test.com/.well-known/cf-custom-hostname-challenge/0d89c70d-ad9f-4843-b99f-6cc0252067e9",
        "http_body": "5cc07c04-ea62-4a5a-95f0-419334a875a4"
      },
      "created_at": "2020-02-06T18:11:23.531995Z"
    }
  ]
}

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, txt, 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. 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" ], "early_hints": "on" }, "bundle_method": "ubiquitous", "wildcard": false, "custom_certificate": "-----BEGIN CERTIFICATE-----\\nMIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN\\nMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E...SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O\\nOeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7\\n-----END CERTIFICATE-----\\n", "custom_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" } 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: user@example.com" \
     -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"],"early_hints":"on"},"bundle_method":"ubiquitous","wildcard":false,"custom_certificate":"-----BEGIN CERTIFICATE-----\\nMIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN\\nMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E...SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O\\nOeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7\\n-----END CERTIFICATE-----\\n","custom_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"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "0d89c70d-ad9f-4843-b99f-6cc0252067e9",
    "hostname": "app.example.com",
    "ssl": {
      "id": "0d89c70d-ad9f-4843-b99f-6cc0252067e9",
      "status": "pending_validation",
      "method": "txt",
      "type": "dv",
      "validation_records": [
        {
          "txt_name": "_acme-challenge.app.example.com",
          "txt_value": "810b7d5f01154524b961ba0cd578acc2",
          "http_url": "http://app.example.com/.well-known/pki-validation/ca3-da12a1c25e7b48cf80408c6c1763b8a2.txt",
          "http_body": "ca3-574923932a82475cb8592200f1a2a23d",
          "emails": [
            "administrator@example.com",
            "webmaster@example.com"
          ]
        }
      ],
      "validation_errors": [
        {
          "message": "SERVFAIL looking up CAA for app.example.com"
        }
      ],
      "hosts": [
        "app.example.com",
        "*.app.example.com"
      ],
      "issuer": "DigiCertInc",
      "serial_number": "6743787633689793699141714808227354901",
      "signature": "SHA256WithRSA",
      "uploaded_on": "2020-02-06T18:11:23.531995Z",
      "expires_on": "2021-02-06T18:11:23.531995Z",
      "custom_csr_id": "7b163417-1d2b-4c84-a38a-2fb7a0cd7752",
      "settings": {
        "http2": "on",
        "min_tls_version": "1.2",
        "tls_1_3": "on",
        "ciphers": [
          "ECDHE-RSA-AES128-GCM-SHA256",
          "AES128-SHA"
        ],
        "early_hints": "on"
      },
      "bundle_method": "ubiquitous",
      "wildcard": false,
      "certificate_authority": "digicert",
      "custom_certificate": "-----BEGIN CERTIFICATE-----\\nMIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN\\nMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E...SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O\\nOeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7\\n-----END CERTIFICATE-----\\n",
      "custom_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"
    },
    "custom_metadata": {
      "key": "value"
    },
    "custom_origin_server": "origin2.example.com",
    "custom_origin_sni": "sni.example.com",
    "status": "pending",
    "verification_errors": [
      "None of the A or AAAA records are owned by this account and the pre-generated ownership verification token was not found."
    ],
    "ownership_verification": {
      "type": "txt",
      "name": "_cf-custom-hostname.app.example.com",
      "value": "5cc07c04-ea62-4a5a-95f0-419334a875a4"
    },
    "ownership_verification_http": {
      "http_url": "http://custom.test.com/.well-known/cf-custom-hostname-challenge/0d89c70d-ad9f-4843-b99f-6cc0252067e9",
      "http_body": "5cc07c04-ea62-4a5a-95f0-419334a875a4"
    },
    "created_at": "2020-02-06T18:11:23.531995Z"
  }
}

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: user@example.com" \
     -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": {
      "id": "0d89c70d-ad9f-4843-b99f-6cc0252067e9",
      "status": "pending_validation",
      "method": "txt",
      "type": "dv",
      "validation_records": [
        {
          "txt_name": "_acme-challenge.app.example.com",
          "txt_value": "810b7d5f01154524b961ba0cd578acc2",
          "http_url": "http://app.example.com/.well-known/pki-validation/ca3-da12a1c25e7b48cf80408c6c1763b8a2.txt",
          "http_body": "ca3-574923932a82475cb8592200f1a2a23d",
          "emails": [
            "administrator@example.com",
            "webmaster@example.com"
          ]
        }
      ],
      "validation_errors": [
        {
          "message": "SERVFAIL looking up CAA for app.example.com"
        }
      ],
      "hosts": [
        "app.example.com",
        "*.app.example.com"
      ],
      "issuer": "DigiCertInc",
      "serial_number": "6743787633689793699141714808227354901",
      "signature": "SHA256WithRSA",
      "uploaded_on": "2020-02-06T18:11:23.531995Z",
      "expires_on": "2021-02-06T18:11:23.531995Z",
      "custom_csr_id": "7b163417-1d2b-4c84-a38a-2fb7a0cd7752",
      "settings": {
        "http2": "on",
        "min_tls_version": "1.2",
        "tls_1_3": "on",
        "ciphers": [
          "ECDHE-RSA-AES128-GCM-SHA256",
          "AES128-SHA"
        ],
        "early_hints": "on"
      },
      "bundle_method": "ubiquitous",
      "wildcard": false,
      "certificate_authority": "digicert",
      "custom_certificate": "-----BEGIN CERTIFICATE-----\\nMIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN\\nMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E...SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O\\nOeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7\\n-----END CERTIFICATE-----\\n",
      "custom_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"
    },
    "custom_metadata": {
      "key": "value"
    },
    "custom_origin_server": "origin2.example.com",
    "custom_origin_sni": "sni.example.com",
    "status": "pending",
    "verification_errors": [
      "None of the A or AAAA records are owned by this account and the pre-generated ownership verification token was not found."
    ],
    "ownership_verification": {
      "type": "txt",
      "name": "_cf-custom-hostname.app.example.com",
      "value": "5cc07c04-ea62-4a5a-95f0-419334a875a4"
    },
    "ownership_verification_http": {
      "http_url": "http://custom.test.com/.well-known/cf-custom-hostname-challenge/0d89c70d-ad9f-4843-b99f-6cc0252067e9",
      "http_body": "5cc07c04-ea62-4a5a-95f0-419334a875a4"
    },
    "created_at": "2020-02-06T18:11:23.531995Z"
  }
}

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" ], "early_hints": "on" }, "bundle_method": "ubiquitous", "wildcard": false, "custom_certificate": "-----BEGIN CERTIFICATE-----\\nMIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN\\nMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E...SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O\\nOeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7\\n-----END CERTIFICATE-----\\n", "custom_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" } One of the following: Show definition »
custom_metadata object	These are per-hostname (customer) settings. `{ "key": "value" }` Any of the following: Show definition »
custom_origin_server string	a valid hostname that’s been added to your DNS zone as an A, AAAA, or CNAME record. `"origin2.example.com"`
custom_origin_sni string	A hostname that will be sent to your custom origin server as SNI for TLS handshake. This can be a valid subdomain of the zone or custom origin server name or the string ':request_host_header:' which will cause the host header in the request to be used as SNI. Not configurable with default/fallback origin server. `"sni.example.com"`

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_hostnames/0d89c70d-ad9f-4843-b99f-6cc0252067e9" \
     -H "X-Auth-Email: user@example.com" \
     -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"],"early_hints":"on"},"bundle_method":"ubiquitous","wildcard":false,"custom_certificate":"-----BEGIN CERTIFICATE-----\\nMIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN\\nMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E...SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O\\nOeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7\\n-----END CERTIFICATE-----\\n","custom_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"},"custom_metadata":{"key":"value"},"custom_origin_server":"origin2.example.com","custom_origin_sni":"sni.example.com"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "0d89c70d-ad9f-4843-b99f-6cc0252067e9",
    "hostname": "app.example.com",
    "ssl": {
      "id": "0d89c70d-ad9f-4843-b99f-6cc0252067e9",
      "status": "pending_validation",
      "method": "txt",
      "type": "dv",
      "validation_records": [
        {
          "txt_name": "_acme-challenge.app.example.com",
          "txt_value": "810b7d5f01154524b961ba0cd578acc2",
          "http_url": "http://app.example.com/.well-known/pki-validation/ca3-da12a1c25e7b48cf80408c6c1763b8a2.txt",
          "http_body": "ca3-574923932a82475cb8592200f1a2a23d",
          "emails": [
            "administrator@example.com",
            "webmaster@example.com"
          ]
        }
      ],
      "validation_errors": [
        {
          "message": "SERVFAIL looking up CAA for app.example.com"
        }
      ],
      "hosts": [
        "app.example.com",
        "*.app.example.com"
      ],
      "issuer": "DigiCertInc",
      "serial_number": "6743787633689793699141714808227354901",
      "signature": "SHA256WithRSA",
      "uploaded_on": "2020-02-06T18:11:23.531995Z",
      "expires_on": "2021-02-06T18:11:23.531995Z",
      "custom_csr_id": "7b163417-1d2b-4c84-a38a-2fb7a0cd7752",
      "settings": {
        "http2": "on",
        "min_tls_version": "1.2",
        "tls_1_3": "on",
        "ciphers": [
          "ECDHE-RSA-AES128-GCM-SHA256",
          "AES128-SHA"
        ],
        "early_hints": "on"
      },
      "bundle_method": "ubiquitous",
      "wildcard": false,
      "certificate_authority": "digicert",
      "custom_certificate": "-----BEGIN CERTIFICATE-----\\nMIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN\\nMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E...SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O\\nOeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7\\n-----END CERTIFICATE-----\\n",
      "custom_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"
    },
    "custom_metadata": {
      "key": "value"
    },
    "custom_origin_server": "origin2.example.com",
    "custom_origin_sni": "sni.example.com",
    "status": "pending",
    "verification_errors": [
      "None of the A or AAAA records are owned by this account and the pre-generated ownership verification token was not found."
    ],
    "ownership_verification": {
      "type": "txt",
      "name": "_cf-custom-hostname.app.example.com",
      "value": "5cc07c04-ea62-4a5a-95f0-419334a875a4"
    },
    "ownership_verification_http": {
      "http_url": "http://custom.test.com/.well-known/cf-custom-hostname-challenge/0d89c70d-ad9f-4843-b99f-6cc0252067e9",
      "http_body": "5cc07c04-ea62-4a5a-95f0-419334a875a4"
    },
    "created_at": "2020-02-06T18:11:23.531995Z"
  }
}

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Custom Hostname Fallback Origin for a Zone

Setup Fallback Origin for all Custom Hostnames for your zone.

custom-hostname-fallback-origin-for-a-zone

Object definition

View properties and constraints defined on the object

Show definition

custom-hostname-fallback-origin-for-a-zone-get-fallback-origin-for-custom-hostnames

GET Get Fallback Origin for Custom Hostnames permission needed: #ssl:read
free
pro
business
enterprise

GET zones/:zone_identifier/custom_hostnames/fallback_origin

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_hostnames/fallback_origin" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "origin": "fallback.example.com",
    "status": "pending_deployment",
    "errors": [
      "DNS records are not setup correctly. Origin should be a proxied A/AAAA/CNAME dns record"
    ],
    "created_at": "2019-10-28T18:11:23.37411Z",
    "updated_at": "2020-03-16T18:11:23.531995Z"
  }
}

custom-hostname-fallback-origin-for-a-zone-update-fallback-origin-for-custom-hostnames

PUT Update Fallback Origin for Custom Hostnames permission needed: #ssl:edit
free
pro
business
enterprise

PUT zones/:zone_identifier/custom_hostnames/fallback_origin

Required parameters

Name /type	Description /example	Constraints
origin string	Your origin hostname that requests to your custom hostnames will be sent to. `"fallback.example.com"`	max length: 255

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_hostnames/fallback_origin" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"origin":"fallback.example.com"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "origin": "fallback.example.com",
    "status": "pending_deployment",
    "errors": [
      "DNS records are not setup correctly. Origin should be a proxied A/AAAA/CNAME dns record"
    ],
    "created_at": "2019-10-28T18:11:23.37411Z",
    "updated_at": "2020-03-16T18:11:23.531995Z"
  }
}

custom-hostname-fallback-origin-for-a-zone-delete-fallback-origin-for-custom-hostnames

DELETE Delete Fallback Origin for Custom Hostnames permission needed: #ssl:edit
free
pro
business
enterprise

DELETE zones/:zone_identifier/custom_hostnames/fallback_origin

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/custom_hostnames/fallback_origin" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "origin": "fallback.example.com",
    "status": "pending_deployment",
    "errors": [
      "DNS records are not setup correctly. Origin should be a proxied A/AAAA/CNAME dns record"
    ],
    "created_at": "2019-10-28T18:11:23.37411Z",
    "updated_at": "2020-03-16T18:11:23.531995Z"
  }
}

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: user@example.com" \
     -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-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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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 active certificate packs

GET zones/:zone_identifier/ssl/certificate_packs

Optional parameters

Name /type	Description /example	Constraints
status	Include Certificate Packs of all statuses, not just active ones. `"all"`	valid values: all

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/ssl/certificate_packs?status=all" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "3822ff90-ea29-44df-9e55-21300bb9419b",
      "type": "custom",
      "hosts": [
        "example.com",
        "*.example.com",
        "www.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"
          },
          "policy": "(country: US) or (region: EU)",
          "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-get-certificate-pack

GET Get Certificate Pack permission needed: #ssl:read
free
pro
business
enterprise

For a given zone, get a certificate pack

GET zones/:zone_identifier/ssl/certificate_packs/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/ssl/certificate_packs/3822ff90-ea29-44df-9e55-21300bb9419b" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "3822ff90-ea29-44df-9e55-21300bb9419b",
    "type": "custom",
    "hosts": [
      "example.com",
      "*.example.com",
      "www.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"
        },
        "policy": "(country: US) or (region: EU)",
        "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-get-certificate-pack-quotas

GET Get Certificate Pack Quotas permission needed: #ssl:read
free
pro
business
enterprise

For a given zone, list certificate pack quotas

GET zones/:zone_identifier/ssl/certificate_packs/quota

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/ssl/certificate_packs/quota" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "advanced": {
      "allocated": 100,
      "used": 5
    }
  }
}

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. Must contain the zone apex, may not contain more than 50 hosts, and may not be empty. `[ "example.com", "*.example.com", "www.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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"hosts":["example.com","*.example.com","www.example.com"]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "3822ff90-ea29-44df-9e55-21300bb9419b",
    "type": "custom",
    "hosts": [
      "example.com",
      "*.example.com",
      "www.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"
        },
        "policy": "(country: US) or (region: EU)",
        "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-order-advanced-certificate-manager-certificate-pack

POST Order Advanced Certificate Manager Certificate Pack permission needed: #ssl:read#ssl:edit
free
pro
business
enterprise

For a given zone, order an advanced certificate pack

POST zones/:zone_identifier/ssl/certificate_packs/order

Required parameters

Name /type	Description /example	Constraints
type string	Type of certificate pack `"advanced"`	valid values: advanced
hosts array	Comma separated list of valid host names for the certificate packs. Must contain the zone apex, may not contain more than 50 hosts, and may not be empty. `[ "example.com", "*.example.com", "www.example.com" ]` An array with items in the following form: Show definition »
validation_method string	Validation Method selected for the order `"txt"`	valid values: txt, http, email
validity_days integer	Validity Days selected for the order `365`	valid values: 14, 30, 90, 365
certificate_authority string	Certificate Authority selected for the order. Selecting Let's Encrypt will reduce customization of other fields: validation_method must be 'txt', validity_days must be 90, cloudflare_branding must be omitted, and hosts must contain only 2 entries, one for the zone name and one for the subdomain wildcard of the zone name (e.g. example.com, *.example.com). `"digicert"`	valid values: digicert, google, lets_encrypt

Optional parameters

Name /type	Description /example	Constraints
cloudflare_branding boolean	Whether or not to add Cloudflare Branding for the order. This will add sni.cloudflaressl.com as the Common Name if set true `false`	valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/ssl/certificate_packs/order" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"advanced","hosts":["example.com","*.example.com","www.example.com"],"validation_method":"txt","validity_days":365,"certificate_authority":"digicert","cloudflare_branding":false}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "3822ff90-ea29-44df-9e55-21300bb9419b",
    "type": "advanced",
    "hosts": [
      "example.com",
      "*.example.com",
      "www.example.com"
    ],
    "status": "initializing",
    "validation_method": "txt",
    "validity_days": 365,
    "certificate_authority": "digicert",
    "cloudflare_branding": false
  }
}

certificate-packs-restart-validation-for-advanced-certificate-manager-certificate-pack

PATCH Restart Validation for Advanced Certificate Manager Certificate Pack permission needed: #ssl:read#ssl:edit
free
pro
business
enterprise

For a given zone, restart validation for an advanced certificate pack. This is only a validation operation for a Certificate Pack in a validation_timed_out status.

PATCH zones/:zone_identifier/ssl/certificate_packs/:identifier

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "3822ff90-ea29-44df-9e55-21300bb9419b",
    "type": "advanced",
    "hosts": [
      "example.com",
      "*.example.com",
      "www.example.com"
    ],
    "status": "initializing",
    "validation_method": "txt",
    "validity_days": 365,
    "certificate_authority": "digicert",
    "cloudflare_branding": false
  }
}

certificate-packs-delete-advanced-certificate-manager-certificate-pack

DELETE Delete Advanced Certificate Manager Certificate Pack permission needed: #ssl:read#ssl:edit
free
pro
business
enterprise

For a given zone, delete an advanced certificate pack

DELETE zones/:zone_identifier/ssl/certificate_packs/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/ssl/certificate_packs/3822ff90-ea29-44df-9e55-21300bb9419b" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "3822ff90-ea29-44df-9e55-21300bb9419b"
  }
}

Certificate Packs error codes

Code	Description
1400	Missing required property in request
1401	Error while requesting from certificate service
1402	Error while requesting from certificate service
1403	Bad response certificate service
1404	Bad response certificate service
1405	Missing required certificate pack id for deletion
1406	Bad response certificate service
1407	Bad response certificate service
1408	ID is not a dedicated or advanced certificate.
1409	Error while requesting from certificate service
1410	Bad response certificate service
1411	ID is not a dedicated or advanced certificate.
1412	Missing required property in request
1413	You do not have sufficient entitlements to order the Dedicated Certificate. If you recently deleted a Dedicated Certificate it may still be pending removal. Please try again and contact your Customer Success Manager or Cloudflare Support for assistance if the issue persists.
1414	You must complete domain control validation (DCV) for all hostnames on the Dedicated Certificate before placing an order.

SSL/TLS Mode Recommendation

SSL/TLS Recommendation for a zone

ssl/tls-mode-recommendation

Object definition

View properties and constraints defined on the object

Show definition

ssl/tls-mode-recommendation-ssl/tls-recommendation

GET SSL/TLS Recommendation permission needed: #ssl:read
free
pro
business
enterprise

Retrieve the SSL/TLS Recommender's recommendation for a zone

GET zones/:zone_identifier/ssl/recommendation

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/ssl/recommendation" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"enabled":true}'

Response (example)

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

Total TLS

Total TLS will automatically issue an individual certificate for every proxied hostname in the zone.

total-tls

Object definition

View properties and constraints defined on the object

Show definition

total-tls-total-tls-settings-details

GET Total TLS Settings Details permission needed: #ssl:read
free
pro
business
enterprise

Get Total TLS Settings for a Zone.

GET zones/:zone_identifier/acm/total_tls

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/acm/total_tls" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "enabled": true,
    "certificate_authority": "google",
    "validity_days": 90,
    "status": "pending_enabled"
  }
}

total-tls-enable-or-disable-total-tls

POST Enable or Disable Total TLS permission needed: #ssl:read#ssl:edit
free
pro
business
enterprise

Set Total TLS Settings or disable the feature for a Zone.

POST zones/:zone_identifier/acm/total_tls

Required parameters

Name /type	Description /example	Constraints
enabled boolean	If enabled, Total TLS will order a hostname specific TLS certificate for any proxied A, AAAA, or CNAME record in your zone. `true`	valid values: (true,false)

Optional parameters

Name /type	Description /example	Constraints
certificate_authority string	The Certificate Authority that Total TLS certificates will be issued through. `"google"`	valid values: google, lets_encrypt

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/acm/total_tls" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"enabled":true,"certificate_authority":"google"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "enabled": true,
    "certificate_authority": "google",
    "validity_days": 90,
    "status": "pending_enabled"
  }
}

Origin CA

API to create Cloudflare-issued SSL certificates that can be installed on your origin server. Use your Origin CA Key as your User Service Key when calling these endpoints (see the section on request headers for details).

origin-ca

Object definition

View properties and constraints defined on the object

Show definition

origin-ca-list-certificates

GET List Certificates
free
pro
business
enterprise

List all existing Origin CA certificates for a given zone. Use your Origin CA 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": "328578533902268680212849205732770752308931942346",
      "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-----"
    }
  ]
}

origin-ca-create-certificate

POST Create Certificate
free
pro
business
enterprise

Create an Origin CA certificate. Use your Origin CA 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": "328578533902268680212849205732770752308931942346",
    "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-----"
  }
}

origin-ca-get-certificate

GET Get Certificate
free
pro
business
enterprise

Get an existing Origin CA certificate by its serial number. Use your Origin CA 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/328578533902268680212849205732770752308931942346" \
     -H "X-Auth-User-Service-Key: v1.0-e24fd090c02efcfecb4de8f4ff246fd5c75b48946fdf0ce26c59f91d0d90797b-cfa33fe60e8e34073c149323454383fc9005d25c9b4c502c2f063457ef65322eade065975001a0b4b4c591c5e1bd36a6e8f7e2d4fa8a9ec01c64c041e99530c2-07b9efe0acd78c82c8d9c690aacb8656d81c369246d7f996a205fe3c18e9254a"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "328578533902268680212849205732770752308931942346",
    "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-----"
  }
}

origin-ca-revoke-certificate

DELETE Revoke Certificate
free
pro
business
enterprise

Revoke an existing Origin CA certificate by its serial number. Use your Origin CA 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/328578533902268680212849205732770752308931942346" \
     -H "X-Auth-User-Service-Key: v1.0-e24fd090c02efcfecb4de8f4ff246fd5c75b48946fdf0ce26c59f91d0d90797b-cfa33fe60e8e34073c149323454383fc9005d25c9b4c502c2f063457ef65322eade065975001a0b4b4c591c5e1bd36a6e8f7e2d4fa8a9ec01c64c041e99530c2-07b9efe0acd78c82c8d9c690aacb8656d81c369246d7f996a205fe3c18e9254a"

Response (example)

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

Origin 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>

Zone-Level Authenticated Origin Pulls

Setup authenticated origin pulls for your zone.

zone-level-authenticated-origin-pulls

Object definition

View properties and constraints defined on the object

Show definition

zone-level-authenticated-origin-pulls-get-enablement-setting-for-zone

GET Get Enablement Setting for Zone permission needed: #ssl:read
free
pro
business
enterprise

Get whether zone-level authenticated origin pulls is enabled or not. It is false by default.

GET zones/:zone_identifier/origin_tls_client_auth/settings

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/origin_tls_client_auth/settings" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

zone-level-authenticated-origin-pulls-set-enablement-for-zone

PUT Set Enablement for Zone permission needed: #ssl:edit
free
pro
business
enterprise

Enable or disable zone-level authenticated origin pulls. 'enabled' should be set true either before/after the certificate is uploaded to see the certificate in use.

PUT zones/:zone_identifier/origin_tls_client_auth/settings

Required parameters

Name /type	Description /example	Constraints
enabled boolean	Indicates whether zone-level authenticated origin pulls is enabled `true`	valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/origin_tls_client_auth/settings" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"enabled":true}'

Response (example)

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

zone-level-authenticated-origin-pulls-upload-certificate

POST Upload Certificate permission needed: #ssl:edit
free
pro
business
enterprise

Upload your own certificate you want Cloudflare to use for edge-to-origin communication to override the shared certificate. Please note that it is important to keep only one certificate active. Also, make sure to enable zone-level authenticated origin pulls by making a PUT call to settings endpoint to see the uploaded certificate in use.

POST zones/:zone_identifier/origin_tls_client_auth

Required parameters

Name /type	Description /example	Constraints
certificate string	The zone's leaf 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 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"

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/origin_tls_client_auth" \
     -H "X-Auth-Email: user@example.com" \
     -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"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
    "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",
    "issuer": "GlobalSign",
    "signature": "SHA256WithRSA",
    "expires_on": "2100-01-01T05:20:00Z",
    "status": "active",
    "uploaded_on": "2019-10-28T18:11:23.37411Z"
  }
}

zone-level-authenticated-origin-pulls-list-certificates

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

GET zones/:zone_identifier/origin_tls_client_auth

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/origin_tls_client_auth" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
      "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",
      "issuer": "GlobalSign",
      "signature": "SHA256WithRSA",
      "expires_on": "2100-01-01T05:20:00Z",
      "status": "active",
      "uploaded_on": "2019-10-28T18:11:23.37411Z"
    }
  ]
}

zone-level-authenticated-origin-pulls-get-certificate-details

GET Get Certificate Details permission needed: #ssl:read
free
pro
business
enterprise

GET zones/:zone_identifier/origin_tls_client_auth/:identifier

cURL (example)

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

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
    "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",
    "issuer": "GlobalSign",
    "signature": "SHA256WithRSA",
    "expires_on": "2100-01-01T05:20:00Z",
    "status": "active",
    "uploaded_on": "2019-10-28T18:11:23.37411Z"
  }
}

zone-level-authenticated-origin-pulls-delete-certificate

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

DELETE zones/:zone_identifier/origin_tls_client_auth/:identifier

cURL (example)

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

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
    "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",
    "issuer": "GlobalSign",
    "signature": "SHA256WithRSA",
    "expires_on": "2100-01-01T05:20:00Z",
    "status": "active",
    "uploaded_on": "2019-10-28T18:11:23.37411Z"
  }
}

Per-hostname Authenticated Origin Pull

Setup a client certficate per hostname to be sent in a request to Origin

per-hostname-authenticated-origin-pull

Object definition

View properties and constraints defined on the object

Show definition

per-hostname-authenticated-origin-pull-upload-a-hostname-client-certificate

POST Upload a Hostname Client Certificate permission needed: #ssl:edit
free
pro
business
enterprise

Upload a certificate to be used for client authentication on a hostname. 10 hostname certificates per zone are allowed

POST zones/:zone_identifier/origin_tls_client_auth/hostnames/certificates

Required parameters

Name /type	Description /example	Constraints
certificate string	The hostname 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 string	The hostname certificate'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"

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/origin_tls_client_auth/hostnames/certificates" \
     -H "X-Auth-Email: user@example.com" \
     -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"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
    "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",
    "issuer": "GlobalSign",
    "signature": "SHA256WithRSA",
    "serial_number": "6743787633689793699141714808227354901",
    "expires_on": "2100-01-01T05:20:00Z",
    "status": "active",
    "uploaded_on": "2019-10-28T18:11:23.37411Z"
  }
}

per-hostname-authenticated-origin-pull-list-certificates

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

GET zones/:zone_identifier/origin_tls_client_auth/hostnames/certificates

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/origin_tls_client_auth/hostnames/certificates" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "hostname": "app.example.com",
      "cert_id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
      "enabled": true,
      "status": "active",
      "created_at": "2100-01-01T05:20:00Z",
      "updated_at": "2100-01-01T05:20:00Z",
      "cert_status": "active",
      "issuer": "GlobalSign",
      "signature": "SHA256WithRSA",
      "serial_number": "6743787633689793699141714808227354901",
      "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",
      "cert_uploaded_on": "2019-10-28T18:11:23.37411Z",
      "cert_updated_at": "2100-01-01T05:20:00Z",
      "expires_on": "2100-01-01T05:20:00Z"
    }
  ]
}

per-hostname-authenticated-origin-pull-get-the-hostname-client-certificate

GET Get the Hostname Client Certificate permission needed: #ssl:read
free
pro
business
enterprise

Get the certificate by ID to be used for client authentication on a hostname

GET zones/:zone_identifier/origin_tls_client_auth/hostnames/certificates/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/origin_tls_client_auth/hostnames/certificates/2458ce5a-0c35-4c7f-82c7-8e9487d3ff60" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
    "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",
    "issuer": "GlobalSign",
    "signature": "SHA256WithRSA",
    "serial_number": "6743787633689793699141714808227354901",
    "expires_on": "2100-01-01T05:20:00Z",
    "status": "active",
    "uploaded_on": "2019-10-28T18:11:23.37411Z"
  }
}

per-hostname-authenticated-origin-pull-delete-hostname-client-certificate

DELETE Delete Hostname Client Certificate permission needed: #ssl:edit
free
pro
business
enterprise

DELETE zones/:zone_identifier/origin_tls_client_auth/hostnames/certificates/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/origin_tls_client_auth/hostnames/certificates/2458ce5a-0c35-4c7f-82c7-8e9487d3ff60" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
    "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",
    "issuer": "GlobalSign",
    "signature": "SHA256WithRSA",
    "serial_number": "6743787633689793699141714808227354901",
    "expires_on": "2100-01-01T05:20:00Z",
    "status": "active",
    "uploaded_on": "2019-10-28T18:11:23.37411Z"
  }
}

per-hostname-authenticated-origin-pull-enable-or-disable-a-hostname-for-client-authentication

PUT Enable or Disable a Hostname for Client Authentication permission needed: #ssl:edit
free
pro
business
enterprise

Associate a hostname to a certificate and enable, disable or invalidate the association. If disabled, client certificate will not be sent to the hostname even if activated at the zone level. 100 maximum associations on a single certificate are allowed. Note: Use a null value for parameter enabled to invalidate the association

PUT zones/:zone_identifier/origin_tls_client_auth/hostnames

Required parameters

Name /type	Description /example	Constraints
config array	`[ { "hostname": "app.example.com", "cert_id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60", "enabled": true } ]` An array with items in the following form: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/origin_tls_client_auth/hostnames" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"config":[{"hostname":"app.example.com","cert_id":"2458ce5a-0c35-4c7f-82c7-8e9487d3ff60","enabled":true}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "hostname": "app.example.com",
      "cert_id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
      "enabled": true,
      "status": "active",
      "created_at": "2100-01-01T05:20:00Z",
      "updated_at": "2100-01-01T05:20:00Z",
      "cert_status": "active",
      "issuer": "GlobalSign",
      "signature": "SHA256WithRSA",
      "serial_number": "6743787633689793699141714808227354901",
      "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",
      "cert_uploaded_on": "2019-10-28T18:11:23.37411Z",
      "cert_updated_at": "2100-01-01T05:20:00Z",
      "expires_on": "2100-01-01T05:20:00Z"
    }
  ]
}

per-hostname-authenticated-origin-pull-get-the-hostname-status-for-client-authentication

GET Get the Hostname Status for Client Authentication permission needed: #ssl:read
free
pro
business
enterprise

GET zones/:zone_identifier/origin_tls_client_auth/hostnames/:hostname

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/origin_tls_client_auth/hostnames/app.example.com" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "hostname": "app.example.com",
    "cert_id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
    "enabled": true,
    "status": "active",
    "created_at": "2100-01-01T05:20:00Z",
    "updated_at": "2100-01-01T05:20:00Z",
    "cert_status": "active",
    "issuer": "GlobalSign",
    "signature": "SHA256WithRSA",
    "serial_number": "6743787633689793699141714808227354901",
    "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",
    "cert_uploaded_on": "2019-10-28T18:11:23.37411Z",
    "cert_updated_at": "2100-01-01T05:20:00Z",
    "expires_on": "2100-01-01T05:20:00Z"
  }
}

Email Routing destination addresses

Create different destination addresses to route your emails to.

email-routing-destination-addresses

Object definition

View properties and constraints defined on the object

Show definition

email-routing-destination-addresses-list-destination-addresses

GET List destination addresses permission needed: com.cloudflare.api.account.email.routing.address.list
free
pro
business
enterprise

Lists existing destination addresses.

GET accounts/:account_identifier/email/routing/addresses

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	Sorts results in an ascending or descending order. `"asc"`	default value: asc valid values: asc, desc
verified boolean	Filter by verified destination addresses. `true`	default value: true valid values: true, false

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/email/routing/addresses?page=1&per_page=20&direction=asc&verified=true" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "tag": "ea95132c15732412d22c1476fa83f27a",
      "email": "user@example.com",
      "verified": "2014-01-02T02:20:00Z",
      "created": "2014-01-02T02:20:00Z",
      "modified": "2014-01-02T02:20:00Z"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 1
  }
}

email-routing-destination-addresses-create-a-destination-address

POST Create a destination address permission needed: com.cloudflare.api.account.email.routing.address.create
free
pro
business
enterprise

Create a destination address to forward your emails to. Destination addresses need to be verified before they can be used.

POST accounts/:account_identifier/email/routing/addresses

Required parameters

Name /type	Description /example	Constraints
email string	The contact email address of the user. `"user@example.com"`	max length: 90

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/email/routing/addresses" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"email":"user@example.com"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "tag": "ea95132c15732412d22c1476fa83f27a",
    "email": "user@example.com",
    "verified": "2014-01-02T02:20:00Z",
    "created": "2014-01-02T02:20:00Z",
    "modified": "2014-01-02T02:20:00Z"
  }
}

email-routing-destination-addresses-get-a-destination-address

GET Get a destination address permission needed: com.cloudflare.api.account.email.routing.address.read
free
pro
business
enterprise

Gets information for a specific destination email already created.

GET accounts/:account_identifier/email/routing/addresses/:destination_address_identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/email/routing/addresses/ea95132c15732412d22c1476fa83f27a" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "tag": "ea95132c15732412d22c1476fa83f27a",
    "email": "user@example.com",
    "verified": "2014-01-02T02:20:00Z",
    "created": "2014-01-02T02:20:00Z",
    "modified": "2014-01-02T02:20:00Z"
  }
}

email-routing-destination-addresses-delete-destination-address

Delete Delete destination address permission needed: com.cloudflare.api.account.email.routing.address.delete
free
pro
business
enterprise

Deletes a specific destination address.

Delete accounts/:account_identifier/email/routing/addresses/:destination_address_identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/email/routing/addresses/ea95132c15732412d22c1476fa83f27a" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "tag": "ea95132c15732412d22c1476fa83f27a",
    "email": "user@example.com",
    "verified": "2014-01-02T02:20:00Z",
    "created": "2014-01-02T02:20:00Z",
    "modified": "2014-01-02T02:20:00Z"
  }
}

Email Routing routing rules

Create rules to route emails to your preferred inbox.

email-routing-routing-rules

Object definition

View properties and constraints defined on the object

Show definition

email-routing-routing-rules-list-routing-rules

GET List routing rules permission needed: com.cloudflare.api.account.zone.email.routing.rule.list
free
pro
business
enterprise

Lists existing routing rules.

GET zones/:zone_identifier/email/routing/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. `20`	default value: 20 min value:5 max value:50
enabled boolean	Filter by enabled routing rules. `true`	valid values: true, false

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/email/routing/rules?page=1&per_page=20&enabled=true" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "tag": "a7e6fb77503c41d8a7f3113c6918f10c",
      "name": "Send to user@example.net rule.",
      "priority": 0,
      "enabled": true,
      "matchers": [
        {
          "type": "literal",
          "field": "to",
          "value": "test@example.com"
        }
      ],
      "actions": [
        {
          "type": "forward",
          "value": [
            "destinationaddress@example.net"
          ]
        }
      ]
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 1
  }
}

email-routing-routing-rules-create-routing-rule

POST Create routing rule permission needed: com.cloudflare.api.account.zone.email.routing.rule.create
free
pro
business
enterprise

Rules consist of a set of criteria for matching emails (such as an email being sent to a specific custom email address) plus a set of actions to take on the email (like forwarding it to a specific destination address).

POST zones/:zone_identifier/email/routing/rules

Required parameters

Name /type	Description /example	Constraints
matchers array	Matching patterns to forward to your actions. `[ { "type": "literal", "field": "to", "value": "test@example.com" } ]` An array with items in the following form: Show definition »
actions array	List actions patterns. `[ { "type": "forward", "value": [ "destinationaddress@example.net" ] } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
name string	Routing rule name. `"Send to user@example.net rule."`	max length: 256
enabled boolean	Routing rule status. `true`	default value: true valid values: true, false
priority number	Priority of the routing rule. `0`	default value: 0 min value:0

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/email/routing/rules" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Send to user@example.net rule.","enabled":true,"priority":0,"matchers":[{"type":"literal","field":"to","value":"test@example.com"}],"actions":[{"type":"forward","value":["destinationaddress@example.net"]}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "tag": "a7e6fb77503c41d8a7f3113c6918f10c",
    "name": "Send to user@example.net rule.",
    "priority": 0,
    "enabled": true,
    "matchers": [
      {
        "type": "literal",
        "field": "to",
        "value": "test@example.com"
      }
    ],
    "actions": [
      {
        "type": "forward",
        "value": [
          "destinationaddress@example.net"
        ]
      }
    ]
  }
}

email-routing-routing-rules-get-routing-rule

GET Get routing rule permission needed: com.cloudflare.api.account.zone.email.routing.rule.read
free
pro
business
enterprise

Get information for a specific routing rule already created.

GET zones/:zone_identifier/email/routing/rules/:rule_identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/email/routing/rules/a7e6fb77503c41d8a7f3113c6918f10c" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "tag": "a7e6fb77503c41d8a7f3113c6918f10c",
    "name": "Send to user@example.net rule.",
    "priority": 0,
    "enabled": true,
    "matchers": [
      {
        "type": "literal",
        "field": "to",
        "value": "test@example.com"
      }
    ],
    "actions": [
      {
        "type": "forward",
        "value": [
          "destinationaddress@example.net"
        ]
      }
    ]
  }
}

email-routing-routing-rules-update-routing-rule

PUT Update routing rule permission needed: com.cloudflare.api.account.zone.email.routing.rule.update
free
pro
business
enterprise

Update actions and matches, or enable/disable specific routing rules

PUT zones/:zone_identifier/email/routing/rules/:rule_identifier

Required parameters

Name /type	Description /example	Constraints
matchers array	Matching patterns to forward to your actions. `[ { "type": "literal", "field": "to", "value": "test@example.com" } ]` An array with items in the following form: Show definition »
actions array	List actions patterns. `[ { "type": "forward", "value": [ "destinationaddress@example.net" ] } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
name string	Routing rule name. `"Send to user@example.net rule."`	max length: 256
enabled boolean	Routing rule status. `true`	default value: true valid values: true, false
priority number	Priority of the routing rule. `0`	default value: 0 min value:0

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/email/routing/rules/a7e6fb77503c41d8a7f3113c6918f10c" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Send to user@example.net rule.","enabled":true,"priority":0,"matchers":[{"type":"literal","field":"to","value":"test@example.com"}],"actions":[{"type":"forward","value":["destinationaddress@example.net"]}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "tag": "a7e6fb77503c41d8a7f3113c6918f10c",
    "name": "Send to user@example.net rule.",
    "priority": 0,
    "enabled": true,
    "matchers": [
      {
        "type": "literal",
        "field": "to",
        "value": "test@example.com"
      }
    ],
    "actions": [
      {
        "type": "forward",
        "value": [
          "destinationaddress@example.net"
        ]
      }
    ]
  }
}

email-routing-routing-rules-delete-routing-rule

DELETE Delete routing rule permission needed: com.cloudflare.api.account.zone.email.routing.rule.delete
free
pro
business
enterprise

Delete a specific routing rule.

DELETE zones/:zone_identifier/email/routing/rules/:rule_identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/email/routing/rules/a7e6fb77503c41d8a7f3113c6918f10c" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "tag": "a7e6fb77503c41d8a7f3113c6918f10c",
    "name": "Send to user@example.net rule.",
    "priority": 0,
    "enabled": true,
    "matchers": [
      {
        "type": "literal",
        "field": "to",
        "value": "test@example.com"
      }
    ],
    "actions": [
      {
        "type": "forward",
        "value": [
          "destinationaddress@example.net"
        ]
      }
    ]
  }
}

email-routing-routing-rules-get-catch-all-rule

GET Get catch-all rule permission needed: com.cloudflare.api.account.zone.email.routing.rule.read
free
pro
business
enterprise

Get information on the default catch-all routing rule.

GET zones/:zone_identifier/email/routing/rules/catch_all

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/email/routing/rules/catch_all" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "tag": "a7e6fb77503c41d8a7f3113c6918f10c",
  "name": "Send to user@example.net rule.",
  "enabled": true,
  "matchers": [
    {
      "type": "all"
    }
  ],
  "actions": [
    {
      "type": "forward",
      "value": [
        "destinationaddress@example.net"
      ]
    }
  ]
}

email-routing-routing-rules-update-catch-all-rule

PUT Update catch-all rule permission needed: com.cloudflare.api.account.zone.email.routing.rule.update
free
pro
business
enterprise

Enable or disable catch-all routing rule, or change action to forward to specific destination address.

PUT zones/:zone_identifier/email/routing/rules/catch_all

Required parameters

Name /type	Description /example	Constraints
matchers array	List of matchers for the catch-all routing rule. `[ { "type": "all" } ]` An array with items in the following form: Show definition »
actions array	List actions for the catch-all routing rule. `[ { "type": "forward", "value": [ "destinationaddress@example.net" ] } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
name string	Routing rule name. `"Send to user@example.net rule."`	max length: 256
enabled boolean	Routing rule status. `true`	default value: true valid values: true, false

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/email/routing/rules/catch_all" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Send to user@example.net rule.","enabled":true,"matchers":[{"type":"all"}],"actions":[{"type":"forward","value":["destinationaddress@example.net"]}]}'

Response (example)

{
  "tag": "a7e6fb77503c41d8a7f3113c6918f10c",
  "name": "Send to user@example.net rule.",
  "enabled": true,
  "matchers": [
    {
      "type": "all"
    }
  ],
  "actions": [
    {
      "type": "forward",
      "value": [
        "destinationaddress@example.net"
      ]
    }
  ]
}

Email Routing settings

Cloudflare Email Routing settings.

email-routing-settings

Object definition

View properties and constraints defined on the object

Show definition

email-routing-settings-get-email-routing-settings

GET Get Email Routing settings permission needed: com.cloudflare.api.account.zone.email.routing.config.read
free
pro
business
enterprise

Get information about the settings for your Email Routing zone.

GET zones/:zone_identifier/email/routing

cURL (example)

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

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "tag": "75610dab9e69410a82cf7e400a09ecec",
    "name": "example.net",
    "enabled": true,
    "created": "2014-01-02T02:20:00Z",
    "modified": "2014-01-02T02:20:00Z",
    "skip_wizard": true,
    "status": "read"
  }
}

email-routing-settings-enable-email-routing

POST Enable Email Routing permission needed: com.cloudflare.api.account.zone.email.routing.config.update
free
pro
business
enterprise

Enable you Email Routing zone. Add and lock the necessary MX and SPF records.

POST zones/:zone_identifier/email/routing/enable

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/email/routing/enable" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "tag": "75610dab9e69410a82cf7e400a09ecec",
    "name": "example.net",
    "enabled": true,
    "created": "2014-01-02T02:20:00Z",
    "modified": "2014-01-02T02:20:00Z",
    "skip_wizard": true,
    "status": "read"
  }
}

email-routing-settings-disable-email-routing

POST Disable Email Routing permission needed: com.cloudflare.api.account.zone.email.routing.config.update
free
pro
business
enterprise

Disable your Email Routing zone. Also removes additional MX records previously required for Email Routing to work.

POST zones/:zone_identifier/email/routing/disable

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/email/routing/disable" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "tag": "75610dab9e69410a82cf7e400a09ecec",
    "name": "example.net",
    "enabled": true,
    "created": "2014-01-02T02:20:00Z",
    "modified": "2014-01-02T02:20:00Z",
    "skip_wizard": true,
    "status": "read"
  }
}

email-routing-settings-email-routing---dns-settings

GET Email Routing - DNS settings permission needed: com.cloudflare.api.account.zone.email.routing.config.read
free
pro
business
enterprise

Show the DNS records needed to configure your Email Routing zone.

GET zones/:zone_identifier/email/routing/dns

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/email/routing/dns" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "type": "A",
      "name": "example.com",
      "content": "127.0.0.1",
      "ttl": 3600,
      "priority": 10
    }
  ]
}

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

stream-videos-upload-videos-from-a-url

POST Upload videos from a URL

Uploads a video to Stream from a provided URL.

POST accounts/:account_identifier/stream/copy

Required parameters

Name /type	Description /example	Constraints
url string (uri)	A video's URL. The server must be publicly routable and support `HTTP HEAD` requests and `HTTP GET` range requests. The server should respond to `HTTP HEAD` requests with a `content-range` header that includes the size of the file. `"https://example.com/myvideo.mp4"`

Optional parameters

Name /type	Description /example	Constraints
creator string	A user-defined identifier for the media creator. `"creator-id_abcde12345"`	max length: 64
thumbnailTimestampPct number	The timestamp for a thumbnail image calculated as a percentage value of the video's duration. To convert from a second-wise timestamp to a percentage, divide the desired timestamp by the total duration of the video. If this value is not set, the default thumbnail image is taken from 0s of the video. `0.529241`	default value: 0 min value:0 max value:1
allowedOrigins array	Lists the origins allowed to display the video. Enter allowed origin domains in an array and use `*` for wildcard subdomains. Empty arrays allow the video to be viewed on any origin. `[ "example.com" ]` An array with items in the following form: Show definition »
requireSignedURLs boolean	Indicates whether the video can be a accessed using the UID. When set to `true`, a signed token must be generated with a signing key to view the video. `true`	default value: false valid values: (true,false) read only
watermark object	`{ "uid": "ea95132c15732412d22c1476fa83f27a" }` An object with the following properties: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/stream/copy" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"url":"https://example.com/myvideo.mp4","creator":"creator-id_abcde12345","thumbnailTimestampPct":0.529241,"allowedOrigins":["example.com"],"requireSignedURLs":true,"watermark":{"uid":"ea95132c15732412d22c1476fa83f27a"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "allowedOrigins": [
      "example.com"
    ],
    "created": "2014-01-02T02:20:00Z",
    "duration": 300,
    "input": {
      "height": 1080,
      "width": 1920
    },
    "maxDurationSeconds": 300,
    "meta": {},
    "modified": "2014-01-02T02:20:00Z",
    "uploadExpiry": "2014-01-02T02:20:00Z",
    "playback": {
      "hls": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/manifest/video.m3u8",
      "dash": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/manifest/video.mpd"
    },
    "preview": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/watch",
    "readyToStream": true,
    "requireSignedURLs": true,
    "size": 4190963,
    "status": {
      "state": "inprogress",
      "pctComplete": 51,
      "errorReasonCode": "ERR_NON_VIDEO",
      "errorReasonText": "The file was not recognized as a valid video file."
    },
    "thumbnail": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/thumbnails/thumbnail.jpg",
    "thumbnailTimestampPct": 0.529241,
    "uid": "ea95132c15732412d22c1476fa83f27a",
    "creator": "creator-id_abcde12345",
    "liveInput": "fc0a8dc887b16759bfd9ad922230a014",
    "uploaded": "2014-01-02T02:20:00Z",
    "watermark": {
      "uid": "ea95132c15732412d22c1476fa83f27a",
      "size": 29472,
      "height": 600,
      "width": 400,
      "created": "2014-01-02T02:20:00Z",
      "downloadedFrom": "https://company.com/logo.png",
      "name": "Marketing Videos",
      "opacity": 0.75,
      "padding": 0.1,
      "scale": 0.1,
      "position": "center"
    },
    "nft": {
      "contract": "0x57f1887a8bf19b14fc0d912b9b2acc9af147ea85",
      "token": 5
    }
  }
}

stream-videos-upload-videos-via-http-requests

POST Upload videos via HTTP requests

Uploads a video up to 200MB using a single HTTP POST (multipart/form-data) request.

POST accounts/:account_identifier/stream

Required parameters

Name /type	Description /example	Constraints
file string	The video file to upload. `"@/Users/kyle/Desktop/skiing.mp4"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/stream" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     --form 'file=@/Users/kyle/Desktop/skiing.mp4'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "allowedOrigins": [
        "example.com"
      ],
      "created": "2014-01-02T02:20:00Z",
      "duration": 300,
      "input": {
        "height": 1080,
        "width": 1920
      },
      "maxDurationSeconds": 300,
      "meta": {},
      "modified": "2014-01-02T02:20:00Z",
      "uploadExpiry": "2014-01-02T02:20:00Z",
      "playback": {
        "hls": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/manifest/video.m3u8",
        "dash": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/manifest/video.mpd"
      },
      "preview": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/watch",
      "readyToStream": true,
      "requireSignedURLs": true,
      "size": 4190963,
      "status": {
        "state": "inprogress",
        "pctComplete": 51,
        "errorReasonCode": "ERR_NON_VIDEO",
        "errorReasonText": "The file was not recognized as a valid video file."
      },
      "thumbnail": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/thumbnails/thumbnail.jpg",
      "thumbnailTimestampPct": 0.529241,
      "uid": "ea95132c15732412d22c1476fa83f27a",
      "creator": "creator-id_abcde12345",
      "liveInput": "fc0a8dc887b16759bfd9ad922230a014",
      "uploaded": "2014-01-02T02:20:00Z",
      "watermark": null,
      "nft": {
        "contract": "0x57f1887a8bf19b14fc0d912b9b2acc9af147ea85",
        "token": 5
      }
    }
  ]
}

stream-videos-upload-videos-via-direct-upload-urls

POST Upload videos via direct upload URLs

Creates a direct upload that allows video uploads without an API key.

POST accounts/:account_identifier/stream/direct_upload

Required parameters

Name /type	Description /example	Constraints
maxDurationSeconds integer	Calculates the amount of time a video occupies before the video is uploaded. Direct uploads occupy minutes of videos on your Stream account until they are expired. After upload, the upload duration is used instead. If a video longer than the value is uploaded, the video results in an error. `300`	min value:1 max value:21600

Optional parameters

Name /type	Description /example	Constraints
expiry string (date-time)	The date and time after upload when videos will not be accepted. `"2021-01-02T02:20:00Z"`	default value: Now + 30 minutes
creator string	A user-defined identifier for the media creator. `"creator-id_abcde12345"`	max length: 64
thumbnailTimestampPct number	The timestamp for a thumbnail image calculated as a percentage value of the video's duration. To convert from a second-wise timestamp to a percentage, divide the desired timestamp by the total duration of the video. If this value is not set, the default thumbnail image is taken from 0s of the video. `0.529241`	default value: 0 min value:0 max value:1
allowedOrigins array	Lists the origins allowed to display the video. Enter allowed origin domains in an array and use `*` for wildcard subdomains. Empty arrays allow the video to be viewed on any origin. `[ "example.com" ]` An array with items in the following form: Show definition »
requireSignedURLs boolean	Indicates whether the video can be a accessed using the UID. When set to `true`, a signed token must be generated with a signing key to view the video. `true`	default value: false valid values: (true,false) read only
watermark object	`{ "uid": "ea95132c15732412d22c1476fa83f27a" }` An object with the following properties: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/stream/direct_upload" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"maxDurationSeconds":300,"expiry":"2021-01-02T02:20:00Z","creator":"creator-id_abcde12345","thumbnailTimestampPct":0.529241,"allowedOrigins":["example.com"],"requireSignedURLs":true,"watermark":{"uid":"ea95132c15732412d22c1476fa83f27a"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "uploadURL": "www.example.com/samplepath",
    "uid": "ea95132c15732412d22c1476fa83f27a",
    "watermark": {
      "uid": "ea95132c15732412d22c1476fa83f27a",
      "size": 29472,
      "height": 600,
      "width": 400,
      "created": "2014-01-02T02:20:00Z",
      "downloadedFrom": "https://company.com/logo.png",
      "name": "Marketing Videos",
      "opacity": 0.75,
      "padding": 0.1,
      "scale": 0.1,
      "position": "center"
    }
  }
}

GET List videos

Lists up to 1000 videos from a single request. For a specific range, refer to the optional parameters.

GET accounts/:account_identifier/stream

Optional parameters

Name /type	Description /example	Constraints
after string (date-time)	Lists videos created after the specified date and time. `"2014-01-02T02:20:00Z"`
before string (date-time)	Lists videos created before the specified date and time. `"2014-01-02T02:20:00Z"`
creator string	Filters by the media creator's user-defined identifier. `"creator-id_abcde12345"`	max length: 64
include_counts boolean	Lists stats in the response that include the number of videos in the response range and the total number of videos available. `false`	default value: false valid values: (true,false)
search string	Searches over the `name` key in the `meta` field. This field can be set with the upload request of after the request. `"puppy.mp4"`
limit integer	The number of videos to include in the response.	min value:0 max value:1000
asc boolean	Lists videos in ascending order of creation. `false`	default value: false valid values: (true,false)
status string	Filters videos by status. `"downloading,queued,inprogress,ready,error"`	default value: downloading,queued,inprogress,ready,error valid values: pendingupload, downloading, queued, inprogress, ready, error

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/stream?after=2014-01-02T02:20:00Z&before=2014-01-02T02:20:00Z&creator=creator-id_abcde12345&include_counts=false&search=puppy.mp4&limit=undefined&asc=false&status=downloading,queued,inprogress,ready,error" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "allowedOrigins": [
        "example.com"
      ],
      "created": "2014-01-02T02:20:00Z",
      "duration": 300,
      "input": {
        "height": 1080,
        "width": 1920
      },
      "maxDurationSeconds": 300,
      "meta": {},
      "modified": "2014-01-02T02:20:00Z",
      "uploadExpiry": "2014-01-02T02:20:00Z",
      "playback": {
        "hls": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/manifest/video.m3u8",
        "dash": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/manifest/video.mpd"
      },
      "preview": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/watch",
      "readyToStream": true,
      "requireSignedURLs": true,
      "size": 4190963,
      "status": {
        "state": "inprogress",
        "pctComplete": 51,
        "errorReasonCode": "ERR_NON_VIDEO",
        "errorReasonText": "The file was not recognized as a valid video file."
      },
      "thumbnail": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/thumbnails/thumbnail.jpg",
      "thumbnailTimestampPct": 0.529241,
      "uid": "ea95132c15732412d22c1476fa83f27a",
      "creator": "creator-id_abcde12345",
      "liveInput": "fc0a8dc887b16759bfd9ad922230a014",
      "uploaded": "2014-01-02T02:20:00Z",
      "watermark": {
        "uid": "ea95132c15732412d22c1476fa83f27a",
        "size": 29472,
        "height": 600,
        "width": 400,
        "created": "2014-01-02T02:20:00Z",
        "downloadedFrom": "https://company.com/logo.png",
        "name": "Marketing Videos",
        "opacity": 0.75,
        "padding": 0.1,
        "scale": 0.1,
        "position": "center"
      },
      "nft": {
        "contract": "0x57f1887a8bf19b14fc0d912b9b2acc9af147ea85",
        "token": 5
      }
    }
  ],
  "total": "35586",
  "range": "1000"
}

stream-videos-initiate-video-uploads-using-tus

POST Initiate video uploads using TUS

Initiates a video upload using the TUS protocol. On success, the server responds with a status code 201 (created) and includes a location header to indicate where the content should be uploaded. Refer to https://tus.io for protocol details.

POST accounts/:account_identifier/stream

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/stream" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Tus-Resumable: 1.0.0" \
     -H "Upload-Creator: creator-id_abcde12345" \
     -H "Upload-Length: 900000000"

Response (example)

stream-videos-retrieve-video-details

GET Retrieve video details

Fetches details for a single video.

GET accounts/:account_identifier/stream/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/stream/ea95132c15732412d22c1476fa83f27a" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "allowedOrigins": [
      "example.com"
    ],
    "created": "2014-01-02T02:20:00Z",
    "duration": 300,
    "input": {
      "height": 1080,
      "width": 1920
    },
    "maxDurationSeconds": 300,
    "meta": {},
    "modified": "2014-01-02T02:20:00Z",
    "uploadExpiry": "2014-01-02T02:20:00Z",
    "playback": {
      "hls": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/manifest/video.m3u8",
      "dash": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/manifest/video.mpd"
    },
    "preview": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/watch",
    "readyToStream": true,
    "requireSignedURLs": true,
    "size": 4190963,
    "status": {
      "state": "inprogress",
      "pctComplete": 51,
      "errorReasonCode": "ERR_NON_VIDEO",
      "errorReasonText": "The file was not recognized as a valid video file."
    },
    "thumbnail": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/thumbnails/thumbnail.jpg",
    "thumbnailTimestampPct": 0.529241,
    "uid": "ea95132c15732412d22c1476fa83f27a",
    "creator": "creator-id_abcde12345",
    "liveInput": "fc0a8dc887b16759bfd9ad922230a014",
    "uploaded": "2014-01-02T02:20:00Z",
    "watermark": {
      "uid": "ea95132c15732412d22c1476fa83f27a",
      "size": 29472,
      "height": 600,
      "width": 400,
      "created": "2014-01-02T02:20:00Z",
      "downloadedFrom": "https://company.com/logo.png",
      "name": "Marketing Videos",
      "opacity": 0.75,
      "padding": 0.1,
      "scale": 0.1,
      "position": "center"
    },
    "nft": {
      "contract": "0x57f1887a8bf19b14fc0d912b9b2acc9af147ea85",
      "token": 5
    }
  }
}

stream-videos-retreieve-embed-code-html

GET Retreieve embed Code HTML

Fetches an HTML code snippet to embed a video in a web page delivered through Cloudflare. On success, returns an HTML fragment for use on web pages to display a video. On failure, returns a JSON response body.

GET accounts/:account_identifier/stream/:identifier/embed

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/stream/ea95132c15732412d22c1476fa83f27a/embed" \
     -H "X-Auth-Email: user@example.com" \
     -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-delete-video

DELETE Delete video

Deletes a video and its copies from Cloudflare Stream.

DELETE accounts/:account_identifier/stream/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/stream/ea95132c15732412d22c1476fa83f27a" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

stream-videos-associate-videos-to-nfts

POST Associate videos to NFTs

Asssociates videos with a token ID and contract address to transfer admin rights on a video. If a change in ownership of the ERC-721 token happens on the Ethereum blockchain, the new token owner can claim control of the video.

POST accounts/:account_identifier/stream/:identifier

Optional parameters

Name /type	Description /example	Constraints
contract string	The ERC-721 compatible contract address. `"0x57f1887a8bf19b14fc0d912b9b2acc9af147ea85"`	min length: 42 max length: 42 read only
token integer	The token ID for the NFT. `5`	read only

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/stream/ea95132c15732412d22c1476fa83f27a" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"contract":"0x57f1887a8bf19b14fc0d912b9b2acc9af147ea85","token":5}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "allowedOrigins": [
        "example.com"
      ],
      "created": "2014-01-02T02:20:00Z",
      "duration": 300,
      "input": {
        "height": 1080,
        "width": 1920
      },
      "maxDurationSeconds": 300,
      "meta": {},
      "modified": "2014-01-02T02:20:00Z",
      "uploadExpiry": "2014-01-02T02:20:00Z",
      "playback": {
        "hls": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/manifest/video.m3u8",
        "dash": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/manifest/video.mpd"
      },
      "preview": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/watch",
      "readyToStream": true,
      "requireSignedURLs": true,
      "size": 4190963,
      "status": {
        "state": "inprogress",
        "pctComplete": 51,
        "errorReasonCode": "ERR_NON_VIDEO",
        "errorReasonText": "The file was not recognized as a valid video file."
      },
      "thumbnail": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/thumbnails/thumbnail.jpg",
      "thumbnailTimestampPct": 0.529241,
      "uid": "ea95132c15732412d22c1476fa83f27a",
      "creator": "creator-id_abcde12345",
      "liveInput": "fc0a8dc887b16759bfd9ad922230a014",
      "uploaded": "2014-01-02T02:20:00Z",
      "watermark": {
        "uid": "ea95132c15732412d22c1476fa83f27a",
        "size": 29472,
        "height": 600,
        "width": 400,
        "created": "2014-01-02T02:20:00Z",
        "downloadedFrom": "https://company.com/logo.png",
        "name": "Marketing Videos",
        "opacity": 0.75,
        "padding": 0.1,
        "scale": 0.1,
        "position": "center"
      },
      "nft": {
        "contract": "0x57f1887a8bf19b14fc0d912b9b2acc9af147ea85",
        "token": 5
      }
    }
  ],
  "total": "35586",
  "range": "1000"
}

stream-videos-create-signed-url-tokens-for-videso

POST Create signed URL tokens for videso

Creates a signed URL token for a video. If a body is not provided in the request, a token is created with default values.

POST accounts/:account_identifier/stream/:identifier/token

Optional parameters

Name /type	Description /example	Constraints
id string	The optional ID of a Stream signing key. If present, the `pem` field is also required. `"ab0d4ef71g4425f8dcba9041231813000"`	read only
pem string	The optional base64 encoded private key in PEM format associated with a Stream signing key. If present, the `id` field is also required. "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFcEFJQkFBS0NBUUVBc284dnBvOFpEWXRkOUgzbWlPaW1qYXAzVXlVM0oyZ3kwTUYvN1R4blJuRnkwRHpDCkxqUk9naFZsQ0hPQmxsd3NVaE9GU0lyYnN4K05tUTdBeS90TFpXSGxuVGF3UWJ5WGZGOStJeDhVSnNlSHBGV1oKNVF5Z1JYd2liSjh1MVVsZ2xlcmZHMkpueldjVXpZTzEySktZN3doSkw1ajROMWgxZFJNUXQ5Q1pkZFlCQWRzOQpCdk02cjRFMDcxQkhQekhWeDMrUTI1VWtubGdUNXIwS3FiM1E1Y0dlTlBXY1JreW1ybkJEWWR0OXR4eFFMb1dPCllzNXdsMnVYWFVYL0VGcDMwajU0Nmp6czllWExLYlNDbjJjTDZFVE96Y2x3aG9DRGx2a2VQT05rUE9LMDVKNUMKTm1TdFdhMG9hV1VGRzM0MFl3cVVrWGt4OU9tNndXd1JldU1uU1FJREFRQUJBb0lCQUFJOHo1ck5kOEdtOGJBMgo1S3pxQjI1R2lOVENwbUNJeW53NXRJWHZTQmNHcEdydUcvdlN2WG9kVlFVSVY0TWdHQkVXUEFrVzdsNWVBcHI4CnA1ZFd5SkRXYTNkdklFSE9vSEpYU3dBYksxZzZEMTNVa2NkZ1EyRGpoNVhuWDhHZCtBY2c2SmRTQWgxOWtYSHEKMk54RUtBVDB6Ri83a1g2MkRkREFBcWxmQkpGSXJodVIvZUdEVWh4L2piTTRhQ2JCcFdiM0pnRE9OYm5tS1ZoMwpxS2ZwZmRZZENZU1lzWUxrNTlxRDF2VFNwUVFUQ0VadW9VKzNzRVNhdkJzaUs1bU0vTzY5ZkRMRXNURG1MeTVQCmhEK3BMQXI0SlhNNjFwRGVBS0l3cUVqWWJybXlDRHRXTUdJNnZzZ0E1eXQzUUJaME9vV2w5QUkwdWxoZ3p4dXQKZ2ZFNTRRRUNnWUVBN0F3a0lhVEEzYmQ4Nk9jSVZnNFlrWGk1cm5aNDdsM1k4V24zcjIzUmVISXhLdkllRUtSbgp5bUlFNDFtRVBBSmlGWFpLK1VPTXdkeS9EcnFJUithT1JiT2NiV01jWUg2QzgvbG1wdVJFaXE3SW1Ub3VWcnA4CnlnUkprMWprVDA4cTIvNmg4eTBEdjJqMitsaHFXNzRNOUt0cmwxcTRlWmZRUFREL01tR1NnTWtDZ1lFQXdhY04KaSttN1p6dnJtL3NuekF2VlZ5SEtwZHVUUjNERk1naC9maC9tZ0ZHZ1RwZWtUOVV5b3FleGNYQXdwMVlhL01iQQoyNTVJVDZRbXZZTm5yNXp6Wmxic2tMV0hsYllvbWhmWnVXTHhXR3hRaEFORWdaMFVVdUVTRGMvbWx2UXZHbEtSCkZoaGhBUWlVSmdDamhPaHk1SlBiNGFldGRKd0UxK09lVWRFaE1vRUNnWUVBNG8yZ25CM1o4ck5xa3NzemlBek4KYmNuMlJVbDJOaW9pejBwS3JMaDFaT29NNE5BekpQdjJsaHRQMzdtS0htS1hLMHczRjFqTEgwSTBxZmxFVmVZbQpSU1huakdHazJjUnpBYUVzOGgrQzNheDE0Z01pZUtGU3BqNUpNOEFNbVVZOXQ1cUVhN2FYc3o0V1ZoOUlMYmVTCkRiNzlhKzVwd21LQVBrcnBsTHhyZFdrQ2dZQlNNSHVBWVdBbmJYZ1BDS2FZWklGVWJNUWNacmY0ZnpWQ2lmYksKYWZHampvRlNPZXdEOGdGK3BWdWJRTGwxbkFieU44ek1xVDRaaHhybUhpcFlqMjJDaHV2NmN3RXJtbGRiSnpwQwpBMnRaVXdkTk1ESFlMUG5lUHlZeGRJWnlsUXFVeW14SGkydElUQUxNcWtLOGV3ZWdXZHpkeGhQSlJScU5JazhrCmZIVHhnUUtCZ1FEUFc2UXIxY3F3QjNUdnVWdWR4WGRqUTdIcDFodXhrNEVWaEFJZllKNFhSTW1NUE5YS28wdHUKdUt6LzE0QW14R0dvSWJxYVc1bDMzeFNteUxhem84clNUN0tSTjVKME9JSHcrZkR5SFgxdHpVSjZCTldDcEFTcwpjbWdNK0htSzVON0w2bkNaZFJQY2IwU1hGaVRQUGhCUG1PVWFDUnpER0ZMK2JYM1VwajJKbWc9PQotLS0tLUVORCBSU0EgUFJJVkFURSBLRVktLS0tLQo="	read only
exp integer	The optional unix epoch timestamp that specficies the time after a token is not accepted. The maximum time specification is 24 hours from issuing time. If this field is not set, the default is one hour after issuing. `1621555515`	read only
nbf integer	The optional unix epoch timestamp that specifies the time before a the token is not accepted. If this field is not set, the default is one hour before issuing. `1621548315`	read only
downloadable boolean	The optional boolean value that enables using signed tokens to access MP4 download links for a video. `false`	default value: false valid values: (true,false) read only
accessRules array	The optional list of access rule constraints on the token. Access can be blocked or allowed based on an IP, IP range, or by country. Access rules are evaluated from first to last. If a rule matches, the associated action is applied and no further rules are evaluated. `[ { "type": "ip.geoip.country", "country": [ "US", "MX" ], "action": "block" }, { "type": "ip.src", "ip": [ "93.184.216.0/24", "2400:cb00::/32" ], "action": "allow" }, { "type": "any", "action": "block" } ]` An array with items in the following form: Show definition »	read only

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/stream/ea95132c15732412d22c1476fa83f27a/token" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"ab0d4ef71g4425f8dcba9041231813000","pem":"LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFcEFJQkFBS0NBUUVBc284dnBvOFpEWXRkOUgzbWlPaW1qYXAzVXlVM0oyZ3kwTUYvN1R4blJuRnkwRHpDCkxqUk9naFZsQ0hPQmxsd3NVaE9GU0lyYnN4K05tUTdBeS90TFpXSGxuVGF3UWJ5WGZGOStJeDhVSnNlSHBGV1oKNVF5Z1JYd2liSjh1MVVsZ2xlcmZHMkpueldjVXpZTzEySktZN3doSkw1ajROMWgxZFJNUXQ5Q1pkZFlCQWRzOQpCdk02cjRFMDcxQkhQekhWeDMrUTI1VWtubGdUNXIwS3FiM1E1Y0dlTlBXY1JreW1ybkJEWWR0OXR4eFFMb1dPCllzNXdsMnVYWFVYL0VGcDMwajU0Nmp6czllWExLYlNDbjJjTDZFVE96Y2x3aG9DRGx2a2VQT05rUE9LMDVKNUMKTm1TdFdhMG9hV1VGRzM0MFl3cVVrWGt4OU9tNndXd1JldU1uU1FJREFRQUJBb0lCQUFJOHo1ck5kOEdtOGJBMgo1S3pxQjI1R2lOVENwbUNJeW53NXRJWHZTQmNHcEdydUcvdlN2WG9kVlFVSVY0TWdHQkVXUEFrVzdsNWVBcHI4CnA1ZFd5SkRXYTNkdklFSE9vSEpYU3dBYksxZzZEMTNVa2NkZ1EyRGpoNVhuWDhHZCtBY2c2SmRTQWgxOWtYSHEKMk54RUtBVDB6Ri83a1g2MkRkREFBcWxmQkpGSXJodVIvZUdEVWh4L2piTTRhQ2JCcFdiM0pnRE9OYm5tS1ZoMwpxS2ZwZmRZZENZU1lzWUxrNTlxRDF2VFNwUVFUQ0VadW9VKzNzRVNhdkJzaUs1bU0vTzY5ZkRMRXNURG1MeTVQCmhEK3BMQXI0SlhNNjFwRGVBS0l3cUVqWWJybXlDRHRXTUdJNnZzZ0E1eXQzUUJaME9vV2w5QUkwdWxoZ3p4dXQKZ2ZFNTRRRUNnWUVBN0F3a0lhVEEzYmQ4Nk9jSVZnNFlrWGk1cm5aNDdsM1k4V24zcjIzUmVISXhLdkllRUtSbgp5bUlFNDFtRVBBSmlGWFpLK1VPTXdkeS9EcnFJUithT1JiT2NiV01jWUg2QzgvbG1wdVJFaXE3SW1Ub3VWcnA4CnlnUkprMWprVDA4cTIvNmg4eTBEdjJqMitsaHFXNzRNOUt0cmwxcTRlWmZRUFREL01tR1NnTWtDZ1lFQXdhY04KaSttN1p6dnJtL3NuekF2VlZ5SEtwZHVUUjNERk1naC9maC9tZ0ZHZ1RwZWtUOVV5b3FleGNYQXdwMVlhL01iQQoyNTVJVDZRbXZZTm5yNXp6Wmxic2tMV0hsYllvbWhmWnVXTHhXR3hRaEFORWdaMFVVdUVTRGMvbWx2UXZHbEtSCkZoaGhBUWlVSmdDamhPaHk1SlBiNGFldGRKd0UxK09lVWRFaE1vRUNnWUVBNG8yZ25CM1o4ck5xa3NzemlBek4KYmNuMlJVbDJOaW9pejBwS3JMaDFaT29NNE5BekpQdjJsaHRQMzdtS0htS1hLMHczRjFqTEgwSTBxZmxFVmVZbQpSU1huakdHazJjUnpBYUVzOGgrQzNheDE0Z01pZUtGU3BqNUpNOEFNbVVZOXQ1cUVhN2FYc3o0V1ZoOUlMYmVTCkRiNzlhKzVwd21LQVBrcnBsTHhyZFdrQ2dZQlNNSHVBWVdBbmJYZ1BDS2FZWklGVWJNUWNacmY0ZnpWQ2lmYksKYWZHampvRlNPZXdEOGdGK3BWdWJRTGwxbkFieU44ek1xVDRaaHhybUhpcFlqMjJDaHV2NmN3RXJtbGRiSnpwQwpBMnRaVXdkTk1ESFlMUG5lUHlZeGRJWnlsUXFVeW14SGkydElUQUxNcWtLOGV3ZWdXZHpkeGhQSlJScU5JazhrCmZIVHhnUUtCZ1FEUFc2UXIxY3F3QjNUdnVWdWR4WGRqUTdIcDFodXhrNEVWaEFJZllKNFhSTW1NUE5YS28wdHUKdUt6LzE0QW14R0dvSWJxYVc1bDMzeFNteUxhem84clNUN0tSTjVKME9JSHcrZkR5SFgxdHpVSjZCTldDcEFTcwpjbWdNK0htSzVON0w2bkNaZFJQY2IwU1hGaVRQUGhCUG1PVWFDUnpER0ZMK2JYM1VwajJKbWc9PQotLS0tLUVORCBSU0EgUFJJVkFURSBLRVktLS0tLQo=","exp":1621555515,"nbf":1621548315,"downloadable":false,"accessRules":[{"type":"ip.geoip.country","country":["US","MX"],"action":"block"},{"type":"ip.src","ip":["93.184.216.0/24","2400:cb00::/32"],"action":"allow"},{"type":"any","action":"block"}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImU5ZGI5OTBhODI2NjZkZDU3MWM3N2Y5NDRhNWM1YzhkIn0.eyJzdWIiOiJlYTk1MTMyYzE1NzMyNDEyZDIyYzE0NzZmYTgzZjI3YSIsImtpZCI6ImU5ZGI5OTBhODI2NjZkZDU3MWM3N2Y5NDRhNWM1YzhkIiwiZXhwIjoiMTUzNzQ2MDM2NSIsIm5iZiI6IjE1Mzc0NTMxNjUifQ.OZhqOARADn1iubK6GKcn25hN3nU-hCFF5q9w2C4yup0C4diG7aMIowiRpP-eDod8dbAJubsiFuTKrqPcmyCKWYsiv0TQueukqbQlF7HCO1TV-oF6El5-7ldJ46eD-ZQ0XgcIYEKrQOYFF8iDQbqPm3REWd6BnjKZdeVrLzuRaiSnZ9qqFpGu5dfxIY9-nZKDubJHqCr3Imtb211VIG_b9MdtO92JjvkDS-rxT_pkEfTZSafl1OU-98A7KBGtPSJHz2dHORIrUiTA6on4eIXTj9aFhGiir4rSn-rn0OjPRTtJMWIDMoQyE_fwrSYzB7MPuzL2t82BWaEbHZTfixBm5A"
  }
}

Stream Videos error codes

Code	Description
10000	Internal Server Error
10001	Authentication Failure
100013	Conflict: Media has been modified since last request
10002	Authorization Failure: Credential not authorized
10003	Not Found: Resource not found
10004	Decoding Error: Cannot decode request body
10005	Bad Request
10006	Beta Access Error
10007	Forbidden: Copy upload not enabled
10008	Invalid Duration
10009	Forbidden: Allowed key count exceeded
10010	Invalid URL
10011	File size too large
10012	Forbidden: Webhook feature not enabled
10014	File size too large
10015	Chunk size is too small
10016	Too Many Requests
10017	Expiration for upload has passed
10018	Video already uploaded
10019	Invalid Percentage Range

Stream Signing Keys

Stream signing keys are required to use signed URLs with Stream videos.

stream-signing-keys

Object definition

View properties and constraints defined on the object

Show definition

stream-signing-keys-create-signing-keys

POST Create signing keys

Creates an RSA private key in PEM and JWK formats. Key files are only displayed once after creation. Keys are created, used, and deleted independently of videos, and every key can sign any video.

POST accounts/:account_identifier/stream/keys

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/stream/keys" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "5213cfa121f70b8c1380686ffc371ba3",
    "pem": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFcGdJQkFBS0NBUUVBMFRqd2pPaVpXbUo0M3ZmM1RvNERvWG1YV3RKR05HeVhmaHl0dExhQmdGMStFUVdRCkRLaG9LYm9hS21xakNBc21za3V0YkxVN1BVOGRrUU5ER1p3S3VWczA4elNaNGt4aTR0RWdQUFp5dDdkWEMrbFkKUllveXJBR0Y0QVhoeTMyOWJIQ1AxSWxyQkIvQWtHZ25kTEFndW54WTByUmdjdk96aWF3NktKeEZuYzJVSzBXVQo4YjBwNEtLSEdwMUtMOWRrMFdUOGRWWXFiZVJpSmpDbFVFbWg4eXY5Q2xPVmFTNEt4aVg2eFRRNERadzZEYUpmCklWM1F0Tmd2cG1ieWxOSmFQSG5zc3JodDJHS1A5NjJlS2poUVJsaWd2SFhKTE9uSm9KZkxlSUVIWitpeFdmY1QKRE1IOTJzR3ZvdzFET2p4TGlDTjF6SEsraDdiTG9YVGlMZ2M0a3dJREFRQUJBb0lCQVFEQ0lCclNJMTlteGNkdwoycExVaUdCR0N4T3NhVDVLbGhkYUpESG9ZdzUxbEVuTWNXVGUyY01NTkdqaXdsN1NyOFlQMkxmcERaOFJtNzdMCk5rT2tGMnk3M3l5YUhFeEw5S1FyMys0Um9ubCtqTlp2YnV0QVdxSDVodEE0dER4MUd3NE85OEg4YWlTcGh1eWQKRUliTGRrQm54OGlDZUdxbFBnbHZ6Q1dLV0xVZlhGbXplMkF5UjBzaWMyYXZRLzZyclYwb3pDdGQ1T0Vod093agphaCs3N1dZV1l0bkEraDhXZVZreWcvdG44UTJJOXo5ZVJYdlZxR2sxMDZLcWRtZFdiU2tIZzA4cFRUSGhVM2paCnMvZGNjdEdOMWFFanlUQWY0QzdHT2lrcUd1MGFTaW1aeDFOM2RWQzBobngySjJtdlhNQ0VtZ0g3TjVnZUxWUFAKOWdkQjdBQkJBb0dCQU5sT2hGQVhaTHV6Y0Ftczl1K3AxM05STWRFOHpIK2ZFaFBrbk9zZ21Xb3VqUzkxQTRtZgpuK01oN3d5bTZoVU1DbDk2WUNMNGtPM0RUMmlYWlRqTXZuMHBoVEx1MXNYcGxWNDJuamRnZGd3cFBEM0FnL1Y5ClVvV2hxdVhoa1I3RFpsUGg5Nmk1aEE0M1BvbTVPQm9BektJbEcrT3ZKUkhhZEVveC9jSmZScFd2QW9HQkFQWjUKNnNmWDdESElCNEtBczRmMWRuNGZJUkMweUF2WVdCL1R3UzZHUWVoNFRFbDVuSkQwWk9ZRVdUbVVBK3pPanZTNApuM09tZ2xNQTU5SGd1ZW13QXVRcEtwWFBOcFUvTERJaThtNnpmTUpvL3E5M0NOQlFQZngzZGh4ZVh4OXE2Mzg3Cm84QWxkOE42RGs4TThjRis3SlNaeUVJODJzLzdpdGRseXA2bFdLaGRBb0dCQUtnU0VrUGYxQWxZdjA2OGVFRGwKRzc0VkRuTEdrMlFobzltKzk1N2psOFNJUEtwMzFrU2JNUTU3TUdpWXNIT1czRzc4TjE3VTRVTUR6R2NZc1RFOQpLaGVrQldGZldMMjU2OHp5Y1d4akx1bzQrbDdJaDBkWHBudTBqbms5L1AvT0lWYS9iczBRcnhKUHFBN2RNb2JxCkYxdFJXRURCTmVxWkMxaFhVZTBEdzVRQkFvR0JBSjdBQ2NNcnhKcVBycDZVakkyK1FOS2M5Q3dSZEdPRXRjWFMKR3JQL2owWE83YnZKVTFsZHYvc1N3L0U4NzRZL3lIM0F5QnF5SFhDZXZiRkZZQmt1MzczYThlM0pwK3RhNC9scQozdUVFUkEvbmxscW5mWXJHbEJZZlQzaVlKQVpWVkZiL3I4bWJtRmJVTDVFazBqV0JyWmxNcjFwU1hkRGx3QmhhCkhMWXY0em1WQW9HQkFLQmw0cFNnbkNSTEJMUU9jWjhXQmhRSjAwZDZieFNrTGNpZ0xUNFJvY3RwNTY1SHJPMDAKSVFLdElTaEg1a2s3SVRHdUYvOERXZEN2djBMYnhvZVBJc2NFaStTaXk5WDZwWENPaS8xa2FyYVU5U3BpZ3czago3YjVlUVV0UlovTkIycVJwc3EzMEdCUENqanhudEVmK2lqelhUS0xNRndyUDhBMTlQNzRONGVTMAotLS0tLUVORCBSU0EgUFJJVkFURSBLRVktLS0tLQo=",
    "jwk": "eyJ1c2UiOiJzaWciLCJrdHkiOiJSU0EiLCJraWQiOiI1MjEzY2ZhMTIxZjcwYjhjMTM4MDY4NmZmYzM3MWJhMyIsImFsZyI6IlJTMjU2IiwibiI6IjBUandqT2laV21KNDN2ZjNUbzREb1htWFd0SkdOR3lYZmh5dHRMYUJnRjEtRVFXUURLaG9LYm9hS21xakNBc21za3V0YkxVN1BVOGRrUU5ER1p3S3VWczA4elNaNGt4aTR0RWdQUFp5dDdkWEMtbFlSWW95ckFHRjRBWGh5MzI5YkhDUDFJbHJCQl9Ba0dnbmRMQWd1bnhZMHJSZ2N2T3ppYXc2S0p4Rm5jMlVLMFdVOGIwcDRLS0hHcDFLTDlkazBXVDhkVllxYmVSaUpqQ2xVRW1oOHl2OUNsT1ZhUzRLeGlYNnhUUTREWnc2RGFKZklWM1F0Tmd2cG1ieWxOSmFQSG5zc3JodDJHS1A5NjJlS2poUVJsaWd2SFhKTE9uSm9KZkxlSUVIWi1peFdmY1RETUg5MnNHdm93MURPanhMaUNOMXpISy1oN2JMb1hUaUxnYzRrdyIsImUiOiJBUUFCIiwiZCI6IndpQWEwaU5mWnNYSGNOcVMxSWhnUmdzVHJHay1TcFlYV2lReDZHTU9kWlJKekhGazN0bkRERFJvNHNKZTBxX0dEOWkzNlEyZkVadS15elpEcEJkc3U5OHNtaHhNU19Ta0s5X3VFYUo1Zm96V2IyN3JRRnFoLVliUU9MUThkUnNPRHZmQl9Hb2txWWJzblJDR3kzWkFaOGZJZ25ocXBUNEpiOHdsaWxpMUgxeFpzM3RnTWtkTEluTm1yMFAtcTYxZEtNd3JYZVRoSWNEc0kyb2Z1LTFtRm1MWndQb2ZGbmxaTW9QN1pfRU5pUGNfWGtWNzFhaHBOZE9pcW5ablZtMHBCNE5QS1UweDRWTjQyYlAzWEhMUmpkV2hJOGt3SC1BdXhqb3BLaHJ0R2tvcG1jZFRkM1ZRdElaOGRpZHByMXpBaEpvQi16ZVlIaTFUel9ZSFFld0FRUSIsInAiOiIyVTZFVUJka3U3TndDYXoyNzZuWGMxRXgwVHpNZjU4U0UtU2M2eUNaYWk2TkwzVURpWi1mNHlIdkRLYnFGUXdLWDNwZ0l2aVE3Y05QYUpkbE9NeS1mU21GTXU3V3hlbVZYamFlTjJCMkRDazhQY0NEOVgxU2hhR3E1ZUdSSHNObVUtSDNxTG1FRGpjLWliazRHZ0RNb2lVYjQ2OGxFZHAwU2pIOXdsOUdsYTgiLCJxIjoiOW5ucXg5ZnNNY2dIZ29DemhfVjJmaDhoRUxUSUM5aFlIOVBCTG9aQjZIaE1TWG1ja1BSazVnUlpPWlFEN002TzlMaWZjNmFDVXdEbjBlQzU2YkFDNUNrcWxjODJsVDhzTWlMeWJyTjh3bWotcjNjSTBGQTlfSGQySEY1ZkgycnJmenVqd0NWM3czb09Ud3p4d1g3c2xKbklRanphel91SzEyWEtucVZZcUYwIiwiZHAiOiJxQklTUTlfVUNWaV9Ucng0UU9VYnZoVU9jc2FUWkNHajJiNzNudU9YeElnOHFuZldSSnN4RG5zd2FKaXdjNWJjYnZ3M1h0VGhRd1BNWnhpeE1UMHFGNlFGWVY5WXZibnJ6UEp4YkdNdTZqajZYc2lIUjFlbWU3U09lVDM4Xzg0aFZyOXV6UkN2RWstb0R0MHlodW9YVzFGWVFNRTE2cGtMV0ZkUjdRUERsQUUiLCJkcSI6Im5zQUp3eXZFbW8tdW5wU01qYjVBMHB6MExCRjBZNFMxeGRJYXNfLVBSYzd0dThsVFdWMl8teExEOFR6dmhqX0lmY0RJR3JJZGNKNjlzVVZnR1M3ZnZkcng3Y21uNjFyai1XcmU0UVJFRC1lV1dxZDlpc2FVRmg5UGVKZ2tCbFZVVnYtdnladVlWdFF2a1NUU05ZR3RtVXl2V2xKZDBPWEFHRm9jdGlfak9aVSIsInFpIjoib0dYaWxLQ2NKRXNFdEE1eG54WUdGQW5UUjNwdkZLUXR5S0F0UGhHaHkybm5ya2VzN1RRaEFxMGhLRWZtU1RzaE1hNFhfd05aMEstX1F0dkdoNDhpeHdTTDVLTEwxZnFsY0k2TF9XUnF0cFQxS21LRERlUHR2bDVCUzFGbjgwSGFwR215cmZRWUU4S09QR2UwUl82S1BOZE1vc3dYQ3Nfd0RYMF92ZzNoNUxRIn0=",
    "created": "2014-01-02T02:20:00Z"
  }
}

stream-signing-keys-list-signing-keys

GET List signing keys

Lists the video ID and creation date and time when a signing key was created.

GET accounts/:account_identifier/stream/keys

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/stream/keys" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "5213cfa121f70b8c1380686ffc371ba3",
      "created": "2014-01-02T02:20:00Z"
    }
  ]
}

stream-signing-keys-delete-signing-keys

DELETE Delete signing keys

Deletes signing keys and revokes all signed URLs generated with the key.

DELETE accounts/:account_identifier/stream/keys/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/stream/keys/5213cfa121f70b8c1380686ffc371ba3" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Stream MP4 Downloads

Create .mp4 files for offline viewing and downloading.

stream-mp4-downloads

Object definition

View properties and constraints defined on the object

Show definition

stream-mp4-downloads-create-downloads

POST Create downloads

Creates a download for a video when a video is ready to view.

POST accounts/:account_identifier/stream/:video_identifier/downloads

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/stream/ea95132c15732412d22c1476fa83f27a/downloads" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "default": {
      "url": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/7227269b8c5324f9b9a68502e80df65a/downloads/default.mp4",
      "status": "ready",
      "percentComplete": "100.0"
    }
  }
}

stream-mp4-downloads-list-downloads

GET List downloads

Lists the downloads created for a video.

GET accounts/:account_identifier/stream/:video_identifier/downloads

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/stream/ea95132c15732412d22c1476fa83f27a/downloads" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "default": {
      "url": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/7227269b8c5324f9b9a68502e80df65a/downloads/default.mp4",
      "status": "ready",
      "percentComplete": "100.0"
    }
  }
}

Stream Subtitles/Captions

Add subtitles or captions to Stream videos for any language.

stream-subtitles/captions

Object definition

View properties and constraints defined on the object

Show definition

stream-subtitles/captions-upload-captions-or-subtitles

PUT Upload captions or subtitles

Uploads the caption or subtitle file to the endpoint for a specific BCP47 language. One caption or subtitle file per language is allowed.

PUT accounts/:account_identifier/stream/:video_identifier/captions/:language

Required parameters

Name /type	Description /example	Constraints
file string	The WebVTT file containing the caption or subtitle content. `"@/Users/kyle/Desktop/tr.vtt"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/stream/ea95132c15732412d22c1476fa83f27a/captions/tr" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     --form 'file=@/Users/kyle/Desktop/tr.vtt'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "label": "Türkçe",
    "language": "tr"
  }
}

stream-subtitles/captions-list-captions-or-subtitles

GET List captions or subtitles

Lists the available captions or subtitles for a specific video.

GET accounts/:account_identifier/stream/:video_identifier/captions

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/stream/ea95132c15732412d22c1476fa83f27a/captions" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "label": "Türkçe",
      "language": "tr"
    }
  ]
}

stream-subtitles/captions-delete-captions-or-subtitles

DELETE Delete captions or subtitles

Removes the captions or subtitles from a video.

DELETE accounts/:account_identifier/stream/:video_identifier/captions/:language

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/stream/ea95132c15732412d22c1476fa83f27a/captions/tr" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Stream Webhook

Create a webhook to notify your service when videos are ready to stream.

stream-webhook

Object definition

View properties and constraints defined on the object

Show definition

stream-webhook-create-webhooks

PUT Create webhooks

Creates a webhook notification.

PUT accounts/:account_identifier/stream/webhook

Required parameters

Name /type	Description /example	Constraints
notificationUrl string (url)	The URL where webhooks will be sent. `"https://example.com"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/stream/webhook" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"notificationUrl":"https://example.com"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "notificationUrl": "https://example.com",
    "modified": "2014-01-02T02:20:00Z",
    "secret": "0b1c2423aa030a11583c6ffadda57fad681d00cd"
  }
}

stream-webhook-view-webhooks

GET View webhooks

Retrieves a list of webhooks.

GET accounts/:account_identifier/stream/webhook

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/stream/webhook" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "notificationUrl": "https://example.com",
    "modified": "2014-01-02T02:20:00Z",
    "secret": "0b1c2423aa030a11583c6ffadda57fad681d00cd"
  }
}

stream-webhook-delete-webhooks

DELETE Delete webhooks

Deletes a webhook.

DELETE accounts/:account_identifier/stream/webhook

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/stream/webhook" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Stream Webhook error codes

Code	Description
10000	Internal Server Error
10001	Authentication Failure

Stream Watermark Profile

You can create watermark profile for different videos.

stream-watermark-profile

Object definition

View properties and constraints defined on the object

Show definition

stream-watermark-profile-create-watermark-profiles-from-a-url

POST Create watermark profiles from a URL

Creates a watermark profile by specifying an image's URL.

POST accounts/:account_identifier/stream/watermarks

Required parameters

Name /type	Description /example	Constraints
url string	The source URL for a downloaded image. If the watermark profile was created via direct upload, this field is null. `"https://company.com/logo.png"`	read only

Optional parameters

Name /type	Description /example	Constraints
name string	A short description of the watermark profile. `"Marketing Videos"`	default value: read only
opacity number	The translucency of the image. A value of `0.0` makes the image completely transparent, and `1.0` makes the image completely opaque. Note that if the image is already semi-transparent, setting this to `1.0` will not make the image completely opaque. `0.75`	default value: 1 min value:0 max value:1 read only
padding number	The whitespace between the adjacent edges (determined by position) of the video and the image. `0.0` indicates no padding, and `1.0` indicates a fully padded video width or length, as determined by the algorithm. `0.1`	default value: 0.05 min value:0 max value:1 read only
scale number	The size of the image relative to the overall size of the video. This parameter will adapt to horizontal and vertical videos automatically. `0.0` indicates no scaling (use the size of the image as-is), and `1.0`fills the entire video. `0.1`	default value: 0.15 min value:0 max value:1 read only
position string	The location of the image. Valid positions are: `upperRight`, `upperLeft`, `lowerLeft`, `lowerRight`, and `center`. Note that `center` ignores the `padding` parameter. `"center"`	default value: upperRight read only

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/stream/watermarks" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"url":"https://company.com/logo.png","name":"Marketing Videos","opacity":0.75,"padding":0.1,"scale":0.1,"position":"center"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "uid": "ea95132c15732412d22c1476fa83f27a",
    "size": 29472,
    "height": 600,
    "width": 400,
    "created": "2014-01-02T02:20:00Z",
    "downloadedFrom": "https://company.com/logo.png",
    "name": "Marketing Videos",
    "opacity": 0.75,
    "padding": 0.1,
    "scale": 0.1,
    "position": "center"
  }
}

stream-watermark-profile-create-watermark-profiles-via-basic-upload

POST Create watermark profiles via basic upload

Creates watermark profiles using a single HTTP POST multipart/form-data request.

POST accounts/:account_identifier/stream/watermarks

Required parameters

Name /type	Description /example	Constraints
file string	The image file to upload. `"@/Users/rchen/Downloads/watermark.png"`

Optional parameters

Name /type	Description /example	Constraints
name string	A short description of the watermark profile. `"Marketing Videos"`	default value: read only
opacity number	The translucency of the image. A value of `0.0` makes the image completely transparent, and `1.0` makes the image completely opaque. Note that if the image is already semi-transparent, setting this to `1.0` will not make the image completely opaque. `0.75`	default value: 1 min value:0 max value:1 read only
padding number	The whitespace between the adjacent edges (determined by position) of the video and the image. `0.0` indicates no padding, and `1.0` indicates a fully padded video width or length, as determined by the algorithm. `0.1`	default value: 0.05 min value:0 max value:1 read only
scale number	The size of the image relative to the overall size of the video. This parameter will adapt to horizontal and vertical videos automatically. `0.0` indicates no scaling (use the size of the image as-is), and `1.0`fills the entire video. `0.1`	default value: 0.15 min value:0 max value:1 read only
position string	The location of the image. Valid positions are: `upperRight`, `upperLeft`, `lowerLeft`, `lowerRight`, and `center`. Note that `center` ignores the `padding` parameter. `"center"`	default value: upperRight read only

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/stream/watermarks" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     --form 'file=@/Users/rchen/Downloads/watermark.png' \
     --form 'name=Marketing Videos' \
     --form 'opacity=0.75' \
     --form 'padding=0.1' \
     --form 'scale=0.1' \
     --form 'position=center'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "uid": "ea95132c15732412d22c1476fa83f27a",
    "size": 29472,
    "height": 600,
    "width": 400,
    "created": "2014-01-02T02:20:00Z",
    "downloadedFrom": "https://company.com/logo.png",
    "name": "Marketing Videos",
    "opacity": 0.75,
    "padding": 0.1,
    "scale": 0.1,
    "position": "center"
  }
}

stream-watermark-profile-list-watermark-profiles

GET List watermark profiles

Lists all watermark profiles for an account.

GET accounts/:account_identifier/stream/watermarks

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/stream/watermarks" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "uid": "ea95132c15732412d22c1476fa83f27a",
      "size": 29472,
      "height": 600,
      "width": 400,
      "created": "2014-01-02T02:20:00Z",
      "downloadedFrom": "https://company.com/logo.png",
      "name": "Marketing Videos",
      "opacity": 0.75,
      "padding": 0.1,
      "scale": 0.1,
      "position": "center"
    }
  ]
}

stream-watermark-profile-watermark-profile-details

GET Watermark profile details

Retrieves details for a single watermark profile.

GET accounts/:account_identifier/stream/watermarks/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/stream/watermarks/ea95132c15732412d22c1476fa83f27a" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "uid": "ea95132c15732412d22c1476fa83f27a",
    "size": 29472,
    "height": 600,
    "width": 400,
    "created": "2014-01-02T02:20:00Z",
    "downloadedFrom": "https://company.com/logo.png",
    "name": "Marketing Videos",
    "opacity": 0.75,
    "padding": 0.1,
    "scale": 0.1,
    "position": "center"
  }
}

stream-watermark-profile-delete-watermark-profiles

DELETE Delete watermark profiles

Deletes a watermark profile.

DELETE accounts/:account_identifier/stream/watermarks/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/stream/watermarks/ea95132c15732412d22c1476fa83f27a" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Stream Watermark Profile error codes

Code	Description
10020	Invalid Percentage Range for Opacity
10021	Invalid Percentage Range for Padding
10022	Invalid Percentage Range for Scale
10023	Invalid Value for Position
10024	Forbidden: Allowed watermark count exceeded

Stream Live Inputs

Each live input is a unique destination that you or your users can stream live video to.

stream-live-inputs

Object definition

View properties and constraints defined on the object

Show definition

stream-live-inputs-create-a-live-input

POST Create a live input

Creates a live input, and returns credentials that you or your users can use to stream live video to Cloudflare Stream.

POST accounts/:account_identifier/stream/live_inputs

Optional parameters

Name /type	Description /example	Constraints
meta object	A user modifiable key-value store used to reference other systems of record for managing live inputs. `{ "name": "test stream 1" }`
recording object	Records the input to a Cloudflare Stream video. Behavior depends on the mode. In most cases, the video will initially be viewable as a live video and transition to on-demand after a condition is satisfied. `{ "mode": "automatic", "requireSignedURLs": true, "allowedOrigins": [ "example.com" ], "timeoutSeconds": 0 }` An object with the following properties: Show definition »
defaultCreator string	Sets the creator ID asssociated with this live input. `null`	default value: null

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/stream/live_inputs" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"meta":{"name":"test stream 1"},"recording":{"mode":"automatic","requireSignedURLs":true,"allowedOrigins":["example.com"],"timeoutSeconds":0},"defaultCreator":null}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "uid": "66be4bf738797e01e1fca35a7bdecdcd",
    "meta": {
      "name": "test stream 1"
    },
    "created": "2014-01-02T02:20:00Z",
    "modified": "2014-01-02T02:20:00Z",
    "rtmps": {
      "url": "rtmps://live.cloudflare.com:443/live/",
      "streamKey": "MjE2OTAxNzQyMjQxNDkyNDYyNTAxNjc3MzE3NzY4MjAwMTYxODMxMjMxOTc66be4bf738797e01e1fca35a7bdecdcd"
    },
    "recording": {
      "mode": "automatic",
      "requireSignedURLs": true,
      "allowedOrigins": [
        "example.com"
      ],
      "timeoutSeconds": 0
    }
  }
}

stream-live-inputs-list-live-inputs

GET List live inputs

Lists the live inputs created for an account. To get the credentials needed to stream to a specific live input, request a single live input.

GET accounts/:account_identifier/stream/live_inputs

Optional parameters

Name /type	Description /example	Constraints
after string (date-time)	Lists live inputs created after the specified date and time. `"2022-01-02T02:20:00Z"`
before string (date-time)	Lists live inputs created before the specified date and time. `"2022-07-02T02:20:00Z"`
include_counts boolean	Lists stats in the response that include the number of live inputs in the response range and the total number of live inputs available. When this parameter is not specified or is specified as `false`, the `result` field of the response object will be an array with the live inputs. `false`	default value: false valid values: (true,false)
search string	Searches over the `name` key in the `meta` field. This field can be set when creating the live input, or after with the update request. `"live stream 1"`
limit integer	The number of live inputs to include in the response.	min value:0 max value:1000
asc boolean	Lists live inputs in ascending order of creation. `false`	default value: false valid values: (true,false)

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/stream/live_inputs?after=2022-01-02T02:20:00Z&before=2022-07-02T02:20:00Z&include_counts=false&search=live stream 1&limit=undefined&asc=false" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "liveInputs": [
      {
        "uid": "66be4bf738797e01e1fca35a7bdecdcd",
        "meta": {
          "name": "test stream 1"
        },
        "created": "2014-01-02T02:20:00Z",
        "modified": "2014-01-02T02:20:00Z"
      }
    ],
    "total": "35586",
    "range": "1000"
  }
}

stream-live-inputs-retrieve-a-live-input

GET Retrieve a live input

Retrieves details of an existing live input.

GET accounts/:account_identifier/stream/live_inputs/:live_input_identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/stream/live_inputs/66be4bf738797e01e1fca35a7bdecdcd" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "uid": "66be4bf738797e01e1fca35a7bdecdcd",
    "meta": {
      "name": "test stream 1"
    },
    "created": "2014-01-02T02:20:00Z",
    "modified": "2014-01-02T02:20:00Z",
    "rtmps": {
      "url": "rtmps://live.cloudflare.com:443/live/",
      "streamKey": "MjE2OTAxNzQyMjQxNDkyNDYyNTAxNjc3MzE3NzY4MjAwMTYxODMxMjMxOTc66be4bf738797e01e1fca35a7bdecdcd"
    },
    "recording": {
      "mode": "automatic",
      "requireSignedURLs": true,
      "allowedOrigins": [
        "example.com"
      ],
      "timeoutSeconds": 0
    }
  }
}

stream-live-inputs-update-a-live-input

PUT Update a live input

Updates a specified live input.

PUT accounts/:account_identifier/stream/live_inputs/:live_input_identifier

Optional parameters

Name /type	Description /example	Constraints
meta object	A user modifiable key-value store used to reference other systems of record for managing live inputs. `{ "name": "test stream 1" }`
recording object	Records the input to a Cloudflare Stream video. Behavior depends on the mode. In most cases, the video will initially be viewable as a live video and transition to on-demand after a condition is satisfied. `{ "mode": "automatic", "requireSignedURLs": true, "allowedOrigins": [ "example.com" ], "timeoutSeconds": 0 }` An object with the following properties: Show definition »
defaultCreator string	Sets the creator ID asssociated with this live input. `null`	default value: null

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/stream/live_inputs/66be4bf738797e01e1fca35a7bdecdcd" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"meta":{"name":"test stream 1"},"recording":{"mode":"automatic","requireSignedURLs":true,"allowedOrigins":["example.com"],"timeoutSeconds":0},"defaultCreator":null}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "uid": "66be4bf738797e01e1fca35a7bdecdcd",
    "meta": {
      "name": "test stream 1"
    },
    "created": "2014-01-02T02:20:00Z",
    "modified": "2014-01-02T02:20:00Z",
    "rtmps": {
      "url": "rtmps://live.cloudflare.com:443/live/",
      "streamKey": "MjE2OTAxNzQyMjQxNDkyNDYyNTAxNjc3MzE3NzY4MjAwMTYxODMxMjMxOTc66be4bf738797e01e1fca35a7bdecdcd"
    },
    "recording": {
      "mode": "automatic",
      "requireSignedURLs": true,
      "allowedOrigins": [
        "example.com"
      ],
      "timeoutSeconds": 0
    }
  }
}

stream-live-inputs-delete-a-live-input

DELETE Delete a live input

Prevents a live input from being streamed to and makes the live input inaccessible to any future API calls.

DELETE accounts/:account_identifier/stream/live_inputs/:live_input_identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/stream/live_inputs/66be4bf738797e01e1fca35a7bdecdcd" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

stream-live-inputs-create-a-new-output,-connected-to-a-live-input

POST Create a new output, connected to a live input

Creates a new output that can be used to simulcast or restream live video to other RTMP or SRT destinations. Outputs are always linked to a specific live input — one live input can have many outputs.

POST accounts/:account_identifier/stream/live_inputs/:live_input_identifier/outputs

Required parameters

Name /type	Description /example	Constraints
url string	The URL an output uses to restream. `"rtmp://a.rtmp.youtube.com/live2"`	read only
streamKey string	The streamKey used to authenticate against an output's target. `"uzya-f19y-g2g9-a2ee-51j2"`	read only

Optional parameters

Name /type	Description /example	Constraints
enabled boolean	When enabled, live video streamed to the associated live input will be sent to the output URL. When disabled, live video will not be sent to the output URL, even when streaming to the associated live input. Use this to control precisely when you start and stop simulcasting to specific destinations like YouTube and Twitch. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/stream/live_inputs/66be4bf738797e01e1fca35a7bdecdcd/outputs" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"url":"rtmp://a.rtmp.youtube.com/live2","streamKey":"uzya-f19y-g2g9-a2ee-51j2","enabled":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "uid": "baea4d9c515887b80289d5c33cf01145",
    "url": "rtmp://a.rtmp.youtube.com/live2",
    "streamKey": "uzya-f19y-g2g9-a2ee-51j2",
    "enabled": true
  }
}

stream-live-inputs-list-all-outputs-associated-with-a-specified-live-input

GET List all outputs associated with a specified live input

Retrieves all outputs associated with a specified live input.

GET accounts/:account_identifier/stream/live_inputs/:live_input_identifier/outputs

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/stream/live_inputs/66be4bf738797e01e1fca35a7bdecdcd/outputs" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "uid": "baea4d9c515887b80289d5c33cf01145",
      "url": "rtmp://a.rtmp.youtube.com/live2",
      "streamKey": "uzya-f19y-g2g9-a2ee-51j2",
      "enabled": true
    }
  ]
}

stream-live-inputs-delete-an-output

DELETE Delete an output

Deletes an output and removes it from the associated live input.

DELETE accounts/:account_identifier/stream/live_inputs/:live_input_identifier/outputs/:output_identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/stream/live_inputs/66be4bf738797e01e1fca35a7bdecdcd/outputs/baea4d9c515887b80289d5c33cf01145" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

stream-live-inputs-update-an-output

PUT Update an output

Updates the state of an output.

PUT accounts/:account_identifier/stream/live_inputs/:live_input_identifier/outputs/:output_identifier

Required parameters

Name /type	Description /example	Constraints
enabled boolean	When enabled, live video streamed to the associated live input will be sent to the output URL. When disabled, live video will not be sent to the output URL, even when streaming to the associated live input. Use this to control precisely when you start and stop simulcasting to specific destinations like YouTube and Twitch. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/stream/live_inputs/66be4bf738797e01e1fca35a7bdecdcd/outputs/baea4d9c515887b80289d5c33cf01145" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"enabled":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "uid": "baea4d9c515887b80289d5c33cf01145",
    "url": "rtmp://a.rtmp.youtube.com/live2",
    "streamKey": "uzya-f19y-g2g9-a2ee-51j2",
    "enabled": true
  }
}

Stream Video Clipping

Clip or trim a video based on a start and end time range.

stream-video-clipping

Object definition

View properties and constraints defined on the object

Show definition

stream-video-clipping-clip-videos-given-a-start-and-end-time

POST Clip videos given a start and end time

Clips a video based on the specified start and end times provided in seconds.

POST accounts/:account_identifier/stream/clip

Required parameters

Name /type	Description /example	Constraints
startTimeSeconds integer	Specifies the start time for the video clip in seconds. `35`	read only
endTimeSeconds integer	Specifies the end time for the video clip in seconds. `155`	read only
clippedFromVideoUID string	The unique video identifier (UID). `"023e105f4ecef8ad9ca31a8372d0c353"`	max length: 32 read only

Optional parameters

Name /type	Description /example	Constraints
watermark object	`{ "uid": "ea95132c15732412d22c1476fa83f27a" }` An object with the following properties: Show definition »
requireSignedURLs boolean	Indicates whether the video can be a accessed using the UID. When set to `true`, a signed token must be generated with a signing key to view the video. `true`	default value: false valid values: (true,false) read only
allowedOrigins array	Lists the origins allowed to display the video. Enter allowed origin domains in an array and use `*` for wildcard subdomains. Empty arrays allow the video to be viewed on any origin. `[ "example.com" ]` An array with items in the following form: Show definition »
maxDurationSeconds integer	Calculates the amount of time a video occupies before the video is uploaded. Direct uploads occupy minutes of videos on your Stream account until they are expired. After upload, the upload duration is used instead. If a video longer than the value is uploaded, the video results in an error. `300`	min value:1 max value:21600
creator string	A user-defined identifier for the media creator. `"creator-id_abcde12345"`	max length: 64
thumbnailTimestampPct number	The timestamp for a thumbnail image calculated as a percentage value of the video's duration. To convert from a second-wise timestamp to a percentage, divide the desired timestamp by the total duration of the video. If this value is not set, the default thumbnail image is taken from 0s of the video. `0.529241`	default value: 0 min value:0 max value:1

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/stream/clip" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"clippedFromVideoUID":"023e105f4ecef8ad9ca31a8372d0c353","startTimeSeconds":35,"endTimeSeconds":155,"creator":"creator-id_abcde12345","maxDurationSeconds":300,"thumbnailTimestampPct":0.529241,"allowedOrigins":["example.com"],"requireSignedURLs":true,"watermark":{"uid":"ea95132c15732412d22c1476fa83f27a"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "clippedFromVideoUID": "023e105f4ecef8ad9ca31a8372d0c353",
    "startTimeSeconds": 35,
    "endTimeSeconds": 155,
    "playback": {
      "hls": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/manifest/video.m3u8",
      "dash": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/manifest/video.mpd"
    },
    "preview": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/watch",
    "created": "2014-01-02T02:20:00Z",
    "modified": "2014-01-02T02:20:00Z",
    "creator": "creator-id_abcde12345",
    "maxDurationSeconds": 300,
    "thumbnailTimestampPct": 0.529241,
    "allowedOrigins": [
      "example.com"
    ],
    "requireSignedURLs": true,
    "watermark": {
      "uid": "ea95132c15732412d22c1476fa83f27a"
    },
    "meta": {
      "name": "example_filename.mp4"
    },
    "status": "inprogress"
  }
}

Cloudflare Images

Upload images to Cloudflare Images for fast image processing and delivery.

cloudflare-images

Object definition

View properties and constraints defined on the object

Show definition

cloudflare-images-upload-an-image-using-a-single-http-request

POST Upload an image using a single HTTP request

Upload an image with up to 10 Megabytes using a single HTTP POST (multipart/form-data) request.

POST accounts/:account_identifier/images/v1

Required parameters

Name /type	Description /example	Constraints
file string	Image file to upload. `"@/Users/kyle/Desktop/logo.png"`

Optional parameters

Name /type	Description /example	Constraints
requireSignedURLs boolean	Indicates whether the image requires a signature token for the access. `true`	default value: false valid values: (true,false)
metadata object	User modifiable key-value store. Can use used for keeping references to another system of record for managing images. `"{\"key\": \"value\"}"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/images/v1" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: multipart/form-data" \
     --form 'file=@/Users/kyle/Desktop/logo.png' \
     --form 'requireSignedURLs=true' \
     --form 'metadata={"key": "value"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "107b9558-dd06-4bbd-5fef-9c2c16bb7900",
    "filename": "logo.png",
    "metadata": {
      "key": "value"
    },
    "requireSignedURLs": true,
    "variants": [
      "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/thumbnail",
      "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/hero",
      "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/original"
    ],
    "uploaded": "2014-01-02T02:20:00Z"
  }
}

cloudflare-images-upload-an-image-via-url

POST Upload an image via URL

Upload an image via URL with up to 10 Megabytes using a single HTTP POST (multipart/form-data) request.

POST accounts/:account_identifier/images/v1

Required parameters

Name /type	Description /example	Constraints
url string	A URL to fetch an image from origin. `"https://example.com/path/to/logo.png"`

Optional parameters

Name /type	Description /example	Constraints
requireSignedURLs boolean	Indicates whether the image requires a signature token for the access. `true`	default value: false valid values: (true,false)
metadata object	User modifiable key-value store. Can use used for keeping references to another system of record for managing images. `"{\"key\": \"value\"}"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/images/v1" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: multipart/form-data" \
     --form 'url=https://example.com/path/to/logo.png' \
     --form 'requireSignedURLs=true' \
     --form 'metadata={"key": "value"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "107b9558-dd06-4bbd-5fef-9c2c16bb7900",
    "filename": "logo.png",
    "metadata": {
      "key": "value"
    },
    "requireSignedURLs": true,
    "variants": [
      "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/thumbnail",
      "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/hero",
      "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/original"
    ],
    "uploaded": "2014-01-02T02:20:00Z"
  }
}

cloudflare-images-update-image

PATCH Update image

Update image access control. On access control change, all copies of the image are purged from cache.

PATCH accounts/:account_identifier/images/v1/:identifier

Optional parameters

Name /type	Description /example	Constraints
requireSignedURLs boolean	Indicates whether the image can be accessed using only its UID. If set to `true`, a signed token needs to be generated with a signing key to view the image. Returns a new UID on a change. No change if not specified. `true`	valid values: (true,false)
metadata object	User modifiable key-value store. Can be used for keeping references to another system of record for managing images. No change if not specified. `"{\"key\": \"value\"}"`

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/images/v1/107b9558-dd06-4bbd-5fef-9c2c16bb7900" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"requireSignedURLs":true,"metadata":"{\"key\": \"value\"}"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "107b9558-dd06-4bbd-5fef-9c2c16bb7900",
    "filename": "logo.png",
    "metadata": {
      "key": "value"
    },
    "requireSignedURLs": true,
    "variants": [
      "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/thumbnail",
      "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/hero",
      "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/original"
    ],
    "uploaded": "2014-01-02T02:20:00Z"
  }
}

Deprecation Warning

End of life Date: July 1, 2022

Use direct_upload v2 instead: https://api.cloudflare.com/#cloudflare-images-create-authenticated-direct-upload-url-v2. It allows you to control metadata, access policy, and returns the same image ID an image will be accessible with.

cloudflare-images-create-authenticated-direct-upload-url

POST Create authenticated direct upload URL

Direct uploads allow users to upload images without API keys. A common use case are web apps, client-side applications, or mobile devices where users upload content directly to Cloudflare Images.

POST accounts/:account_identifier/images/v1/direct_upload

Optional parameters

Name /type	Description /example	Constraints
expiry string (date-time)	The date after which the upload will not be accepted. Minimum: Now + 2 minutes. Maximum: Now + 6 hours. `"2021-01-02T02:20:00Z"`	default value: Now + 30 minutes

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/images/v1/direct_upload" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"expiry":"2021-01-02T02:20:00Z"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "uploadURL": "https://upload.imagedelivery.net/e22e9e6b-c02b-42fd-c405-6c32af5fe623",
    "id": "107b9558-dd06-4bbd-5fef-9c2c16bb7900"
  }
}

cloudflare-images-create-authenticated-direct-upload-url-v2

POST Create authenticated direct upload URL V2

Direct uploads allow users to upload images without API keys. A common use case are web apps, client-side applications, or mobile devices where users upload content directly to Cloudflare Images. This method creates a draft record for a future image. It returns an upload URL and an image identifier. To verify if the image itself has been uploaded, send an image details request (accounts/:account_identifier/images/v1/:identifier), and check that the draft: true property is not present.

POST accounts/:account_identifier/images/v2/direct_upload

Optional parameters

Name /type	Description /example	Constraints
requireSignedURLs boolean	Indicates whether the image requires a signature token to be accessed. `true`	default value: false valid values: (true,false)
metadata object	User modifiable key-value store. Can be used for keeping references to another system of record, for managing images. `"{\"key\": \"value\"}"`
expiry string (date-time)	The date after which the upload will not be accepted. Minimum: Now + 2 minutes. Maximum: Now + 6 hours. `"2021-01-02T02:20:00Z"`	default value: Now + 30 minutes

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/images/v2/direct_upload" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: multipart/form-data" \
     --form 'requireSignedURLs=true' \
     --form 'metadata={"key": "value"}' \
     --form 'expiry=2021-01-02T02:20:00Z'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "uploadURL": "https://upload.imagedelivery.net/FxUufywByo0m2v3xhKSiU8/e22e9e6b-c02b-42fd-c405-6c32af5fe600",
    "id": "e22e9e6b-c02b-42fd-c405-6c32af5fe600"
  }
}

cloudflare-images-list-images

GET List images

List up to 100 images with one request. Use the optional parameters below to get a specific range of images.

GET accounts/:account_identifier/images/v1

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. `50`	default value: 50 min value:10 max value:100

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/images/v1?page=1&per_page=50" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "107b9558-dd06-4bbd-5fef-9c2c16bb7900",
      "filename": "logo.png",
      "metadata": {
        "key": "value"
      },
      "requireSignedURLs": true,
      "variants": [
        "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/thumbnail",
        "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/hero",
        "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/original"
      ],
      "uploaded": "2014-01-02T02:20:00Z"
    }
  ]
}

cloudflare-images-image-details

GET Image details

Fetch details for a single image.

GET accounts/:account_identifier/images/v1/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/images/v1/107b9558-dd06-4bbd-5fef-9c2c16bb7900" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "107b9558-dd06-4bbd-5fef-9c2c16bb7900",
    "filename": "logo.png",
    "metadata": {
      "key": "value"
    },
    "requireSignedURLs": true,
    "variants": [
      "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/thumbnail",
      "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/hero",
      "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/original"
    ],
    "uploaded": "2014-01-02T02:20:00Z"
  }
}

cloudflare-images-base-image

GET Base image

Fetch base image. For most images this will be the originally uploaded file. For larger images it can be a near-lossless version of the original.

GET accounts/:account_identifier/images/v1/:identifier/blob

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/images/v1/107b9558-dd06-4bbd-5fef-9c2c16bb7900/blob" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

<image blob data>

cloudflare-images-delete-image

DELETE Delete image

Delete an image on Cloudflare Images. On success, all copies of the image are deleted and purged from cache.

DELETE accounts/:account_identifier/images/v1/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/images/v1/107b9558-dd06-4bbd-5fef-9c2c16bb7900" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

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

cloudflare-images-images-usage-statistics

GET Images usage statistics

Fetch usage statistics details for Cloudflare Images.

GET accounts/:account_identifier/images/v1/stats

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/023e105f4ecef8ad9ca31a8372d0c353/images/v1/stats" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "count": {
    "current": 1000,
    "allowed": 100000
  }
}

Cloudflare Images error codes

Code	Description
5400	Bad Request.
5401	Variant <name> not found.
5403	The given account is not valid or is not authorized to access this service.
5404	Image not found.
5408	Client was sending upload too slowly.
5413	Maximum image size of 10 MB is reached
5415	Images must be uploaded as a form, not as raw image data. Please use multipart/form-data format.
5433	Request has been aborted by the client.
5450	Error while receiving upload.
5453	The given account has reached a service limit.
5455	Unsupported image format.
5500	Internal Server Error.
5503	Server Unavailable.
5540	Error received from the storage.
5541	Error while purging cache.
5542	Error while loading account.
5543	Error during audit.
5544	Error during abuse operation.
5550	Internal Server Error.

Cloudflare Images Variants

Cloudflare Images supports variants that specify different image sizes for different use cases. You can configure up to 20 variants.

cloudflare-images-variants

Object definition

View properties and constraints defined on the object

Show definition

cloudflare-images-variants-create-a-variant

POST Create a variant

Specify variants that allow you to resize images for different use cases.

POST accounts/:account_identifier/images/v1/variants

Required parameters

Name /type	Description /example	Constraints
id string	API item identifier tag `"hero"`	max length: 99 read only pattern: ^[a-zA-Z0-9]$
options object	Allows you to define image resizing sizes for different use cases. `{ "fit": "scale-down", "metadata": "none", "width": 1366, "height": 768 }` An object with the following properties: Show definition »

Optional parameters

Name /type	Description /example	Constraints
neverRequireSignedURLs boolean	Indicates whether the variant can access an image without a signature, regardless of image access control. `true`	default value: false valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/images/v1/variants" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"hero","options":{"fit":"scale-down","metadata":"none","width":1366,"height":768},"neverRequireSignedURLs":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "variant": {
      "id": "hero",
      "options": {
        "fit": "scale-down",
        "metadata": "none",
        "width": 1366,
        "height": 768
      },
      "neverRequireSignedURLs": true
    }
  }
}

cloudflare-images-variants-list-variants

GET List variants

Lists existing variants.

GET accounts/:account_identifier/images/v1/variants

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/images/v1/variants" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "variants": {
      "hero": {
        "id": "hero",
        "options": {
          "fit": "scale-down",
          "metadata": "none",
          "width": 1366,
          "height": 768
        },
        "neverRequireSignedURLs": true
      }
    }
  }
}

cloudflare-images-variants-variant-details

GET Variant details

Fetch details for a single variant.

GET accounts/:account_identifier/images/v1/variants/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/images/v1/variants/hero" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "variant": {
      "id": "hero",
      "options": {
        "fit": "scale-down",
        "metadata": "none",
        "width": 1366,
        "height": 768
      },
      "neverRequireSignedURLs": true
    }
  }
}

cloudflare-images-variants-update-a-variant

PATCH Update a variant

Updating a variant purges the cache for all images associated with the variant.

PATCH accounts/:account_identifier/images/v1/variants/:identifier

Required parameters

Name /type	Description /example	Constraints
options object	Allows you to define image resizing sizes for different use cases. `{ "fit": "scale-down", "metadata": "none", "width": 1366, "height": 768 }` An object with the following properties: Show definition »

Optional parameters

Name /type	Description /example	Constraints
neverRequireSignedURLs boolean	Indicates whether the variant can access an image without a signature, regardless of image access control. `true`	default value: false valid values: (true,false)

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/images/v1/variants/hero" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"options":{"fit":"scale-down","metadata":"none","width":1366,"height":768},"neverRequireSignedURLs":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "variant": {
      "id": "hero",
      "options": {
        "fit": "scale-down",
        "metadata": "none",
        "width": 1366,
        "height": 768
      },
      "neverRequireSignedURLs": true
    }
  }
}

cloudflare-images-variants-delete-a-variant

DELETE Delete a variant

Deleting a variant purges the cache for all images associated with the variant.

DELETE accounts/:account_identifier/images/v1/variants/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/images/v1/variants/hero" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

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

Cloudflare Images Keys

Keys are used to generate signature tokens required for accessing images marked as private.

cloudflare-images-keys

Object definition

View properties and constraints defined on the object

Show definition

cloudflare-images-keys-list-signing-keys

GET List Signing Keys

Lists your signing keys. These can be found on your Cloudflare Images dashboard.

GET accounts/:account_identifier/images/v1/keys

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/images/v1/keys" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "keys": [
      {
        "name": "default",
        "value": "Oix0bbNaT8Rge9PuyxUBrjI6zrgnsyJ5="
      }
    ]
  }
}

Pages Project

A Pages project represents a website deployed to Cloudflare's edge.

For more detailed documentation on using the API for Pages see the Pages docs.

pages-project

Object definition

View properties and constraints defined on the object

Show definition

pages-project-get-projects

GET Get projects

Fetch a list of all user projects

GET accounts/:account_identifier/pages/projects

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/pages/projects" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "name": "NextJS Blog",
      "id": "7b162ea7-7367-4d67-bcde-1160995d5",
      "created_on": "2017-01-01T00:00:00Z",
      "subdomain": "helloworld.pages.dev",
      "domains": [
        "customdomain.com",
        "customdomain.org"
      ],
      "source": {
        "type": "github",
        "config": {
          "owner": "cloudflare",
          "repo_name": "ninjakittens",
          "production_branch": "main",
          "pr_comments_enabled": true,
          "production_deployments_enabled": true,
          "preview_deployment_setting": "custom",
          "preview_branch_includes": [
            "release/*",
            "production",
            "main"
          ],
          "preview_branch_excludes": [
            "dependabot/*",
            "dev",
            "*/ignore"
          ]
        }
      },
      "build_config": {
        "build_command": "npm run build",
        "destination_dir": "build",
        "root_dir": "/",
        "web_analytics_tag": "cee1c73f6e4743d0b5e6bb1a0bcaabcc",
        "web_analytics_token": "021e1057c18547eca7b79f2516f06o7x"
      },
      "deployment_configs": {
        "preview": {
          "env_vars": {
            "BUILD_VERSION": {
              "value": "3.3"
            }
          },
          "kv_namespaces": {
            "KV_BINDING": {
              "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3"
            }
          },
          "durable_object_namespaces": {
            "DO_BINDING": {
              "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3"
            }
          },
          "r2_buckets": {
            "R2_BINDING": {
              "name": "some-bucket"
            }
          },
          "d1_databases": {
            "D1_BINDING": {
              "id": "445e2955-951a-43f8-a35b-a4d0c8138f63"
            }
          },
          "compatibility_date": "2022-01-01",
          "compatibility_flags": [
            "url_standard"
          ]
        },
        "production": {
          "env_vars": {
            "BUILD_VERSION": {
              "value": "3.3"
            }
          },
          "kv_namespaces": {
            "KV_BINDING": {
              "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3"
            }
          },
          "durable_object_namespaces": {
            "DO_BINDING": {
              "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3"
            }
          },
          "r2_buckets": {
            "R2_BINDING": {
              "name": "some-bucket"
            }
          },
          "d1_databases": {
            "D1_BINDING": {
              "id": "445e2955-951a-43f8-a35b-a4d0c8138f63"
            }
          },
          "compatibility_date": "2022-01-01",
          "compatibility_flags": [
            "url_standard"
          ]
        }
      },
      "latest_deployment": {},
      "canonical_deployment": {},
      "production_branch": "main"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 100,
    "count": 1,
    "total_count": 1
  }
}

pages-project-get-project

GET Get project

Fetch a project by name

GET accounts/:account_identifier/pages/projects/:project_name

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/pages/projects/this-is-my-project-01" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "name": "NextJS Blog",
    "id": "7b162ea7-7367-4d67-bcde-1160995d5",
    "created_on": "2017-01-01T00:00:00Z",
    "subdomain": "helloworld.pages.dev",
    "domains": [
      "customdomain.com",
      "customdomain.org"
    ],
    "source": {
      "type": "github",
      "config": {
        "owner": "cloudflare",
        "repo_name": "ninjakittens",
        "production_branch": "main",
        "pr_comments_enabled": true,
        "production_deployments_enabled": true,
        "preview_deployment_setting": "custom",
        "preview_branch_includes": [
          "release/*",
          "production",
          "main"
        ],
        "preview_branch_excludes": [
          "dependabot/*",
          "dev",
          "*/ignore"
        ]
      }
    },
    "build_config": {
      "build_command": "npm run build",
      "destination_dir": "build",
      "root_dir": "/",
      "web_analytics_tag": "cee1c73f6e4743d0b5e6bb1a0bcaabcc",
      "web_analytics_token": "021e1057c18547eca7b79f2516f06o7x"
    },
    "deployment_configs": {
      "preview": {
        "env_vars": {
          "BUILD_VERSION": {
            "value": "3.3"
          }
        },
        "kv_namespaces": {
          "KV_BINDING": {
            "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3"
          }
        },
        "durable_object_namespaces": {
          "DO_BINDING": {
            "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3"
          }
        },
        "r2_buckets": {
          "R2_BINDING": {
            "name": "some-bucket"
          }
        },
        "d1_databases": {
          "D1_BINDING": {
            "id": "445e2955-951a-43f8-a35b-a4d0c8138f63"
          }
        },
        "compatibility_date": "2022-01-01",
        "compatibility_flags": [
          "url_standard"
        ]
      },
      "production": {
        "env_vars": {
          "BUILD_VERSION": {
            "value": "3.3"
          }
        },
        "kv_namespaces": {
          "KV_BINDING": {
            "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3"
          }
        },
        "durable_object_namespaces": {
          "DO_BINDING": {
            "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3"
          }
        },
        "r2_buckets": {
          "R2_BINDING": {
            "name": "some-bucket"
          }
        },
        "d1_databases": {
          "D1_BINDING": {
            "id": "445e2955-951a-43f8-a35b-a4d0c8138f63"
          }
        },
        "compatibility_date": "2022-01-01",
        "compatibility_flags": [
          "url_standard"
        ]
      }
    },
    "latest_deployment": {},
    "canonical_deployment": {},
    "production_branch": "main"
  }
}

pages-project-delete-project

DELETE Delete project

Destroy a project by name

DELETE accounts/:account_identifier/pages/projects/:project_name

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/pages/projects/this-is-my-project-01" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

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

pages-project-create-project

POST Create project

Make a new project

POST accounts/:account_identifier/pages/projects

Optional parameters

Name /type	Description /example	Constraints
subdomain string	The Cloudflare subdomain associated with the project `"helloworld.pages.dev"`	read only
production_branch string	Production branch of the project. Used to identify production deployments `"main"`
name string	Name of the project `"NextJS Blog"`
domains array	A list of associated custom domains for the project `[ "customdomain.com", "customdomain.org" ]`	read only
canonical_deployment	Most recent deployment to the repo `{}` One of the following: Show definition » A Pages deployment is a published build for a commit on Pages Show definition »	read only
build_config object	Configs for the project build process `{ "build_command": "npm run build", "destination_dir": "build", "root_dir": "/", "web_analytics_tag": "cee1c73f6e4743d0b5e6bb1a0bcaabcc", "web_analytics_token": "021e1057c18547eca7b79f2516f06o7x" }` An object with the following properties: Show definition »
created_on string (date-time)	When the project was created `"2017-01-01T00:00:00Z"`	read only
deployment_configs object	Configs for deployments in a project { "preview": { "env_vars": { "BUILD_VERSION": { "value": "3.3" } }, "kv_namespaces": { "KV_BINDING": { "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3" } }, "durable_object_namespaces": { "DO_BINDING": { "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3" } }, "r2_buckets": { "R2_BINDING": { "name": "some-bucket" } }, "d1_databases": { "D1_BINDING": { "id": "445e2955-951a-43f8-a35b-a4d0c8138f63" } }, "compatibility_date": "2022-01-01", "compatibility_flags": [ "url_standard" ] }, "production": { "env_vars": { "BUILD_VERSION": { "value": "3.3" } }, "kv_namespaces": { "KV_BINDING": { "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3" } }, "durable_object_namespaces": { "DO_BINDING": { "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3" } }, "r2_buckets": { "R2_BINDING": { "name": "some-bucket" } }, "d1_databases": { "D1_BINDING": { "id": "445e2955-951a-43f8-a35b-a4d0c8138f63" } }, "compatibility_date": "2022-01-01", "compatibility_flags": [ "url_standard" ] } } An object with the following properties: Show definition »
source object	Configs for the project source `{ "type": "github", "config": { "owner": "cloudflare", "repo_name": "ninjakittens", "production_branch": "main", "pr_comments_enabled": true, "production_deployments_enabled": true, "preview_deployment_setting": "custom", "preview_branch_includes": [ "release/", "production", "main" ], "preview_branch_excludes": [ "dependabot/", "dev", "*/ignore" ] } }` An object with the following properties: Show definition »	read only
id string	Id of the project `"7b162ea7-7367-4d67-bcde-1160995d5"`	read only
latest_deployment	Most recent deployment to the repo `{}` One of the following: Show definition » A Pages deployment is a published build for a commit on Pages Show definition »	read only

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/pages/projects" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"NextJS Blog","id":"7b162ea7-7367-4d67-bcde-1160995d5","created_on":"2017-01-01T00:00:00Z","subdomain":"helloworld.pages.dev","domains":["customdomain.com","customdomain.org"],"source":{"type":"github","config":{"owner":"cloudflare","repo_name":"ninjakittens","production_branch":"main","pr_comments_enabled":true,"production_deployments_enabled":true,"preview_deployment_setting":"custom","preview_branch_includes":["release/*","production","main"],"preview_branch_excludes":["dependabot/*","dev","*/ignore"]}},"build_config":{"build_command":"npm run build","destination_dir":"build","root_dir":"/","web_analytics_tag":"cee1c73f6e4743d0b5e6bb1a0bcaabcc","web_analytics_token":"021e1057c18547eca7b79f2516f06o7x"},"deployment_configs":{"preview":{"env_vars":{"BUILD_VERSION":{"value":"3.3"}},"kv_namespaces":{"KV_BINDING":{"namespace_id":"5eb63bbbe01eeed093cb22bb8f5acdc3"}},"durable_object_namespaces":{"DO_BINDING":{"namespace_id":"5eb63bbbe01eeed093cb22bb8f5acdc3"}},"r2_buckets":{"R2_BINDING":{"name":"some-bucket"}},"d1_databases":{"D1_BINDING":{"id":"445e2955-951a-43f8-a35b-a4d0c8138f63"}},"compatibility_date":"2022-01-01","compatibility_flags":["url_standard"]},"production":{"env_vars":{"BUILD_VERSION":{"value":"3.3"}},"kv_namespaces":{"KV_BINDING":{"namespace_id":"5eb63bbbe01eeed093cb22bb8f5acdc3"}},"durable_object_namespaces":{"DO_BINDING":{"namespace_id":"5eb63bbbe01eeed093cb22bb8f5acdc3"}},"r2_buckets":{"R2_BINDING":{"name":"some-bucket"}},"d1_databases":{"D1_BINDING":{"id":"445e2955-951a-43f8-a35b-a4d0c8138f63"}},"compatibility_date":"2022-01-01","compatibility_flags":["url_standard"]}},"latest_deployment":{},"canonical_deployment":{},"production_branch":"main"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "name": "NextJS Blog",
    "id": "7b162ea7-7367-4d67-bcde-1160995d5",
    "created_on": "2017-01-01T00:00:00Z",
    "subdomain": "helloworld.pages.dev",
    "domains": [
      "customdomain.com",
      "customdomain.org"
    ],
    "source": {
      "type": "github",
      "config": {
        "owner": "cloudflare",
        "repo_name": "ninjakittens",
        "production_branch": "main",
        "pr_comments_enabled": true,
        "production_deployments_enabled": true,
        "preview_deployment_setting": "custom",
        "preview_branch_includes": [
          "release/*",
          "production",
          "main"
        ],
        "preview_branch_excludes": [
          "dependabot/*",
          "dev",
          "*/ignore"
        ]
      }
    },
    "build_config": {
      "build_command": "npm run build",
      "destination_dir": "build",
      "root_dir": "/",
      "web_analytics_tag": "cee1c73f6e4743d0b5e6bb1a0bcaabcc",
      "web_analytics_token": "021e1057c18547eca7b79f2516f06o7x"
    },
    "deployment_configs": {
      "preview": {
        "env_vars": {
          "BUILD_VERSION": {
            "value": "3.3"
          }
        },
        "kv_namespaces": {
          "KV_BINDING": {
            "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3"
          }
        },
        "durable_object_namespaces": {
          "DO_BINDING": {
            "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3"
          }
        },
        "r2_buckets": {
          "R2_BINDING": {
            "name": "some-bucket"
          }
        },
        "d1_databases": {
          "D1_BINDING": {
            "id": "445e2955-951a-43f8-a35b-a4d0c8138f63"
          }
        },
        "compatibility_date": "2022-01-01",
        "compatibility_flags": [
          "url_standard"
        ]
      },
      "production": {
        "env_vars": {
          "BUILD_VERSION": {
            "value": "3.3"
          }
        },
        "kv_namespaces": {
          "KV_BINDING": {
            "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3"
          }
        },
        "durable_object_namespaces": {
          "DO_BINDING": {
            "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3"
          }
        },
        "r2_buckets": {
          "R2_BINDING": {
            "name": "some-bucket"
          }
        },
        "d1_databases": {
          "D1_BINDING": {
            "id": "445e2955-951a-43f8-a35b-a4d0c8138f63"
          }
        },
        "compatibility_date": "2022-01-01",
        "compatibility_flags": [
          "url_standard"
        ]
      }
    },
    "latest_deployment": {},
    "canonical_deployment": {},
    "production_branch": "main"
  }
}

pages-project-update-project

PATCH Update project

Set new attributes for an existing project. Modify environment variables. To delete an environment variable, set the key to null.

PATCH accounts/:account_identifier/pages/projects/:project_name

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/pages/projects/this-is-my-project-01" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"deployment_configs":{"production":{"env_vars":{"delete_this_env_var":null,"BUILD_VERSION":{"value":"3.3"}},"compatibility_date":"2022-01-01","compatibility_flags":["url_standard"]}}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "name": "NextJS Blog",
    "id": "7b162ea7-7367-4d67-bcde-1160995d5",
    "created_on": "2017-01-01T00:00:00Z",
    "subdomain": "helloworld.pages.dev",
    "domains": [
      "customdomain.com",
      "customdomain.org"
    ],
    "source": {
      "type": "github",
      "config": {
        "owner": "cloudflare",
        "repo_name": "ninjakittens",
        "production_branch": "main",
        "pr_comments_enabled": true,
        "production_deployments_enabled": true,
        "preview_deployment_setting": "custom",
        "preview_branch_includes": [
          "release/*",
          "production",
          "main"
        ],
        "preview_branch_excludes": [
          "dependabot/*",
          "dev",
          "*/ignore"
        ]
      }
    },
    "build_config": {
      "build_command": "npm run build",
      "destination_dir": "build",
      "root_dir": "/",
      "web_analytics_tag": "cee1c73f6e4743d0b5e6bb1a0bcaabcc",
      "web_analytics_token": "021e1057c18547eca7b79f2516f06o7x"
    },
    "deployment_configs": {
      "preview": {
        "env_vars": {
          "BUILD_VERSION": {
            "value": "3.3"
          }
        },
        "kv_namespaces": {
          "KV_BINDING": {
            "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3"
          }
        },
        "durable_object_namespaces": {
          "DO_BINDING": {
            "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3"
          }
        },
        "r2_buckets": {
          "R2_BINDING": {
            "name": "some-bucket"
          }
        },
        "d1_databases": {
          "D1_BINDING": {
            "id": "445e2955-951a-43f8-a35b-a4d0c8138f63"
          }
        },
        "compatibility_date": "2022-01-01",
        "compatibility_flags": [
          "url_standard"
        ]
      },
      "production": {
        "env_vars": {
          "BUILD_VERSION": {
            "value": "3.3"
          }
        },
        "kv_namespaces": {
          "KV_BINDING": {
            "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3"
          }
        },
        "durable_object_namespaces": {
          "DO_BINDING": {
            "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3"
          }
        },
        "r2_buckets": {
          "R2_BINDING": {
            "name": "some-bucket"
          }
        },
        "d1_databases": {
          "D1_BINDING": {
            "id": "445e2955-951a-43f8-a35b-a4d0c8138f63"
          }
        },
        "compatibility_date": "2022-01-01",
        "compatibility_flags": [
          "url_standard"
        ]
      }
    },
    "latest_deployment": {},
    "canonical_deployment": {},
    "production_branch": "main"
  }
}

Pages Project error codes

Code	Description
8000000	An unknown error occurred
8000001	A project already exists for this repo
8000002	A project with this name already exists
8000003	Invalid project name
8000004	Account not authorized for the requested repo
8000005	Required field missing
8000006	Unable to parse request
8000007	Project not found
8000008	No installation found
8000009	Deployment not found
8000010	User is not authorized for provided GitHub Installation ID
8000011	User has no linked GitHub accounts matching the provided username
8000012	User has no linked GitHub repositories matching the provided name
8000013	Authorization failed
8000014	Deployment type not found
8000015	Domain is invalid
8000016	Unicode domains are not supported
8000017	An operation is already in progress for this domain
8000018	Domain is unavailable
8000019	Project has reached the maximum number of allowed domains
8000020	No deployment stage found for the provided name
8000021	Domain not found
8000022	Invalid PATCH operation requested
8000023	Attempt to add duplicate environment variable, or replace or delete nonexistent variable
8000024	Invalid list options provided
8000025	Domain is not registered
8000026	Coming soon
8000027	Too many projects
8000028	Must delete custom domains before deleting project
8000029	Subdomain is unavailable
8000030	Subdomain is blocked
8000031	Unable to cancel completed deployment
8000032	Unable to find a branch with the provided name
8000033	Production branch must be set
8000034	Cannot delete active production deployment
8000035	Cannot delete aliased deployment
8000036	Account has been blocked
8000037	Invalid values for BuildConfig
8000038	Cannot rollback to a failed deployment
8000039	Deployment is currently in production
8000040	Cannot rollback to a preview deployment
8000041	Project assigned unexpected subdomain
8000042	The specified build candidate has already been promoted
8000043	Another build candidate has already been promoted
8000044	Deploy hook not found
8000045	Invalid deploy hook ID. Please use the UUID for the hook.
8000046	Provider not found
8000047	Functions configuration not found
8000048	Build metadata not found
8000049	Invalid deploy hook name
8000050	The associated Source Control Management account has been blocked
8000051	Invalid branch config
8000052	File is too large (> 25 MiB)
8000053	Build not found
8000054	Build is not running
8000055	Can't retry direct upload deployments
8000056	Can't rotate kv namespace if there is an ongoing deployment
8000057	Invalid _routes.json
8000058	Commit hash (sha) length must not exceed 64 characters

Pages Deployment

A Pages deployment is a published build for a commit on Pages

For more detailed documentation on using the API for Pages see the Pages docs.

pages-deployment

Object definition

View properties and constraints defined on the object

Show definition

pages-deployment-get-deployments

GET Get deployments

Fetch a list of deployments from a project

GET accounts/:account_identifier/pages/projects/:project_name/deployments

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/pages/projects/this-is-my-project-01/deployments" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f64788e9-fccd-4d4a-a28a-cb84f88f6",
      "short_id": "f64788e9",
      "project_id": "7b162ea7-7367-4d67-bcde-1160995d5",
      "project_name": "ninjakittens",
      "environment": "preview",
      "url": "https://f64788e9.ninjakittens.pages.dev",
      "created_on": "2021-03-09T00:55:03.923456Z",
      "modified_on": "2021-03-09T00:58:59.045655",
      "aliases": [
        "https://branchname.projectname.pages.dev"
      ],
      "is_skipped": true,
      "latest_stage": {
        "name": "deploy",
        "started_on": "2021-03-09T00:55:03.923456Z",
        "ended_on": "2021-03-09T00:58:59.045655",
        "status": "success"
      },
      "env_vars": {
        "BUILD_VERSION": {
          "value": "3.3"
        },
        "ENV": {
          "value": "STAGING"
        }
      },
      "deployment_trigger": {
        "type": "ad_hoc",
        "metadata": {
          "branch": "main",
          "commit_hash": "ad9ccd918a81025731e10e40267e11273a263421",
          "commit_message": "Update index.html"
        }
      },
      "stages": [
        {
          "name": "queued",
          "started_on": "2021-06-03T15:38:15.608194Z",
          "ended_on": "2021-06-03T15:39:03.134378Z",
          "status": "active"
        },
        {
          "name": "initialize",
          "started_on": null,
          "ended_on": null,
          "status": "idle"
        },
        {
          "name": "clone_repo",
          "started_on": null,
          "ended_on": null,
          "status": "idle"
        },
        {
          "name": "build",
          "started_on": null,
          "ended_on": null,
          "status": "idle"
        },
        {
          "name": "deploy",
          "started_on": null,
          "ended_on": null,
          "status": "idle"
        }
      ],
      "build_config": {
        "build_command": "npm run build",
        "destination_dir": "build",
        "root_dir": "/",
        "web_analytics_tag": "cee1c73f6e4743d0b5e6bb1a0bcaabcc",
        "web_analytics_token": "021e1057c18547eca7b79f2516f06o7x"
      },
      "source": {
        "type": "github",
        "config": {
          "owner": "cloudflare",
          "repo_name": "ninjakittens",
          "production_branch": "main",
          "pr_comments_enabled": true,
          "production_deployments_enabled": true,
          "preview_deployment_setting": "custom",
          "preview_branch_includes": [
            "release/*",
            "production",
            "main"
          ],
          "preview_branch_excludes": [
            "dependabot/*",
            "dev",
            "*/ignore"
          ]
        }
      }
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 100,
    "count": 1,
    "total_count": 1
  }
}

pages-deployment-get-deployment-info

GET Get deployment info

Fetch a deployment

GET accounts/:account_identifier/pages/projects/:project_name/deployments/:deployment_identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/pages/projects/this-is-my-project-01/deployments/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f64788e9-fccd-4d4a-a28a-cb84f88f6",
    "short_id": "f64788e9",
    "project_id": "7b162ea7-7367-4d67-bcde-1160995d5",
    "project_name": "ninjakittens",
    "environment": "preview",
    "url": "https://f64788e9.ninjakittens.pages.dev",
    "created_on": "2021-03-09T00:55:03.923456Z",
    "modified_on": "2021-03-09T00:58:59.045655",
    "aliases": [
      "https://branchname.projectname.pages.dev"
    ],
    "is_skipped": true,
    "latest_stage": {
      "name": "deploy",
      "started_on": "2021-03-09T00:55:03.923456Z",
      "ended_on": "2021-03-09T00:58:59.045655",
      "status": "success"
    },
    "env_vars": {
      "BUILD_VERSION": {
        "value": "3.3"
      },
      "ENV": {
        "value": "STAGING"
      }
    },
    "deployment_trigger": {
      "type": "ad_hoc",
      "metadata": {
        "branch": "main",
        "commit_hash": "ad9ccd918a81025731e10e40267e11273a263421",
        "commit_message": "Update index.html"
      }
    },
    "stages": [
      {
        "name": "queued",
        "started_on": "2021-06-03T15:38:15.608194Z",
        "ended_on": "2021-06-03T15:39:03.134378Z",
        "status": "active"
      },
      {
        "name": "initialize",
        "started_on": null,
        "ended_on": null,
        "status": "idle"
      },
      {
        "name": "clone_repo",
        "started_on": null,
        "ended_on": null,
        "status": "idle"
      },
      {
        "name": "build",
        "started_on": null,
        "ended_on": null,
        "status": "idle"
      },
      {
        "name": "deploy",
        "started_on": null,
        "ended_on": null,
        "status": "idle"
      }
    ],
    "build_config": {
      "build_command": "npm run build",
      "destination_dir": "build",
      "root_dir": "/",
      "web_analytics_tag": "cee1c73f6e4743d0b5e6bb1a0bcaabcc",
      "web_analytics_token": "021e1057c18547eca7b79f2516f06o7x"
    },
    "source": {
      "type": "github",
      "config": {
        "owner": "cloudflare",
        "repo_name": "ninjakittens",
        "production_branch": "main",
        "pr_comments_enabled": true,
        "production_deployments_enabled": true,
        "preview_deployment_setting": "custom",
        "preview_branch_includes": [
          "release/*",
          "production",
          "main"
        ],
        "preview_branch_excludes": [
          "dependabot/*",
          "dev",
          "*/ignore"
        ]
      }
    }
  }
}

Deprecation Warning

End of life Date: September 19, 2022

Use "Get deployment logs" instead: https://api.cloudflare.com/#pages-deployment-get-deployment-logs.

pages-deployment-get-deployment-stage-logs

GET Get deployment stage logs

Fetch deploy logs

GET accounts/:account_identifier/pages/projects/:project_name/deployments/:deployment_identifier/history/:deployment_stage_name/logs

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/pages/projects/this-is-my-project-01/deployments/9a7806061c88ada191ed06f989cc3dac/history/deploy/logs" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "name": "build",
    "started_on": "2021-04-20T19:35:58.238757Z",
    "ended_on": "2021-04-20T19:36:06.38889Z",
    "status": "success",
    "start": 0,
    "end": 37,
    "total": 37,
    "data": [
      {
        "id": 15,
        "timestamp": "2021-04-20T19:35:59.0749819Z",
        "message": "Installing dependencies"
      },
      {
        "id": 16,
        "timestamp": "2021-04-20T19:35:59.0931208Z",
        "message": "Python version set to 2.7"
      },
      {
        "id": 17,
        "timestamp": "2021-04-20T19:36:02.2369501Z",
        "message": "v12.18.0 is already installed."
      },
      {
        "id": 18,
        "timestamp": "2021-04-20T19:36:02.6028886Z",
        "message": "Now using node v12.18.0 (npm v6.14.4)"
      },
      {
        "id": 19,
        "timestamp": "2021-04-20T19:36:02.624555Z",
        "message": "Started restoring cached build plugins"
      },
      {
        "id": 20,
        "timestamp": "2021-04-20T19:36:02.6340688Z",
        "message": "Finished restoring cached build plugins"
      },
      {
        "id": 21,
        "timestamp": "2021-04-20T19:36:02.963095Z",
        "message": "Attempting ruby version 2.7.1, read from environment"
      },
      {
        "id": 22,
        "timestamp": "2021-04-20T19:36:04.2236084Z",
        "message": "Using ruby version 2.7.1"
      },
      {
        "id": 23,
        "timestamp": "2021-04-20T19:36:04.5450152Z",
        "message": "Using PHP version 5.6"
      },
      {
        "id": 24,
        "timestamp": "2021-04-20T19:36:04.5740509Z",
        "message": "5.2 is already installed."
      },
      {
        "id": 25,
        "timestamp": "2021-04-20T19:36:04.577035Z",
        "message": "Using Swift version 5.2"
      },
      {
        "id": 26,
        "timestamp": "2021-04-20T19:36:04.5771615Z",
        "message": "Installing Hugo 0.54.0"
      },
      {
        "id": 27,
        "timestamp": "2021-04-20T19:36:05.4786868Z",
        "message": "Hugo Static Site Generator v0.54.0-B1A82C61A/extended linux/amd64 BuildDate: 2019-02-01T10:04:38Z"
      },
      {
        "id": 28,
        "timestamp": "2021-04-20T19:36:05.4794366Z",
        "message": "Started restoring cached go cache"
      },
      {
        "id": 29,
        "timestamp": "2021-04-20T19:36:05.481977Z",
        "message": "Finished restoring cached go cache"
      },
      {
        "id": 30,
        "timestamp": "2021-04-20T19:36:05.9049776Z",
        "message": "go version go1.14.4 linux/amd64"
      },
      {
        "id": 31,
        "timestamp": "2021-04-20T19:36:05.9086053Z",
        "message": "go version go1.14.4 linux/amd64"
      },
      {
        "id": 32,
        "timestamp": "2021-04-20T19:36:05.9163568Z",
        "message": "Installing missing commands"
      },
      {
        "id": 33,
        "timestamp": "2021-04-20T19:36:05.9163934Z",
        "message": "Verify run directory"
      },
      {
        "id": 34,
        "timestamp": "2021-04-20T19:36:05.9164636Z",
        "message": "Executing user command: echo \"skipping build step: no build command specified\""
      },
      {
        "id": 35,
        "timestamp": "2021-04-20T19:36:05.9165087Z",
        "message": "skipping build step: no build command specified"
      },
      {
        "id": 36,
        "timestamp": "2021-04-20T19:36:05.917412Z",
        "message": "Finished"
      }
    ]
  }
}

pages-deployment-get-deployment-logs

GET Get deployment logs

Fetch deploy logs

GET accounts/:account_identifier/pages/projects/:project_name/deployments/:deployment_identifier/history/logs

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/pages/projects/this-is-my-project-01/deployments/9a7806061c88ada191ed06f989cc3dac/history/logs" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "total": 30,
    "includes_container_logs": true,
    "data": [
      {
        "ts": "2021-04-20T19:35:29.0749819Z",
        "line": "Cloning repository..."
      },
      {
        "ts": "2021-04-20T19:35:30.0749819Z",
        "line": "From https://github.com/cloudflare/example"
      },
      {
        "ts": "2021-04-20T19:35:30.0749819Z",
        "line": " * branch            209c5bb11d89533f426b2f8469bcae12fdccf71b -> FETCH_HEAD"
      },
      {
        "ts": "2021-04-20T19:35:30.0749819Z",
        "line": ""
      },
      {
        "ts": "2021-04-20T19:35:30.0749819Z",
        "line": "HEAD is now at 209c5bb Update index.html"
      },
      {
        "ts": "2021-04-20T19:35:30.0749819Z",
        "line": ""
      },
      {
        "ts": "2021-04-20T19:35:30.0749819Z",
        "line": ""
      },
      {
        "ts": "2021-04-20T19:35:30.0749819Z",
        "line": "Success: Finished cloning repository files"
      },
      {
        "ts": "2021-04-20T19:35:59.0749819Z",
        "line": "Installing dependencies"
      },
      {
        "ts": "2021-04-20T19:35:59.0931208Z",
        "line": "Python version set to 2.7"
      },
      {
        "ts": "2021-04-20T19:36:02.2369501Z",
        "line": "v12.18.0 is already installed."
      },
      {
        "ts": "2021-04-20T19:36:02.6028886Z",
        "line": "Now using node v12.18.0 (npm v6.14.4)"
      },
      {
        "ts": "2021-04-20T19:36:02.624555Z",
        "line": "Started restoring cached build plugins"
      },
      {
        "ts": "2021-04-20T19:36:02.6340688Z",
        "line": "Finished restoring cached build plugins"
      },
      {
        "ts": "2021-04-20T19:36:02.963095Z",
        "line": "Attempting ruby version 2.7.1, read from environment"
      },
      {
        "ts": "2021-04-20T19:36:04.2236084Z",
        "line": "Using ruby version 2.7.1"
      },
      {
        "ts": "2021-04-20T19:36:04.5450152Z",
        "line": "Using PHP version 5.6"
      },
      {
        "ts": "2021-04-20T19:36:04.5740509Z",
        "line": "5.2 is already installed."
      },
      {
        "ts": "2021-04-20T19:36:04.577035Z",
        "line": "Using Swift version 5.2"
      },
      {
        "ts": "2021-04-20T19:36:04.5771615Z",
        "line": "Installing Hugo 0.54.0"
      },
      {
        "ts": "2021-04-20T19:36:05.4786868Z",
        "line": "Hugo Static Site Generator v0.54.0-B1A82C61A/extended linux/amd64 BuildDate: 2019-02-01T10:04:38Z"
      },
      {
        "ts": "2021-04-20T19:36:05.4794366Z",
        "line": "Started restoring cached go cache"
      },
      {
        "ts": "2021-04-20T19:36:05.481977Z",
        "line": "Finished restoring cached go cache"
      },
      {
        "ts": "2021-04-20T19:36:05.9049776Z",
        "line": "go version go1.14.4 linux/amd64"
      },
      {
        "ts": "2021-04-20T19:36:05.9086053Z",
        "line": "go version go1.14.4 linux/amd64"
      },
      {
        "ts": "2021-04-20T19:36:05.9163568Z",
        "line": "Installing missing commands"
      },
      {
        "ts": "2021-04-20T19:36:05.9163934Z",
        "line": "Verify run directory"
      },
      {
        "ts": "2021-04-20T19:36:05.9164636Z",
        "line": "Executing user command: echo \"skipping build step: no build command specified\""
      },
      {
        "ts": "2021-04-20T19:36:05.9165087Z",
        "line": "skipping build step: no build command specified"
      },
      {
        "ts": "2021-04-20T19:36:05.917412Z",
        "line": "Finished"
      }
    ]
  }
}

pages-deployment-delete-deployment

DELETE Delete deployment

Destroy a deployment

DELETE accounts/:account_identifier/pages/projects/:project_name/deployments/:deployment_identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/pages/projects/this-is-my-project-01/deployments/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

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

pages-deployment-create-deployment

POST Create deployment

Start a new deployment from production. The repo/account must have been authorized through the Pages UI dash before.

POST accounts/:account_identifier/pages/projects/:project_name/deployments

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/pages/projects/this-is-my-project-01/deployments" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f64788e9-fccd-4d4a-a28a-cb84f88f6",
    "short_id": "f64788e9",
    "project_id": "7b162ea7-7367-4d67-bcde-1160995d5",
    "project_name": "ninjakittens",
    "environment": "preview",
    "url": "https://f64788e9.ninjakittens.pages.dev",
    "created_on": "2021-03-09T00:55:03.923456Z",
    "modified_on": "2021-03-09T00:58:59.045655",
    "aliases": [
      "https://branchname.projectname.pages.dev"
    ],
    "is_skipped": true,
    "latest_stage": {
      "name": "deploy",
      "started_on": "2021-03-09T00:55:03.923456Z",
      "ended_on": "2021-03-09T00:58:59.045655",
      "status": "success"
    },
    "env_vars": {
      "BUILD_VERSION": {
        "value": "3.3"
      },
      "ENV": {
        "value": "STAGING"
      }
    },
    "deployment_trigger": {
      "type": "ad_hoc",
      "metadata": {
        "branch": "main",
        "commit_hash": "ad9ccd918a81025731e10e40267e11273a263421",
        "commit_message": "Update index.html"
      }
    },
    "stages": [
      {
        "name": "queued",
        "started_on": "2021-06-03T15:38:15.608194Z",
        "ended_on": "2021-06-03T15:39:03.134378Z",
        "status": "active"
      },
      {
        "name": "initialize",
        "started_on": null,
        "ended_on": null,
        "status": "idle"
      },
      {
        "name": "clone_repo",
        "started_on": null,
        "ended_on": null,
        "status": "idle"
      },
      {
        "name": "build",
        "started_on": null,
        "ended_on": null,
        "status": "idle"
      },
      {
        "name": "deploy",
        "started_on": null,
        "ended_on": null,
        "status": "idle"
      }
    ],
    "build_config": {
      "build_command": "npm run build",
      "destination_dir": "build",
      "root_dir": "/",
      "web_analytics_tag": "cee1c73f6e4743d0b5e6bb1a0bcaabcc",
      "web_analytics_token": "021e1057c18547eca7b79f2516f06o7x"
    },
    "source": {
      "type": "github",
      "config": {
        "owner": "cloudflare",
        "repo_name": "ninjakittens",
        "production_branch": "main",
        "pr_comments_enabled": true,
        "production_deployments_enabled": true,
        "preview_deployment_setting": "custom",
        "preview_branch_includes": [
          "release/*",
          "production",
          "main"
        ],
        "preview_branch_excludes": [
          "dependabot/*",
          "dev",
          "*/ignore"
        ]
      }
    }
  }
}

pages-deployment-retry-deployment

POST Retry deployment

Retry a previous deployment

POST accounts/:account_identifier/pages/projects/:project_name/deployments/:deployment_identifier/retry

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/pages/projects/this-is-my-project-01/deployments/9a7806061c88ada191ed06f989cc3dac/retry" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f64788e9-fccd-4d4a-a28a-cb84f88f6",
    "short_id": "f64788e9",
    "project_id": "7b162ea7-7367-4d67-bcde-1160995d5",
    "project_name": "ninjakittens",
    "environment": "preview",
    "url": "https://f64788e9.ninjakittens.pages.dev",
    "created_on": "2021-03-09T00:55:03.923456Z",
    "modified_on": "2021-03-09T00:58:59.045655",
    "aliases": [
      "https://branchname.projectname.pages.dev"
    ],
    "is_skipped": true,
    "latest_stage": {
      "name": "deploy",
      "started_on": "2021-03-09T00:55:03.923456Z",
      "ended_on": "2021-03-09T00:58:59.045655",
      "status": "success"
    },
    "env_vars": {
      "BUILD_VERSION": {
        "value": "3.3"
      },
      "ENV": {
        "value": "STAGING"
      }
    },
    "deployment_trigger": {
      "type": "ad_hoc",
      "metadata": {
        "branch": "main",
        "commit_hash": "ad9ccd918a81025731e10e40267e11273a263421",
        "commit_message": "Update index.html"
      }
    },
    "stages": [
      {
        "name": "queued",
        "started_on": "2021-06-03T15:38:15.608194Z",
        "ended_on": "2021-06-03T15:39:03.134378Z",
        "status": "active"
      },
      {
        "name": "initialize",
        "started_on": null,
        "ended_on": null,
        "status": "idle"
      },
      {
        "name": "clone_repo",
        "started_on": null,
        "ended_on": null,
        "status": "idle"
      },
      {
        "name": "build",
        "started_on": null,
        "ended_on": null,
        "status": "idle"
      },
      {
        "name": "deploy",
        "started_on": null,
        "ended_on": null,
        "status": "idle"
      }
    ],
    "build_config": {
      "build_command": "npm run build",
      "destination_dir": "build",
      "root_dir": "/",
      "web_analytics_tag": "cee1c73f6e4743d0b5e6bb1a0bcaabcc",
      "web_analytics_token": "021e1057c18547eca7b79f2516f06o7x"
    },
    "source": {
      "type": "github",
      "config": {
        "owner": "cloudflare",
        "repo_name": "ninjakittens",
        "production_branch": "main",
        "pr_comments_enabled": true,
        "production_deployments_enabled": true,
        "preview_deployment_setting": "custom",
        "preview_branch_includes": [
          "release/*",
          "production",
          "main"
        ],
        "preview_branch_excludes": [
          "dependabot/*",
          "dev",
          "*/ignore"
        ]
      }
    }
  }
}

pages-deployment-rollback-deployment

POST Rollback deployment

Rollback the production deployment to a previous deploy. You can only rollback to succesful builds on production.

POST accounts/:account_identifier/pages/projects/:project_name/deployments/:deployment_identifier/rollback

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/pages/projects/this-is-my-project-01/deployments/9a7806061c88ada191ed06f989cc3dac/rollback" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f64788e9-fccd-4d4a-a28a-cb84f88f6",
    "short_id": "f64788e9",
    "project_id": "7b162ea7-7367-4d67-bcde-1160995d5",
    "project_name": "ninjakittens",
    "environment": "preview",
    "url": "https://f64788e9.ninjakittens.pages.dev",
    "created_on": "2021-03-09T00:55:03.923456Z",
    "modified_on": "2021-03-09T00:58:59.045655",
    "aliases": [
      "https://branchname.projectname.pages.dev"
    ],
    "is_skipped": true,
    "latest_stage": {
      "name": "deploy",
      "started_on": "2021-03-09T00:55:03.923456Z",
      "ended_on": "2021-03-09T00:58:59.045655",
      "status": "success"
    },
    "env_vars": {
      "BUILD_VERSION": {
        "value": "3.3"
      },
      "ENV": {
        "value": "STAGING"
      }
    },
    "deployment_trigger": {
      "type": "ad_hoc",
      "metadata": {
        "branch": "main",
        "commit_hash": "ad9ccd918a81025731e10e40267e11273a263421",
        "commit_message": "Update index.html"
      }
    },
    "stages": [
      {
        "name": "queued",
        "started_on": "2021-06-03T15:38:15.608194Z",
        "ended_on": "2021-06-03T15:39:03.134378Z",
        "status": "active"
      },
      {
        "name": "initialize",
        "started_on": null,
        "ended_on": null,
        "status": "idle"
      },
      {
        "name": "clone_repo",
        "started_on": null,
        "ended_on": null,
        "status": "idle"
      },
      {
        "name": "build",
        "started_on": null,
        "ended_on": null,
        "status": "idle"
      },
      {
        "name": "deploy",
        "started_on": null,
        "ended_on": null,
        "status": "idle"
      }
    ],
    "build_config": {
      "build_command": "npm run build",
      "destination_dir": "build",
      "root_dir": "/",
      "web_analytics_tag": "cee1c73f6e4743d0b5e6bb1a0bcaabcc",
      "web_analytics_token": "021e1057c18547eca7b79f2516f06o7x"
    },
    "source": {
      "type": "github",
      "config": {
        "owner": "cloudflare",
        "repo_name": "ninjakittens",
        "production_branch": "main",
        "pr_comments_enabled": true,
        "production_deployments_enabled": true,
        "preview_deployment_setting": "custom",
        "preview_branch_includes": [
          "release/*",
          "production",
          "main"
        ],
        "preview_branch_excludes": [
          "dependabot/*",
          "dev",
          "*/ignore"
        ]
      }
    }
  }
}

Pages Deployment error codes

Code	Description
8000000	An unknown error occurred
8000001	A project already exists for this repo
8000002	A project with this name already exists
8000003	Invalid project name
8000004	Account not authorized for the requested repo
8000005	Required field missing
8000006	Unable to parse request
8000007	Project not found
8000008	No installation found
8000009	Deployment not found
8000010	User is not authorized for provided GitHub Installation ID
8000011	User has no linked GitHub accounts matching the provided username
8000012	User has no linked GitHub repositories matching the provided name
8000013	Authorization failed
8000014	Deployment type not found
8000015	Domain is invalid
8000016	Unicode domains are not supported
8000017	An operation is already in progress for this domain
8000018	Domain is unavailable
8000019	Project has reached the maximum number of allowed domains
8000020	No deployment stage found for the provided name
8000021	Domain not found
8000022	Invalid PATCH operation requested
8000023	Attempt to add duplicate environment variable, or replace or delete nonexistent variable
8000024	Invalid list options provided
8000025	Domain is not registered
8000026	Coming soon
8000027	Too many projects
8000028	Must delete custom domains before deleting project
8000029	Subdomain is unavailable
8000030	Subdomain is blocked
8000031	Unable to cancel completed deployment
8000032	Unable to find a branch with the provided name
8000033	Production branch must be set
8000034	Cannot delete active production deployment
8000035	Cannot delete aliased deployment
8000036	Account has been blocked

Pages Domains

A domain represents a custom domain tied to a Pages project.

For more detailed documentation on using the API for Pages see the Pages docs.

pages-domains

Object definition

View properties and constraints defined on the object

Show definition

pages-domains-get-domains

GET Get domains

Fetch a list of all domains

GET accounts/:account_identifier/pages/projects/:project_name/domains

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/pages/projects/this-is-my-project-01/domains" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "8232210c-6818-4e34-8d95-cc386874b8d2",
      "name": "example.com",
      "status": "pending",
      "verification_data": {
        "status": "active"
      },
      "validation_data": {
        "status": "active",
        "method": "http"
      },
      "zone_tag": "023e105f4ecef8ad9ca31a8372d0c353",
      "created_on": "2017-01-01T00:00:00Z"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 100,
    "count": 1,
    "total_count": 1
  }
}

pages-domains-add-domain

POST Add domain

Add a new domain for the Pages project

POST accounts/:account_identifier/pages/projects/:project_name/domains

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/pages/projects/this-is-my-project-01/domains" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     --data '{"name":"example.com"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "8232210c-6818-4e34-8d95-cc386874b8d2",
    "name": "example.com",
    "status": "pending",
    "verification_data": {
      "status": "active"
    },
    "validation_data": {
      "status": "active",
      "method": "http"
    },
    "zone_tag": "023e105f4ecef8ad9ca31a8372d0c353",
    "created_on": "2017-01-01T00:00:00Z"
  }
}

pages-domains-get-domain

GET Get domain

Fetch a single domain

GET accounts/:account_identifier/pages/projects/:project_name/domains/:domain_name

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/pages/projects/this-is-my-project-01/domains/this-is-my-domain-01.com" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "8232210c-6818-4e34-8d95-cc386874b8d2",
    "name": "example.com",
    "status": "pending",
    "verification_data": {
      "status": "active"
    },
    "validation_data": {
      "status": "active",
      "method": "http"
    },
    "zone_tag": "023e105f4ecef8ad9ca31a8372d0c353",
    "created_on": "2017-01-01T00:00:00Z"
  }
}

pages-domains-patch-domain

PATCH Patch domain

Retry the validation status of a single domain

PATCH accounts/:account_identifier/pages/projects/:project_name/domains/:domain_name

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/pages/projects/this-is-my-project-01/domains/this-is-my-domain-01.com" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "8232210c-6818-4e34-8d95-cc386874b8d2",
    "name": "example.com",
    "status": "pending",
    "verification_data": {
      "status": "active"
    },
    "validation_data": {
      "status": "active",
      "method": "http"
    },
    "zone_tag": "023e105f4ecef8ad9ca31a8372d0c353",
    "created_on": "2017-01-01T00:00:00Z"
  }
}

pages-domains-delete-domain

DELETE Delete domain

Delete a domain

DELETE accounts/:account_identifier/pages/projects/:project_name/domains/:domain_name

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/pages/projects/this-is-my-project-01/domains/this-is-my-domain-01.com" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

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

Pages Domains error codes

Code	Description
8000000	An unknown error occurred
8000001	A project already exists for this repo
8000002	A project with this name already exists
8000003	Invalid project name
8000004	Account not authorized for the requested repo
8000005	Required field missing
8000006	Unable to parse request
8000007	Project not found
8000008	No installation found
8000009	Deployment not found
8000010	User is not authorized for provided GitHub Installation ID
8000011	User has no linked GitHub accounts matching the provided username
8000012	User has no linked GitHub repositories matching the provided name
8000013	Authorization failed
8000014	Deployment type not found
8000015	Domain is invalid
8000016	Unicode domains are not supported
8000017	An operation is already in progress for this domain
8000018	Domain is unavailable
8000019	Project has reached the maximum number of allowed domains
8000020	No deployment stage found for the provided name
8000021	Domain not found
8000022	Invalid PATCH operation requested
8000023	Attempt to add duplicate environment variable, or replace or delete nonexistent variable
8000024	Invalid list options provided
8000025	Domain is not registered
8000026	Coming soon
8000027	Too many projects
8000028	Must delete custom domains before deleting project
8000029	Subdomain is unavailable
8000030	Subdomain is blocked
8000031	Unable to cancel completed deployment
8000032	Unable to find a branch with the provided name
8000033	Production branch must be set
8000034	Cannot delete active production deployment
8000035	Cannot delete aliased deployment
8000036	Account has been blocked

R2 Bucket

A bucket is a container for objects stored in R2 Storage.

For more detailed documentation on using the In-Worker API or S3 Compatible APIs for R2 see the Runtime APIs or S3 Compatibility APIs.

r2-bucket

Object definition

View properties and constraints defined on the object

Show definition

r2-bucket-create-bucket

POST Create Bucket permission needed: com.cloudflare.edge.r2.bucket.create

Creates a new R2 bucket.

POST accounts/:account_identifier/r2/buckets

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/r2/buckets" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '"{'name': 'example-bucket'}"'

Response (example)

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

r2-bucket-delete-bucket

DELETE Delete Bucket permission needed: com.cloudflare.edge.r2.bucket.delete

Deletes an existing R2 bucket.

DELETE accounts/:account_identifier/r2/buckets/:bucket_name

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/r2/buckets/example-bucket" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

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

R2 Bucket error codes

Code	Description
10001	An unknown internal error occurred.
10002	The user is unauthorized to perform this operation.
10003	The user does not have permissions to perform this operation.
10004	The bucket already exists.
10005	The bucket name is invalid.
10006	The bucket does not exist.
10008	The bucket is not empty.
10009	The user has hit the maximum number of buckets for their account.
10017	The account specified is not valid.
10042	The account is not entitled to use R2.
10043	The service is unavailable.

Worker Script

A Worker script is a single script that is executed on matching routes in the Cloudflare edge

For more detailed documentation on using the API for Workers see the Workers API.

worker-script

Object definition

View properties and constraints defined on the object

Show definition

worker-script-upload-worker

PUT Upload Worker permission needed: com.cloudflare.edge.worker.script.create

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: user@example.com" \
     -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,
    "usage_model": "unbound",
    "modified_on": "2017-01-01T00:00:00Z"
  }
}

worker-script-upload-worker-module

PUT Upload Worker Module permission needed: com.cloudflare.edge.worker.script.create

Upload a worker module.

PUT accounts/:account_identifier/workers/scripts/:script_name

Optional parameters

Name /type	Description /example	Constraints
metadata string	Metadata for script such as bindings. Main module needs to be specified with `main_module`. `"{\"main_module\": \"worker.js\", \"some_binding\": \"stuff\"}"`
"worker.js" string	Worker script `"@worker.js;type=application/javascript+module"`
"second-file.js" string	Worker script `"@second-file.js;type=application/javascript+module"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/scripts/this-is_my_script-01" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: multipart/form-data" \
     --form 'metadata={"main_module": "worker.js", "some_binding": "stuff"}' \
     --form '"worker.js"=@worker.js;type=application/javascript+module' \
     --form '"second-file.js"=@second-file.js;type=application/javascript+module'

Response (example)

{
  "result": {
    "id": "this-is_my_script-01",
    "etag": "777f24a43bef5f69174aa69ceaf1dea67968d510a31d1vw3e49d34a0187c06d1",
    "handlers": [
      "fetch"
    ],
    "modified_on": "2022-05-20T19:02:56.446492Z",
    "created_on": "2022-05-05T05:15:11.602148Z",
    "usage_model": "bundled"
  },
  "success": true,
  "errors": [],
  "messages": []
}

worker-script-list-workers

GET List Workers permission needed: com.cloudflare.edge.worker.script.list

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "this-is_my_script-01",
      "etag": "ea95132c15732412d22c1476fa83f27a",
      "usage_model": "unbound",
      "created_on": "2017-01-01T00:00:00Z",
      "modified_on": "2017-01-01T00:00:00Z"
    }
  ]
}

worker-script-download-worker

GET Download Worker permission needed: com.cloudflare.edge.worker.script.read

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: user@example.com" \
     -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 permission needed: com.cloudflare.edge.worker.script.delete

Delete your worker. This call has no response body on a successful delete.

Query paramaters:

force: boolean; If set to true, delete will not be stopped by associated service binding, durable object, or other binding. Any of these associated bindings/durable objects will be deleted along with the script.

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

worker-script-update-usage-model

PUT Update Usage Model permission needed: com.cloudflare.edge.worker.script.create

Updates the Usage Model for a given Worker. Requires a Workers Paid subscription.

PUT accounts/:account_identifier/workers/scripts/:script_name/usage-model

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/scripts/this-is_my_script-01/usage-model" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     --data '"{'usage_model': 'unbound'}"'

Response (example)

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

worker-script-fetch-usage-model

GET Fetch Usage Model permission needed: com.cloudflare.edge.worker.script.read

Fetches the Usage Model for a given Worker.

GET accounts/:account_identifier/workers/scripts/:script_name/usage-model

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/scripts/this-is_my_script-01/usage-model" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

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

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
10075	Requires a Workers Paid plan

Worker Routes

Routes are basic patterns used to enable or disable workers that match requests.

For more detailed documentation on using the API for Workers see the Workers API.

worker-routes

Object definition

View properties and constraints defined on the object

Show definition

worker-routes-create-route

POST Create Route permission needed: com.cloudflare.edge.worker.route.create

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: user@example.com" \
     -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-list-routes

GET List Routes permission needed: com.cloudflare.edge.worker.route.list

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: user@example.com" \
     -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-get-route

GET Get Route permission needed: com.cloudflare.edge.worker.route.read

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: user@example.com" \
     -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-update-route

PUT Update Route permission needed: com.cloudflare.edge.worker.route.update

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: user@example.com" \
     -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-delete-route

DELETE Delete Route permission needed: com.cloudflare.edge.worker.route.delete

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

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

Worker Routes 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 permission needed: com.cloudflare.edge.storage.kv.namespace.list

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:100
order	Field to order results by `"id"`	valid values: id, title
direction	Direction to order namespaces `"asc"`	valid values: asc, desc

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/storage/kv/namespaces?page=1&per_page=20&order=id&direction=asc" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "0f2ac74b498b48028cb68387c421e279",
      "title": "My Own Namespace",
      "supports_url_encoding": true
    }
  ]
}

workers-kv-namespace-create-a-namespace

POST Create a Namespace permission needed: com.cloudflare.edge.storage.kv.namespace.create

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: user@example.com" \
     -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",
    "supports_url_encoding": true
  }
}

workers-kv-namespace-remove-a-namespace

DELETE Remove a Namespace permission needed: com.cloudflare.edge.storage.kv.namespace.delete

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

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

workers-kv-namespace-rename-a-namespace

PUT Rename a Namespace permission needed: com.cloudflare.edge.storage.kv.namespace.delete

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: user@example.com" \
     -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 permission needed: com.cloudflare.edge.storage.kv.key.list

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"`
prefix string	A string prefix used to filter down which keys will be returned. Exact matches and any key names that begin with the prefix will be returned. `"My-Prefix"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/storage/kv/namespaces/0f2ac74b498b48028cb68387c421e279/keys?limit=1000&cursor=6Ck1la0VxJ0djhidm1MdX2FyDGxLKVeeHZZmORS_8XeSuhz9SjIJRaSa2lnsF01tQOHrfTGAP3R5X1Kv5iVUuMbNKhWNAXHOl6ePB0TUL8nw&prefix=My-Prefix" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "name": "My-Key",
      "expiration": 1577836800,
      "metadata": {
        "someMetadataKey": "someMetadataValue"
      }
    }
  ],
  "result_info": {
    "count": 1,
    "cursor": "6Ck1la0VxJ0djhidm1MdX2FyDGxLKVeeHZZmORS_8XeSuhz9SjIJRaSa2lnsF01tQOHrfTGAP3R5X1Kv5iVUuMbNKhWNAXHOl6ePB0TUL8nw"
  }
}

workers-kv-namespace-read-key-value-pair

GET Read key-value pair permission needed: com.cloudflare.edge.storage.kv.key.read

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

"Some Value"

workers-kv-namespace-read-the-metadata-for-a-key

GET Read the metadata for a key permission needed: com.cloudflare.edge.storage.kv.key.read

Returns the metadata associated with the given key in the given namespace. Use URL-encoding to use special characters (e.g. :, !, %) in the key name.

GET accounts/:account_identifier/storage/kv/namespaces/:namespace_identifier/metadata/:key_name

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/storage/kv/namespaces/0f2ac74b498b48028cb68387c421e279/metadata/My-Key" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

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

workers-kv-namespace-write-key-value-pair

PUT Write key-value pair permission needed: com.cloudflare.edge.storage.kv.key.update

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. If both are set, expiration_ttl is used and expiration is ignored.

PUT accounts/:account_identifier/storage/kv/namespaces/:namespace_identifier/values/:key_name?expiration=:expiration&expiration_ttl=:expiration_ttl

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/storage/kv/namespaces/0f2ac74b498b48028cb68387c421e279/values/My-Key?expiration=1578435000&expiration_ttl=300" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: text/plain" \
     --data '"Some Value"'

Response (example)

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

workers-kv-namespace-write-key-value-pair-with-metadata

PUT Write key-value pair with metadata permission needed: com.cloudflare.edge.storage.kv.key.update

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 along with json metadata to be associated with the key/value pair. Existing values, expirations and metadata will be overwritten. If neither expiration nor expiration_ttl is specified, the key-value pair will never expire. If both are set, expiration_ttl is used and expiration is ignored.

PUT accounts/:account_identifier/storage/kv/namespaces/:namespace_identifier/values/:key_name?expiration=:expiration&expiration_ttl=:expiration_ttl

Required parameters

Name /type	Description /example	Constraints
value string	A byte sequence to be stored, up to 10 MB in length. `"Some Value"`
metadata string	Arbitrary JSON to be associated with a key/value pair `"{\"someMetadataKey\": \"someMetadataValue\"}"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/storage/kv/namespaces/0f2ac74b498b48028cb68387c421e279/values/My-Key?expiration=1578435000&expiration_ttl=300" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: multipart/form-data" \
     --form 'value=Some Value' \
     --form 'metadata={"someMetadataKey": "someMetadataValue"}'

Response (example)

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

workers-kv-namespace-write-multiple-key-value-pairs

PUT Write multiple key-value pairs permission needed: com.cloudflare.edge.storage.kv.key.update

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. If both are set, expiration_ttl is used and expiration is ignored. 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 512 bytes. All printable, non-whitespace characters are valid. `"My-Key"`	max length: 512
value string	A UTF-8 encoded string to be stored, up to 10 MB in length. `"Some string"`	max length: 10485760

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. `1578435000`
expiration_ttl number	The number of seconds for which the key should be visible before it expires. At least 60. `300`
metadata object	Arbitrary JSON that is associated with a key `{ "someMetadataKey": "someMetadataValue" }`
base64 boolean	Whether or not the server should base64 decode the value before storing it. Useful for writing values that wouldn't otherwise be valid JSON strings, such as images. `false`	default value: false valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/storage/kv/namespaces/0f2ac74b498b48028cb68387c421e279/bulk" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '[{"key":"My-Key","value":"Some string","expiration":1578435000,"expiration_ttl":300,"metadata":{"someMetadataKey":"someMetadataValue"},"base64":false}]'

Response (example)

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

workers-kv-namespace-delete-key-value-pair

DELETE Delete key-value pair permission needed: com.cloudflare.edge.storage.kv.key.delete

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

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

workers-kv-namespace-delete-multiple-key-value-pairs

DELETE Delete multiple key-value pairs permission needed: com.cloudflare.edge.storage.kv.key.delete

Remove multiple KV pairs from the Namespace. Body should be an array of up to 10,000 keys to be removed.

DELETE accounts/:account_identifier/storage/kv/namespaces/:namespace_identifier/bulk

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/storage/kv/namespaces/0f2ac74b498b48028cb68387c421e279/bulk" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '["My-Key"]'

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
10018	too many namespaces in this account
10019	missing title
10021	this namespace does not support the list-keys endpoint
10022	too many requests
10024	payload too large
10025	endpoint does not exist
10026	not entitled
10028	invalid limit argument
10029	invalid request
10030	key too long
10033	invalid expiration
10034	invalid expiration ttl
10035	this namespace does not support the bulk endpoint
10037	the user lacks the permissions to perform this operation
10038	this namespace does not support the list-keys prefix parameter
10041	invalid "list keys" cursor
10042	illegal key name
10043	invalid order
10044	invalid direction
10045	deprecated endpoint
10046	too many bulk requests
10047	invalid metadata
10048	free limit reached

Workers KV Request Analytics

Metrics on Workers KV requests.

workers-kv-request-analytics

Object definition

View properties and constraints defined on the object

Show definition

workers-kv-request-analytics-query-request-analytics

GET Query Request Analytics

Retrieves Workers KV request 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

default value: 10000

since
string (date-time)

Start of time interval to query, defaults to 6 hours before request received.

"2019-01-02T02:20:00Z"

default value: <6 hours ago>

until
string (date-time)

End of time interval to query, defaults to current time.

"2019-01-02T03:20:00Z"

default value: <now>

metrics
array

One or more metrics to compute.

[
  "requests",
  "readKiB"
]

An array with items in the following form:

Show definition »

default value: ["requests"]

dimensions
array

Can be used to break down the data by given attributes.

[
  "accountId",
  "responseCode"
]

An array with items in the following form:

Show definition »

default value: []

sort
array

Array of dimensions or metrics to sort by, each dimension/metric may be prefixed by - (descending) or + (ascending)

[
  "+requests",
  "-responseCode"
]

default value: []

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. Note that the semicolon is a reserved character in URLs (rfc1738) and needs to be percent-encoded as %3B. 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

"requestType==read AND responseCode!=200"

default value: ""

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=accountId,responseCode&sort=+requests,-responseCode&filters=requestType==read AND responseCode!=200" \
     -H "X-Auth-Email: user@example.com" \
     -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": [
        "accountId",
        "responseCode"
      ],
      "sort": [
        "+requests",
        "-responseCode"
      ],
      "filters": "requestType==read AND responseCode!=200"
    }
  }
}

Workers KV Request Analytics error codes

Code	Description
10001	missing CF-Ray header
10002	missing account ID
10003	malformed account ID
10004	malformed query
10005	unauthorized method
10006	time range too large
10007	bad namespace ID
10008	missing account tag

Workers KV Stored Data Analytics

Metrics on Workers KV stored data.

workers-kv-stored-data-analytics

Object definition

View properties and constraints defined on the object

Show definition

workers-kv-stored-data-analytics-query-stored-data-analytics

GET Query Stored Data Analytics

Retrieves Workers KV stored data metrics for the given account.

GET accounts/:account_identifier/storage/analytics/stored

Optional parameters

Name /type Description /example Constraints

limit
integer

Limit number of returned metrics.

10000

default value: 10000

since
string (date-time)

Start of time interval to query, defaults to 6 hours before request received.

"2019-01-02T02:20:00Z"

default value: <6 hours ago>

until
string (date-time)

End of time interval to query, defaults to current time.

"2019-01-02T03:20:00Z"

default value: <now>

metrics
array

One or more metrics to compute.

[
  "storedBytes",
  "storedKeys"
]

An array with items in the following form:

Show definition »

default value: ["storedBytes"]

dimensions
array

Can be used to break down the data by given attributes.

[
  "namespaceId"
]

An array with items in the following form:

Show definition »

default value: []

sort
array

Array of dimensions or metrics to sort by, each dimension/metric may be prefixed by - (descending) or + (ascending)

[
  "+storedBytes",
  "-namespaceId"
]

default value: []

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

"namespaceId==a4e8cbb7-1b58-4990-925e-e026d40c4c64"

default value: ""

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/storage/analytics/stored?limit=10000&since=2019-01-02T02:20:00Z&until=2019-01-02T03:20:00Z&metrics=storedBytes,storedKeys&dimensions=namespaceId&sort=+storedBytes,-namespaceId&filters=namespaceId==a4e8cbb7-1b58-4990-925e-e026d40c4c64" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "rows": 2,
    "data": [
      {
        "metrics": [
          [
            2,
            4
          ],
          [
            16,
            32
          ]
        ]
      }
    ],
    "data_lag": 0,
    "min": {
      "storedKeys": 2,
      "storedBytes": 16
    },
    "max": {
      "storedKeys": 4,
      "storedBytes": 32
    },
    "totals": {
      "storedKeys": 6,
      "storedBytes": 48
    },
    "query": {
      "limit": 10000,
      "since": "2019-01-02T02:20:00Z",
      "until": "2019-01-02T03:20:00Z",
      "metrics": [
        "storedBytes",
        "storedKeys"
      ],
      "dimensions": [
        "namespaceId"
      ],
      "sort": [
        "+storedBytes",
        "-namespaceId"
      ],
      "filters": "namespaceId==a4e8cbb7-1b58-4990-925e-e026d40c4c64"
    }
  }
}

Workers KV Stored Data Analytics error codes

Code	Description
10001	missing CF-Ray header
10002	missing account ID
10003	malformed account ID
10004	malformed query
10005	unauthorized method

Worker Script (Deprecated)

A Worker script is a single script that is executed on matching filters in the Cloudflare edge

NOTE: This API is deprecated, please use equivalent /accounts API endpoints where possible. These APIs are for use with the previously limited single-script zones.

worker-script-deprecated-

Object definition

View properties and constraints defined on the object

Show definition

worker-script-deprecated--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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Accept: application/javascript"

Response (example)

addEventListener('fetch', event => { event.respondWith(fetch(event.request)) })

worker-script-deprecated--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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

worker-script-deprecated--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: user@example.com" \
     -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 (Deprecated) 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 (Deprecated)

A worker binding is a resource made available to a worker via a JavaScript variable name.

NOTE: This API is deprecated, please use equivalent /accounts API endpoints where possible. These APIs are for use with the previously limited single-script zones.

worker-binding-deprecated-

Object definitions

View properties and constraints defined on the object

Show definitions

worker-binding-deprecated--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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "name": "myBinding",
      "type": "kv_namespace",
      "namespace_id": "0f2ac74b498b48028cb68387c421e279"
    }
  ]
}

Worker Filters (Deprecated)

Filters are basic patterns used to enable or disable workers that match requests.

NOTE: This API is deprecated, please use equivalent /routes API endpoints where possible. These APIs are for use with the previously limited single-script zones.

worker-filters-deprecated-

Object definition

View properties and constraints defined on the object

Show definition

worker-filters-deprecated--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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "9a7806061c88ada191ed06f989cc3dac",
      "pattern": "example.net/*",
      "enabled": true
    }
  ]
}

worker-filters-deprecated--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: user@example.com" \
     -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-deprecated--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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

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

worker-filters-deprecated--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: user@example.com" \
     -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 (Deprecated) 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 Cron Trigger

A Worker Cron Trigger schedules a Worker Script to be ran at a specific interval.

For more detailed documentation on using the API for Workers see the Workers API.

worker-cron-trigger

Object definition

View properties and constraints defined on the object

Show definition

worker-cron-trigger-update-cron-triggers

PUT Update Cron Triggers permission needed: com.cloudflare.edge.worker.cron.trigger.update

Updates Cron Triggers for a Worker.

PUT accounts/:account_identifier/workers/scripts/:script_name/schedules

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/scripts/this-is_my_script-01/schedules" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '"[{'cron': '*/30 * * * *'}]"'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "schedules": [
      {
        "cron": "*/30 * * * *",
        "created_on": "2017-01-01T00:00:00Z",
        "modified_on": "2017-01-01T00:00:00Z"
      }
    ]
  }
}

worker-cron-trigger-get-cron-triggers

GET Get Cron Triggers permission needed: com.cloudflare.edge.worker.cron.trigger.read

Fetches Cron Triggers for a Worker.

GET accounts/:account_identifier/workers/scripts/:script_name/schedules

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/scripts/this-is_my_script-01/schedules" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "schedules": [
      {
        "cron": "*/30 * * * *",
        "created_on": "2017-01-01T00:00:00Z",
        "modified_on": "2017-01-01T00:00:00Z"
      }
    ]
  }
}

Worker Cron Trigger error codes

Code	Description
10001	Unsupported or unexpected Content Type
10002	Unexpected internal server error
10003	Missing required URL parameter
10004	Malformed URL parameter
10005	Missing script name
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
10023	Unauthorized access attempt
10026	Unable to parse request body
10063	workers.dev subdomain required
10100	Unable to parse cron string

Worker Tail Logs

Receive websocket URL of trace worker.

For more detailed documentation on using the API for Workers see the Workers API.

worker-tail-logs

Object definition

View properties and constraints defined on the object

Show definition

worker-tail-logs-start-tail

POST Start Tail permission needed: com.cloudflare.edge.worker.script.readcom.cloudflare.edge.worker.tail.create

Starts a tail that receives logs and exception from a Worker

POST accounts/:account_identifier/workers/scripts/:script_name/tails

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/scripts/this-is_my_script-01/tails" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "03dc9f77817b488fb26c5861ec18f791",
    "url": "wss://tail.developers.workers.dev/03dc9f77817b488fb26c5861ec18f791",
    "expires_at": "2021-08-20T19:15:51Z"
  }
}

worker-tail-logs-list-tails

GET List Tails permission needed: com.cloudflare.edge.worker.script.read

Get list of tails currently deployed on a worker

GET accounts/:account_identifier/workers/scripts/:script_name/tails

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/scripts/this-is_my_script-01/tails" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "03dc9f77817b488fb26c5861ec18f791",
    "url": "wss://tail.developers.workers.dev/03dc9f77817b488fb26c5861ec18f791",
    "expires_at": "2021-08-20T19:15:51Z"
  }
}

worker-tail-logs-delete-tail

DELETE Delete Tail permission needed: com.cloudflare.edge.worker.script.readcom.cloudflare.edge.worker.tail.create

Deletes a tail from a Worker

DELETE accounts/:account_identifier/workers/scripts/:script_name/tails/:id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/scripts/this-is_my_script-01/tails/03dc9f77817b488fb26c5861ec18f791" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

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

Worker Tail Logs error codes

Code	Description
10057	Worker has too much traffic to add a tail
10059	Worker has too many active tails (maximum is 10)
10076	Worker cannot be tailed due to abuse

Worker Domain

A Worker Domain lets you attach workers to a specific zone and hostname (Beta)

For more detailed documentation on using the API for Workers see the Workers API.

worker-domain

Object definition

View properties and constraints defined on the object

Show definition

worker-domain-list-domains

GET List Domains permission needed: com.cloudflare.edge.worker.domain.list

Lists all Worker Domains.

GET accounts/:account_identifier/workers/domains

Optional parameters

Name /type	Description /example	Constraints
zone_id string	Identifier of the zone `"593c9c94de529bbbfaac7c53ced0447d"`	max length: 32 read only
zone_name string	Name of the zone `"example.com"`
hostname string	Hostname of the Worker Domain `"foo.example.com"`
service string	Worker service associated with the zone and hostname `"foo"`
environment string	Worker environment associated with the zone and hostname `"production"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/domains?zone_id=593c9c94de529bbbfaac7c53ced0447d&zone_name=example.com&hostname=foo.example.com&service=foo&environment=production" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "dbe10b4bc17c295377eabd600e1787fd",
      "zone_id": "593c9c94de529bbbfaac7c53ced0447d",
      "zone_name": "example.com",
      "hostname": "foo.example.com",
      "service": "foo",
      "environment": "production"
    }
  ]
}

worker-domain-attach-to-domain

PUT Attach to Domain permission needed: com.cloudflare.edge.worker.domain.update

Attaches a worker to a zone and hostname.

PUT accounts/:account_identifier/workers/domains

Required parameters

Name /type	Description /example	Constraints
zone_id string	Identifier of the zone `"593c9c94de529bbbfaac7c53ced0447d"`	max length: 32 read only
hostname string	Hostname of the Worker Domain `"foo.example.com"`
service string	Worker service associated with the zone and hostname `"foo"`
environment string	Worker environment associated with the zone and hostname `"production"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/domains" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"zone_id":"593c9c94de529bbbfaac7c53ced0447d","hostname":"foo.example.com","service":"foo","environment":"production"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "dbe10b4bc17c295377eabd600e1787fd",
    "zone_id": "593c9c94de529bbbfaac7c53ced0447d",
    "zone_name": "example.com",
    "hostname": "foo.example.com",
    "service": "foo",
    "environment": "production"
  }
}

worker-domain-get-a-domain

GET Get a Domain permission needed: com.cloudflare.edge.worker.domain.read

Gets a Worker Domain.

GET accounts/:account_identifier/workers/domains/:domain_identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/domains/dbe10b4bc17c295377eabd600e1787fd" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "dbe10b4bc17c295377eabd600e1787fd",
    "zone_id": "593c9c94de529bbbfaac7c53ced0447d",
    "zone_name": "example.com",
    "hostname": "foo.example.com",
    "service": "foo",
    "environment": "production"
  }
}

worker-domain-detach-from-domain

DELETE Detach from Domain permission needed: com.cloudflare.edge.worker.domain.delete

Detaches a worker from a zone and hostname.

DELETE accounts/:account_identifier/workers/domains/:domain_identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/domains/dbe10b4bc17c295377eabd600e1787fd" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

Worker Domain 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)
100110	Domain zone identifier is missing
100111	Domain hostname is missing
100112	Domain hostname does not match the zone
100113	Domain cannot be managed since there are other DNS entries
100114	Domain not found
100115	Domain cannot be managed since there are other DNS entries
100122	User has reached their limit for custom domains
10014	Internal error while attempting authorization checks
10015	The current account is not authorized to use workers
10023	Unauthorized access attempt
10026	Unable to parse request body

Worker Subdomain

A Worker Subdomain is a unique subdomain specified for each Cloudflare account that enables running Workers without a zone.

For more detailed documentation on using the API for Workers see the Workers API.

worker-subdomain

Object definition

View properties and constraints defined on the object

Show definition

worker-subdomain-create-subdomain

PUT Create Subdomain permission needed: com.cloudflare.edge.worker.cron.subdomain.create

Creates a Workers subdomain for an account.

PUT accounts/:account_identifier/workers/subdomain

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/subdomain" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '"{'subdomain': 'example-subdomain'}"'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "name": "example-subdomain"
  }
}

worker-subdomain-get-subdomain

GET Get Subdomain permission needed: com.cloudflare.edge.worker.cron.subdomain.read

Returns a Workers subdomain for an account.

GET accounts/:account_identifier/workers/subdomain

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/subdomain" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "name": "example-subdomain"
  }
}

Worker Subdomain 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
10023	Unauthorized access attempt
10026	Unable to parse request body
10031	Subdomain is unavailable
10033	Subdomain is invalid
10034	Email verification is required
10035	Conflict occurred updating resource
10036	Subdomain exists for account

Worker Account Settings

Worker Account Settings specify account-level configurations for a Workers account.

For more detailed documentation on using the API for Workers see the Workers API.

worker-account-settings

Object definition

View properties and constraints defined on the object

Show definition

worker-account-settings-create-worker-account-settings

PUT Create Worker Account Settings permission needed: com.cloudflare.api.account.update

Creates Worker Account Settings for an account.

PUT accounts/:account_identifier/workers/account-settings

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/account-settings" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '"{'default_usage_model': 'unbound'}"'

Response (example)

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

worker-account-settings-fetch-worker-account-settings

GET Fetch Worker Account Settings permission needed: com.cloudflare.api.account.read

Fetches Worker Account Settings for an account.

GET accounts/:account_identifier/workers/account-settings

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/workers/account-settings" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Worker Account Settings 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
10023	Unauthorized access attempt
10026	Unable to parse request body
10075	Requires a Workers Paid plan
10080	The current account is not authorized to use green compute

Durable Objects Namespace

A Namespace is a collection of Durable Objects of the same class

durable-objects-namespace

Object definition

View properties and constraints defined on the object

Show definition

durable-objects-namespace-list-namespaces

GET List Namespaces permission needed: com.cloudflare.edge.worker.durable-object.class.list

Returns the namespaces owned by an account

GET accounts/:account_identifier/workers/durable_objects/namespaces

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/workers/durable_objects/namespaces" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "5fd1cafff895419c8bcc647fc64ab8f0",
      "name": "some_namespace_name",
      "script": "some_script_name",
      "class": "SomeClass"
    }
  ]
}

durable-objects-namespace-list-objects

GET List Objects permission needed: com.cloudflare.edge.worker.durable-object.class.read

Returns the Durable Objects in a given namespace

GET accounts/:account_identifier/workers/durable_objects/namespaces/:id/objects

Optional parameters

Name /type	Description /example	Constraints
limit number	The number of objects to return. The cursor attribute may be used to iterate over the next batch of objects if there are more than the limit. `1000`	default value: 1000 min value:10 max value:10000
cursor string	Opaque token indicating the position from which to continue when requesting the next set of records. A valid value for the cursor can be obtained from the cursors object in the result_info structure. `"AAAAANuhDN7SjacTnSVsDu3WW1Lvst6dxJGTjRY5BhxPXdf6L6uTcpd_NVtjhn11OUYRsVEykxoUwF-JQU4dn6QylZSKTOJuG0indrdn_MlHpMRtsxgXjs-RPdHYIVm3odE_uvEQ_dTQGFm8oikZMohns34DLBgrQpc"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/workers/durable_objects/namespaces/5fd1cafff895419c8bcc647fc64ab8f0/objects?limit=1000&cursor=AAAAANuhDN7SjacTnSVsDu3WW1Lvst6dxJGTjRY5BhxPXdf6L6uTcpd_NVtjhn11OUYRsVEykxoUwF-JQU4dn6QylZSKTOJuG0indrdn_MlHpMRtsxgXjs-RPdHYIVm3odE_uvEQ_dTQGFm8oikZMohns34DLBgrQpc" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "fe7803fc55b964e09d94666545aab688d360c6bda69ba349ced1e5f28d2fc2c8",
      "hasStoredData": true
    }
  ],
  "result_info": {
    "count": 1,
    "cursor": "AAAAANuhDN7SjacTnSVsDu3WW1Lvst6dxJGTjRY5BhxPXdf6L6uTcpd_NVtjhn11OUYRsVEykxoUwF-JQU4dn6QylZSKTOJuG0indrdn_MlHpMRtsxgXjs-RPdHYIVm3odE_uvEQ_dTQGFm8oikZMohns34DLBgrQpc"
  }
}

Durable Objects Namespace 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
10023	Unauthorized access attempt
10066	Durable Object namespace not found
10075	Requires a Workers Paid plan

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

Retrieves 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	Sets the maximum number of results per page. `20`	default value: 20 min value:1 max value:100
direction string	Sets the direction by which results are ordered. `"desc"`	default value: asc valid values: asc, desc
order string	Application field by which results are ordered. `"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: user@example.com" \
     -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": "off",
      "ip_firewall": true,
      "tls": "full",
      "edge_ips": {
        "type": "dynamic",
        "connectivity": "all"
      },
      "traffic_type": "direct",
      "argo_smart_routing": true,
      "created_on": "2014-01-02T02:20:00Z",
      "modified_on": "2014-01-02T02:20:00Z"
    }
  ]
}

spectrum-applications-create-spectrum-application-using-an-ip-address-for-the-origin

POST Create Spectrum application using an IP address for the origin

Creates a new Spectrum application from a configuration using an IP address for the origin.

POST zones/:zone/spectrum/apps

Required parameters

Name /type	Description /example	Constraints
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 »
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 »
protocol string	The port configuration at Cloudflare’s edge. May specify a single port, for example `"tcp/1000"`, or a range of ports, for example `"tcp/1000-2000"`. `"tcp/22"`

Optional parameters

Name /type	Description /example	Constraints
proxy_protocol string	Enables Proxy Protocol to the origin. Refer to Enable Proxy protocol for implementation details on PROXY Protocol V1, PROXY Protocol V2, and Simple Proxy Protocol. `"off"`	default value: off valid values: off, v1, v2, simple
edge_ips	The anycast edge IP configuration for the hostname of this application. `{ "type": "dynamic", "connectivity": "all" }` One of the following: Show definition » Show definition »	default value: Map { "type": "dynamic", "connectivity": "all" }
argo_smart_routing boolean	Enables Argo Smart Routing for this application. `true`	default value: false valid values: (true,false) notes: Only available for TCP applications with traffic_type set to "direct".
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
traffic_type string	Determines how data travels from the edge to your origin. When set to "direct", Spectrum will send traffic directly to your origin, and the application's type is derived from the `protocol`. When set to "http" or "https", Spectrum will apply Cloudflare's HTTP/HTTPS features as it sends traffic to your origin, and the application type matches this property exactly. `"direct"`	default value: direct valid values: direct, http, https

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/spectrum/apps" \
     -H "X-Auth-Email: user@example.com" \
     -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":"off","ip_firewall":true,"tls":"full","edge_ips":{"type":"dynamic","connectivity":"all"},"traffic_type":"direct","argo_smart_routing":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": "off",
    "ip_firewall": true,
    "tls": "full",
    "edge_ips": {
      "type": "dynamic",
      "connectivity": "all"
    },
    "traffic_type": "direct",
    "argo_smart_routing": true,
    "created_on": "2014-01-02T02:20:00Z",
    "modified_on": "2014-01-02T02:20:00Z"
  }
}

spectrum-applications-create-spectrum-application-using-a-name-for-the-origin

POST Create Spectrum application using a name for the origin

Creates a new Spectrum application from a configuration using a name for the origin.

POST zones/:zone/spectrum/apps

Required parameters

Name /type	Description /example	Constraints
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_dns object	The name and type of DNS record for the Spectrum application. `{ "type": "", "name": "origin.example.com", "ttl": 600 }` An object with the following properties: Show definition »
protocol string	The port configuration at Cloudflare’s edge. May specify a single port, for example `"tcp/1000"`, or a range of ports, for example `"tcp/1000-2000"`. `"tcp/22"`
origin_port integerstring	The destination port at the origin. Only specified in conjunction with origin_dns. May use an integer to specify a single origin port, for example `1000`, or a string to specify a range of origin ports, for example `"1000-2000"` `22`	min value:1 max value:65535 notes: If specifying a port range, the number of ports in the range must match the number of ports specified in the "protocol" field.

Optional parameters

Name /type	Description /example	Constraints
proxy_protocol string	Enables Proxy Protocol to the origin. Refer to Enable Proxy protocol for implementation details on PROXY Protocol V1, PROXY Protocol V2, and Simple Proxy Protocol. `"off"`	default value: off valid values: off, v1, v2, simple
edge_ips	The anycast edge IP configuration for the hostname of this application. `{ "type": "dynamic", "connectivity": "all" }` One of the following: Show definition » Show definition »	default value: Map { "type": "dynamic", "connectivity": "all" }
argo_smart_routing boolean	Enables Argo Smart Routing for this application. `true`	default value: false valid values: (true,false) notes: Only available for TCP applications with traffic_type set to "direct".
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
traffic_type string	Determines how data travels from the edge to your origin. When set to "direct", Spectrum will send traffic directly to your origin, and the application's type is derived from the `protocol`. When set to "http" or "https", Spectrum will apply Cloudflare's HTTP/HTTPS features as it sends traffic to your origin, and the application type matches this property exactly. `"direct"`	default value: direct valid values: direct, http, https

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/spectrum/apps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"protocol":"tcp/22","dns":{"type":"CNAME","name":"ssh.example.com"},"origin_dns":{"type":"","name":"origin.example.com","ttl":600},"origin_port":22,"proxy_protocol":"off","ip_firewall":true,"tls":"full","edge_ips":{"type":"dynamic","connectivity":"all"},"traffic_type":"direct","argo_smart_routing":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "ea95132c15732412d22c1476fa83f27a",
    "protocol": "tcp/22",
    "dns": {
      "type": "CNAME",
      "name": "ssh.example.com"
    },
    "origin_dns": {
      "type": "",
      "name": "origin.example.com",
      "ttl": 600
    },
    "origin_port": 22,
    "proxy_protocol": "off",
    "ip_firewall": true,
    "tls": "full",
    "edge_ips": {
      "type": "dynamic",
      "connectivity": "all"
    },
    "traffic_type": "direct",
    "argo_smart_routing": true,
    "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

Gets 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: user@example.com" \
     -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": "off",
    "ip_firewall": true,
    "tls": "full",
    "edge_ips": {
      "type": "dynamic",
      "connectivity": "all"
    },
    "traffic_type": "direct",
    "argo_smart_routing": true,
    "created_on": "2014-01-02T02:20:00Z",
    "modified_on": "2014-01-02T02:20:00Z"
  }
}

spectrum-applications-update-spectrum-application-configuration-using-an-ip-address-for-the-origin

PUT Update Spectrum application configuration using an IP address for the origin

Updates a previously existing application's configuration that uses an IP address for the origin.

PUT zones/:zone/spectrum/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
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 »
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 »
protocol string	The port configuration at Cloudflare’s edge. May specify a single port, for example `"tcp/1000"`, or a range of ports, for example `"tcp/1000-2000"`. `"tcp/22"`

Optional parameters

Name /type	Description /example	Constraints
proxy_protocol string	Enables Proxy Protocol to the origin. Refer to Enable Proxy protocol for implementation details on PROXY Protocol V1, PROXY Protocol V2, and Simple Proxy Protocol. `"off"`	default value: off valid values: off, v1, v2, simple
edge_ips	The anycast edge IP configuration for the hostname of this application. `{ "type": "dynamic", "connectivity": "all" }` One of the following: Show definition » Show definition »	default value: Map { "type": "dynamic", "connectivity": "all" }
argo_smart_routing boolean	Enables Argo Smart Routing for this application. `true`	default value: false valid values: (true,false) notes: Only available for TCP applications with traffic_type set to "direct".
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
traffic_type string	Determines how data travels from the edge to your origin. When set to "direct", Spectrum will send traffic directly to your origin, and the application's type is derived from the `protocol`. When set to "http" or "https", Spectrum will apply Cloudflare's HTTP/HTTPS features as it sends traffic to your origin, and the application type matches this property exactly. `"direct"`	default value: direct valid values: direct, http, https

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/spectrum/apps/ea95132c15732412d22c1476fa83f27a" \
     -H "X-Auth-Email: user@example.com" \
     -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":"off","ip_firewall":true,"tls":"full","edge_ips":{"type":"dynamic","connectivity":"all"},"traffic_type":"direct","argo_smart_routing":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": "off",
    "ip_firewall": true,
    "tls": "full",
    "edge_ips": {
      "type": "dynamic",
      "connectivity": "all"
    },
    "traffic_type": "direct",
    "argo_smart_routing": true,
    "created_on": "2014-01-02T02:20:00Z",
    "modified_on": "2014-01-02T02:20:00Z"
  }
}

spectrum-applications-update-spectrum-application-configuration-using-a-name-for-the-origin

PUT Update Spectrum application configuration using a name for the origin

Updates a previously existing application's configuration that uses a name for the origin.

PUT zones/:zone/spectrum/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
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_dns object	The name and type of DNS record for the Spectrum application. `{ "type": "", "name": "origin.example.com", "ttl": 600 }` An object with the following properties: Show definition »
protocol string	The port configuration at Cloudflare’s edge. May specify a single port, for example `"tcp/1000"`, or a range of ports, for example `"tcp/1000-2000"`. `"tcp/22"`
origin_port integerstring	The destination port at the origin. Only specified in conjunction with origin_dns. May use an integer to specify a single origin port, for example `1000`, or a string to specify a range of origin ports, for example `"1000-2000"` `22`	min value:1 max value:65535 notes: If specifying a port range, the number of ports in the range must match the number of ports specified in the "protocol" field.

Optional parameters

Name /type	Description /example	Constraints
proxy_protocol string	Enables Proxy Protocol to the origin. Refer to Enable Proxy protocol for implementation details on PROXY Protocol V1, PROXY Protocol V2, and Simple Proxy Protocol. `"off"`	default value: off valid values: off, v1, v2, simple
edge_ips	The anycast edge IP configuration for the hostname of this application. `{ "type": "dynamic", "connectivity": "all" }` One of the following: Show definition » Show definition »	default value: Map { "type": "dynamic", "connectivity": "all" }
argo_smart_routing boolean	Enables Argo Smart Routing for this application. `true`	default value: false valid values: (true,false) notes: Only available for TCP applications with traffic_type set to "direct".
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
traffic_type string	Determines how data travels from the edge to your origin. When set to "direct", Spectrum will send traffic directly to your origin, and the application's type is derived from the `protocol`. When set to "http" or "https", Spectrum will apply Cloudflare's HTTP/HTTPS features as it sends traffic to your origin, and the application type matches this property exactly. `"direct"`	default value: direct valid values: direct, http, https

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/spectrum/apps/ea95132c15732412d22c1476fa83f27a" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"protocol":"tcp/22","dns":{"type":"CNAME","name":"ssh.example.com"},"origin_dns":{"type":"","name":"origin.example.com","ttl":600},"origin_port":22,"proxy_protocol":"off","ip_firewall":true,"tls":"full","edge_ips":{"type":"dynamic","connectivity":"all"},"traffic_type":"direct","argo_smart_routing":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "ea95132c15732412d22c1476fa83f27a",
    "protocol": "tcp/22",
    "dns": {
      "type": "CNAME",
      "name": "ssh.example.com"
    },
    "origin_dns": {
      "type": "",
      "name": "origin.example.com",
      "ttl": 600
    },
    "origin_port": 22,
    "proxy_protocol": "off",
    "ip_firewall": true,
    "tls": "full",
    "edge_ips": {
      "type": "dynamic",
      "connectivity": "all"
    },
    "traffic_type": "direct",
    "argo_smart_routing": true,
    "created_on": "2014-01-02T02:20:00Z",
    "modified_on": "2014-01-02T02:20:00Z"
  }
}

spectrum-applications-delete-spectrum-application

DELETE Delete Spectrum application

Deletes 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: user@example.com" \
     -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==disconnect%20AND%20coloName!=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. Timestamp must be in RFC3339 format and uses UTC unless otherwise specified.

"2014-01-02T02:20:00Z"

until
string (date-time)

End of time interval to query, defaults to current time. Timestamp must be in RFC3339 format and uses UTC unless otherwise specified.

"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==disconnect%20AND%20coloName!=SFO&sort=+count,-bytesIngress&since=2014-01-02T02:20:00Z&until=2014-01-02T03:20:00Z" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

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==disconnect%20AND%20coloName!=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. Timestamp must be in RFC3339 format and uses UTC unless otherwise specified.

"2014-01-02T02:20:00Z"

until
string (date-time)

End of time interval to query, defaults to current time. Timestamp must be in RFC3339 format and uses UTC unless otherwise specified.

"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==disconnect%20AND%20coloName!=SFO&sort=+count,-bytesIngress&since=2014-01-02T02:20:00Z&until=2014-01-02T03:20:00Z&time_delta=minute" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

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-aggregated-analytics

GET Get current aggregated 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: user@example.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

Page Rules allow you to perform one or more actions on requests matching target patterns.

page-rules

Object definition

View properties and constraints defined on the object

Show definition

page-rules-get-page-rules

GET Get Page Rules permission needed: #zone:read
free
pro
business
enterprise

Fetches Page Rules in a zone.

GET zones/:zone_identifier/pagerules

Optional parameters

Name /type	Description /example	Constraints
status string	The status of the Page Rule. `"active"`	default value: disabled valid values: active, disabled
order string	The field used to sort returned Page Rules. `"status"`	default value: priority valid values: status, priority
direction string	The direction used to sort returned Page Rules. `"desc"`	default value: desc valid values: asc, desc
match string	When set to `all`, all the search requirements must match. When set to `any`, only one of the search requirements has to match. `"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: user@example.com" \
     -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": "browser_check",
          "value": "on"
        }
      ],
      "priority": 1,
      "status": "active",
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "created_on": "2014-01-01T05:20:00.12345Z"
    }
  ]
}

page-rules-create-a-page-rule

POST Create a Page Rule permission needed: #zone:edit
free
pro
business
enterprise

Creates a new Page Rule.

POST zones/:zone_identifier/pagerules

Required parameters

Name /type	Description /example	Constraints
targets array	The rule targets to evaluate on each 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 to another URL or override settings, but not both. `[ { "id": "browser_check", "value": "on" } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
priority integer	The priority of the rule, used to define which Page Rule is processed over another. A higher number indicates a higher priority. For example, if you have a catch-all Page Rule (rule A: `/images/`) but want a more specific Page Rule to take precedence (rule B: `/images/special/`), specify a higher priority for rule B so it overrides rule A. `1`	default value: 1
status string	The 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"targets":[{"target":"url","constraint":{"operator":"matches","value":"*example.com/images/*"}}],"actions":[{"id":"browser_check","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": "browser_check",
        "value": "on"
      }
    ],
    "priority": 1,
    "status": "active",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "created_on": "2014-01-01T05:20:00.12345Z"
  }
}

page-rules-get-a-page-rule

GET Get a Page Rule permission needed: #zone:read
free
pro
business
enterprise

Fetches the details of a Page Rule.

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: user@example.com" \
     -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": "browser_check",
        "value": "on"
      }
    ],
    "priority": 1,
    "status": "active",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "created_on": "2014-01-01T05:20:00.12345Z"
  }
}

page-rules-update-a-page-rule

PUT Update a Page Rule permission needed: #zone:edit
free
pro
business
enterprise

Replaces the configuration of an existing Page Rule. The configuration of the updated Page Rule will exactly match the data passed in the API request.

PUT zones/:zone_identifier/pagerules/:identifier

Required parameters

Name /type	Description /example	Constraints
targets array	The rule targets to evaluate on each 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 to another URL or override settings, but not both. `[ { "id": "browser_check", "value": "on" } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
priority integer	The priority of the rule, used to define which Page Rule is processed over another. A higher number indicates a higher priority. For example, if you have a catch-all Page Rule (rule A: `/images/`) but want a more specific Page Rule to take precedence (rule B: `/images/special/`), specify a higher priority for rule B so it overrides rule A. `1`	default value: 1
status string	The 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"targets":[{"target":"url","constraint":{"operator":"matches","value":"*example.com/images/*"}}],"actions":[{"id":"browser_check","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": "browser_check",
        "value": "on"
      }
    ],
    "priority": 1,
    "status": "active",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "created_on": "2014-01-01T05:20:00.12345Z"
  }
}

page-rules-edit-a-page-rule

PATCH Edit a Page Rule permission needed: #zone:edit
free
pro
business
enterprise

Updates one or more fields of an existing Page Rule.

PATCH zones/:zone_identifier/pagerules/:identifier

Optional parameters

Name /type	Description /example	Constraints
targets array	The rule targets to evaluate on each 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 to another URL or override settings, but not both. `[ { "id": "browser_check", "value": "on" } ]` An array with items in the following form: Show definition »
priority integer	The priority of the rule, used to define which Page Rule is processed over another. A higher number indicates a higher priority. For example, if you have a catch-all Page Rule (rule A: `/images/`) but want a more specific Page Rule to take precedence (rule B: `/images/special/`), specify a higher priority for rule B so it overrides rule A. `1`	default value: 1
status string	The 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"targets":[{"target":"url","constraint":{"operator":"matches","value":"*example.com/images/*"}}],"actions":[{"id":"browser_check","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": "browser_check",
        "value": "on"
      }
    ],
    "priority": 1,
    "status": "active",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "created_on": "2014-01-01T05:20:00.12345Z"
  }
}

page-rules-delete-a-page-rule

DELETE Delete a Page Rule permission needed: #zone:edit
free
pro
business
enterprise

Deletes an existing Page Rule.

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Available Page Rules settings

The different settings that Page Rules can apply to matching requests.

For more information on Page Rules, refer to Page Rules.

available-page-rules-settings

Object definition

View properties and constraints defined on the object

Show definition

available-page-rules-settings-get-available-page-rules-settings

GET Get available Page Rules settings permission needed: #zone:read
free
pro
business
enterprise

Returns a list of settings (and their details) that Page Rules can apply to matching requests.

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "browser_check",
      "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_key_fields",
      "properties": [
        {
          "name": "value",
          "type": "object",
          "properties": [
            {
              "name": "query_string",
              "type": "select",
              "multiple": false,
              "allowEmpty": true,
              "choices": [
                "include",
                "exclude"
              ]
            },
            {
              "name": "header",
              "type": "select",
              "multiple": true,
              "allowEmpty": true,
              "choices": [
                "include",
                "exclude",
                "check_presence"
              ]
            },
            {
              "name": "host",
              "type": "select",
              "multiple": true,
              "allowEmpty": false,
              "choices": [
                "resolved"
              ]
            },
            {
              "name": "cookie",
              "type": "select",
              "multiple": true,
              "allowEmpty": true,
              "choices": [
                "include",
                "check_presence"
              ]
            },
            {
              "name": "user",
              "type": "select",
              "multiple": true,
              "allowEmpty": false,
              "choices": [
                "device_type",
                "geo",
                "lang"
              ]
            }
          ]
        }
      ]
    },
    {
      "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": "cache_ttl_by_status",
      "properties": [
        {
          "name": "value",
          "type": "object",
          "allowEmpty": false
        }
      ]
    },
    {
      "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

Rate limits configured for a zone.

Note: To configure the new rate limiting rules based on the Ruleset Engine you must use the Account rulesets or Zone rulesets API endpoints. For more information, refer to Rate limiting rules in Developer Docs.

rate-limits-for-a-zone

Object definition

View properties and constraints defined on the object

Show definition

rate-limits-for-a-zone-get-rate-limits

GET Get rate limits
free
pro
business
enterprise

Fetches the rate limits for a zone.

GET zones/:zone_identifier/rate_limits

Optional parameters

Name /type	Description /example	Constraints
page number	The page number of paginated results. `1`	default value: 1 min value:1
per_page number	The maximum number of results per page. You can only set the value to `1` or to a multiple 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: user@example.com" \
     -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-create-a-rate-limit

POST Create a rate limit
free
pro
business
enterprise

Creates a new rate limit for a zone. Refer to the object definition for a list of required attributes.

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 will trigger the configured mitigation action. Configure this value along with the `period` property to establish a threshold per period. `60`	min value:1
period number	The time in seconds (an integer value) to count matching traffic. If the count exceeds the configured threshold within this period, Cloudflare will perform the configured action. `900`	min value:10 max value:86400
action object	The action to perform when the threshold of matched traffic within the configured period 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	The unique identifier of the rate limit. `"372e67954025e0ba6aaa6d586b9e0b59"`	max length: 32 read only
disabled boolean	When true, indicates that the rate limit is currently disabled. `false`	valid values: (true,false)
description string	An informative summary of the rate limit. This value is sanitized and any tags will be removed. `"Prevent multiple login failures to mitigate brute force attacks"`	max length: 1024
bypass array	Criteria specifying when the current rate limit should be bypassed. You can specify that the rate limit should not apply to one or more 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: user@example.com" \
     -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-get-a-rate-limit

GET Get a rate limit
free
pro
business
enterprise

Fetches the details of a rate limit.

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: user@example.com" \
     -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-a-rate-limit

PUT Update a rate limit
free
pro
business
enterprise

Updates an existing rate limit.

PUT zones/:zone_identifier/rate_limits/:id

Required parameters

Name /type	Description /example	Constraints
id string	The unique identifier of the rate limit. `"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 will trigger the configured mitigation action. Configure this value along with the `period` property to establish a threshold per period. `60`	min value:1
period number	The time in seconds (an integer value) to count matching traffic. If the count exceeds the configured threshold within this period, Cloudflare will perform the configured action. `900`	min value:10 max value:86400
action object	The action to perform when the threshold of matched traffic within the configured period 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	When true, indicates that the rate limit is currently disabled. `false`	valid values: (true,false)
description string	An informative summary of the rate limit. This value is sanitized and any tags will be removed. `"Prevent multiple login failures to mitigate brute force attacks"`	max length: 1024
bypass array	Criteria specifying when the current rate limit should be bypassed. You can specify that the rate limit should not apply to one or more 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: user@example.com" \
     -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-a-rate-limit

DELETE Delete a rate limit
free
pro
business
enterprise

Deletes an existing rate limit.

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: user@example.com" \
     -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

IP Access rules for a user

IP Access rules applied to all zones owned by the current user.

You can create IP Access rules for a specific zone, all zones of an account, or all zones owned by the current user. Each scope has its own API endpoints for managing IP Access rules.

ip-access-rules-for-a-user

Object definition

View properties and constraints defined on the object

Show definition

ip-access-rules-for-a-user-get-ip-access-rules

GET Get IP Access rules
free
pro
business
enterprise

Fetches IP Access rules of the user. You can filter the results using several optional parameters.

GET user/firewall/access_rules/rules

Optional parameters

Name /type	Description /example	Constraints
notes string	The string to search for in the notes of existing IP Access rules. `"my note"`	notes: For example, the string 'attack' would match IP Access rules with notes 'Attack 26/02' and 'Attack 27/02'. The search is case insensitive.
mode string	The action to apply to a matched request. `"challenge"`	valid values: block, challenge, whitelist, js_challenge, managed_challenge
match string	When set to `all`, all the search requirements must match. When set to `any`, only one of the search requirements has to match. `"all"`	default value: all valid values: any, all
configuration.target string	The target to search in existing rules. `"ip"`	valid values: ip, ip_range, asn, country
order string	The field used to sort returned rules. `"mode"`	valid values: configuration.target, configuration.value, mode
page number	The page number of paginated results. `1`	default value: 1 min value:1
per_page number	The maximum number of results per page. You can only set the value to `1` or to a multiple of 5 such as `5`, `10`, `15`, or `20`. `20`	default value: 20 min value:1 max value:1000
configuration.value string	The target value to search for in existing rules: an IP address, an IP address range, or a country code, depending on the provided `configuration.target`. `"198.51.100.4"`	notes: You can search for a single IPv4 address, an IP address range with a subnet of '/16' or '/24', or a two-letter ISO-3166-1 alpha-2 country code.
direction string	The direction used to sort returned 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "92f17202ed8bd63d69a66b86a49a8f6b",
      "notes": "This rule is enabled because of an event that occurred on date X.",
      "allowed_modes": [
        "whitelist",
        "block",
        "challenge",
        "js_challenge",
        "managed_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": "user@example.com",
        "type": "user"
      }
    }
  ]
}

ip-access-rules-for-a-user-create-an-ip-access-rule

POST Create an IP Access rule
free
pro
business
enterprise

Creates a new IP Access rule for all zones owned by the current user.

Note: To create an IP Access rule that applies to a specific zone, refer to the IP Access rules for a zone 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, managed_challenge
configuration object	The rule configuration. `{ "target": "ip", "value": "198.51.100.4" }` One of the following: Show definition » Show definition » Show definition » Show definition » Show definition »

Optional parameters

Name /type	Description /example	Constraints
notes string	An informative summary of the rule, typically used as a reminder or explanation. `"This rule is enabled because of an event that occurred on date X."`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/user/firewall/access_rules/rules" \
     -H "X-Auth-Email: user@example.com" \
     -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 enabled because of an event that occurred on date X."}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "92f17202ed8bd63d69a66b86a49a8f6b",
    "notes": "This rule is enabled because of an event that occurred on date X.",
    "allowed_modes": [
      "whitelist",
      "block",
      "challenge",
      "js_challenge",
      "managed_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": "user@example.com",
      "type": "user"
    }
  }
}

ip-access-rules-for-a-user-update-an-ip-access-rule

PATCH Update an IP Access rule
free
pro
business
enterprise

Updates an IP Access rule defined at the user level. You can only update the rule action (mode parameter) and notes.

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, managed_challenge
notes string	An informative summary of the rule, typically used as a reminder or explanation. `"This rule is enabled because of an event that occurred on date X."`

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/user/firewall/access_rules/rules/92f17202ed8bd63d69a66b86a49a8f6b" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"mode":"challenge","notes":"This rule is enabled because of an event that occurred on date X."}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "92f17202ed8bd63d69a66b86a49a8f6b",
    "notes": "This rule is enabled because of an event that occurred on date X.",
    "allowed_modes": [
      "whitelist",
      "block",
      "challenge",
      "js_challenge",
      "managed_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": "user@example.com",
      "type": "user"
    }
  }
}

ip-access-rules-for-a-user-delete-an-ip-access-rule

DELETE Delete an IP Access rule
free
pro
business
enterprise

Deletes an IP Access rule at the user level.

Note: Deleting a user-level rule will affect 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

IP Access rules for an account

IP Access rules applied to all the zones of an account based on an IP address, an IP address range, or a country.

ip-access-rules-for-an-account

Object definition

View properties and constraints defined on the object

Show definition

ip-access-rules-for-an-account-get-ip-access-rules

GET Get IP Access rules permission needed: #waf:read
free
pro
business
enterprise

Fetches IP Access rules of an account. These rules apply to all the zones in the account. You can filter the results using several optional parameters.

GET accounts/:account_identifier/firewall/access_rules/rules

Optional parameters

Name /type	Description /example	Constraints
notes string	The string to search for in the notes of existing IP Access rules. `"my note"`	notes: For example, the string 'attack' would match IP Access rules with notes 'Attack 26/02' and 'Attack 27/02'. The search is case insensitive.
mode string	The action to apply to a matched request. `"challenge"`	valid values: block, challenge, whitelist, js_challenge, managed_challenge
match string	When set to `all`, all the search requirements must match. When set to `any`, only one of the search requirements has to match. `"all"`	default value: all valid values: any, all
configuration.target string	The target to search in existing rules. `"ip"`	valid values: ip, ip_range, asn, country
order string	The field used to sort returned rules. `"mode"`	valid values: configuration.target, configuration.value, mode
page number	The page number of paginated results. `1`	default value: 1 min value:1
per_page number	The maximum number of results per page. You can only set the value to `1` or to a multiple of 5 such as `5`, `10`, `15`, or `20`. `20`	default value: 20 min value:1 max value:1000
configuration.value string	The target value to search for in existing rules: an IP address, an IP address range, or a country code, depending on the provided `configuration.target`. `"198.51.100.4"`	notes: You can search for a single IPv4 address, an IP address range with a subnet of '/16' or '/24', or a two-letter ISO-3166-1 alpha-2 country code.
direction string	The direction used to sort returned 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "92f17202ed8bd63d69a66b86a49a8f6b",
      "notes": "This rule is enabled because of an event that occurred on date X.",
      "allowed_modes": [
        "whitelist",
        "block",
        "challenge",
        "js_challenge",
        "managed_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": "user@example.com",
        "type": "user"
      }
    }
  ]
}

ip-access-rules-for-an-account-create-an-ip-access-rule

POST Create an IP Access rule permission needed: #waf:edit
free
pro
business
enterprise

Creates a new IP Access rule for an account. The rule will apply to all zones in the account.

Note: To create an IP Access rule that applies to a single zone, refer to the IP Access rules for a zone 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, managed_challenge
configuration object	The rule configuration. `{ "target": "ip", "value": "198.51.100.4" }` One of the following: Show definition » Show definition » Show definition » Show definition » Show definition »

Optional parameters

Name /type	Description /example	Constraints
notes string	An informative summary of the rule, typically used as a reminder or explanation. `"This rule is enabled because of an event that occurred on date X."`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/firewall/access_rules/rules" \
     -H "X-Auth-Email: user@example.com" \
     -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 enabled because of an event that occurred on date X."}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "92f17202ed8bd63d69a66b86a49a8f6b",
    "notes": "This rule is enabled because of an event that occurred on date X.",
    "allowed_modes": [
      "whitelist",
      "block",
      "challenge",
      "js_challenge",
      "managed_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": "user@example.com",
      "type": "user"
    }
  }
}

ip-access-rules-for-an-account-get-an-ip-access-rule

GET Get an IP Access rule permission needed: #waf:read
free
pro
business
enterprise

Fetches the details of an IP Access rule defined at the account level.

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "92f17202ed8bd63d69a66b86a49a8f6b",
    "notes": "This rule is enabled because of an event that occurred on date X.",
    "allowed_modes": [
      "whitelist",
      "block",
      "challenge",
      "js_challenge",
      "managed_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": "user@example.com",
      "type": "user"
    }
  }
}

ip-access-rules-for-an-account-update-an-ip-access-rule

PATCH Update an IP Access rule permission needed: #waf:edit
free
pro
business
enterprise

Updates an IP Access rule defined at the account level.

Note: This operation will affect all zones in the account.

PATCH accounts/:account_identifier/firewall/access_rules/rules/:identifier

Required parameters

Name /type	Description /example	Constraints
id string	The unique identifier of the IP Access rule. `"92f17202ed8bd63d69a66b86a49a8f6b"`	max length: 32 read only
allowed_modes array	The available actions that a rule can apply to a matched request. `[ "whitelist", "block", "challenge", "js_challenge", "managed_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, managed_challenge
configuration object	The rule configuration. `{ "target": "ip", "value": "198.51.100.4" }` One of the following: Show definition » Show definition » Show definition » Show definition » Show definition »
scope object	All zones owned by the user will have the rule applied. `{ "id": "7c5dae5552338874e5053f2534d2767a", "email": "user@example.com", "type": "user" }` An object with the following properties: Show definition »	read only

Optional parameters

Name /type	Description /example	Constraints
notes string	An informative summary of the rule, typically used as a reminder or explanation. `"This rule is enabled because of an event that occurred on date X."`
created_on string (date-time)	The timestamp of when the rule was created. `"2014-01-01T05:20:00.12345Z"`	read only
modified_on string (date-time)	The timestamp of 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"92f17202ed8bd63d69a66b86a49a8f6b","notes":"This rule is enabled because of an event that occurred on date X.","allowed_modes":["whitelist","block","challenge","js_challenge","managed_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":"user@example.com","type":"user"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "92f17202ed8bd63d69a66b86a49a8f6b",
    "notes": "This rule is enabled because of an event that occurred on date X.",
    "allowed_modes": [
      "whitelist",
      "block",
      "challenge",
      "js_challenge",
      "managed_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": "user@example.com",
      "type": "user"
    }
  }
}

ip-access-rules-for-an-account-delete-an-ip-access-rule

DELETE Delete an IP Access rule permission needed: #waf:edit
free
pro
business
enterprise

Deletes an existing IP Access rule defined at the account level.

Note: This operation will affect all zones in 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

IP Access rules for a zone

IP Access rules applied to a specific zone based on an IP address, an IP address range, or a country.

You can create IP Access rules for a specific zone, all zones of an account, or all zones owned by a user. Each scope has its own API endpoints for managing IP Access rules.

ip-access-rules-for-a-zone

Object definition

View properties and constraints defined on the object

Show definition

ip-access-rules-for-a-zone-get-ip-access-rules

GET Get IP Access rules
free
pro
business
enterprise

Fetches IP Access rules of a zone. You can filter the results using several optional parameters.

GET zones/:zone_id/firewall/access_rules/rules

Optional parameters

Name /type	Description /example	Constraints
notes string	The string to search for in the notes of existing IP Access rules. `"my note"`	notes: For example, the string 'attack' would match IP Access rules with notes 'Attack 26/02' and 'Attack 27/02'. The search is case insensitive.
mode string	The action to apply to a matched request. `"challenge"`	valid values: block, challenge, whitelist, js_challenge, managed_challenge
match string	When set to `all`, all the search requirements must match. When set to `any`, only one of the search requirements has to match. `"all"`	default value: all valid values: any, all
configuration.target string	The target to search in existing rules. `"ip"`	valid values: ip, ip_range, asn, country
order string	The field used to sort returned rules. `"mode"`	valid values: configuration.target, configuration.value, mode
page number	The page number of paginated results. `1`	default value: 1 min value:1
per_page number	The maximum number of results per page. You can only set the value to `1` or to a multiple of 5 such as `5`, `10`, `15`, or `20`. `20`	default value: 20 min value:1 max value:1000
configuration.value string	The target value to search for in existing rules: an IP address, an IP address range, or a country code, depending on the provided `configuration.target`. `"198.51.100.4"`	notes: You can search for a single IPv4 address, an IP address range with a subnet of '/16' or '/24', or a two-letter ISO-3166-1 alpha-2 country code.
direction string	The direction used to sort returned 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "92f17202ed8bd63d69a66b86a49a8f6b",
      "notes": "This rule is enabled because of an event that occurred on date X.",
      "allowed_modes": [
        "whitelist",
        "block",
        "challenge",
        "js_challenge",
        "managed_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": "user@example.com",
        "type": "user"
      }
    }
  ]
}

ip-access-rules-for-a-zone-create-an-ip-access-rule

POST Create an IP Access rule
free
pro
business
enterprise

Creates a new IP Access rule for a zone.

Note: To create an IP Access rule that applies to multiple zones, refer to IP Access rules for a user or IP Access rules for an account 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, managed_challenge
configuration object	The rule configuration. `{ "target": "ip", "value": "198.51.100.4" }` One of the following: Show definition » Show definition » Show definition » Show definition » Show definition »
notes string	An informative summary of the rule, typically used as a reminder or explanation. `"This rule is enabled because of an event that occurred on date X."`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/access_rules/rules" \
     -H "X-Auth-Email: user@example.com" \
     -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 enabled because of an event that occurred on date X."}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "92f17202ed8bd63d69a66b86a49a8f6b",
    "notes": "This rule is enabled because of an event that occurred on date X.",
    "allowed_modes": [
      "whitelist",
      "block",
      "challenge",
      "js_challenge",
      "managed_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": "user@example.com",
      "type": "user"
    }
  }
}

ip-access-rules-for-a-zone-update-an-ip-access-rule

PATCH Update an IP Access rule
free
pro
business
enterprise

Updates an IP Access rule defined at the zone level. You can only update the rule action (mode parameter) and notes.

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, managed_challenge
notes string	An informative summary of the rule, typically used as a reminder or explanation. `"This rule is enabled because of an event that occurred 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"mode":"challenge","notes":"This rule is enabled because of an event that occurred on date X."}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "92f17202ed8bd63d69a66b86a49a8f6b",
    "notes": "This rule is enabled because of an event that occurred on date X.",
    "allowed_modes": [
      "whitelist",
      "block",
      "challenge",
      "js_challenge",
      "managed_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": "user@example.com",
      "type": "user"
    }
  }
}

ip-access-rules-for-a-zone-delete-an-ip-access-rule

DELETE Delete an IP Access rule
free
pro
business
enterprise

Deletes an IP Access rule defined at the zone level.

Optionally, you can use the cascade property to specify that you wish to delete similar rules in other zones managed by the same zone owner.

DELETE zones/:zone_id/firewall/access_rules/rules/:identifier

Optional parameters

Name /type	Description /example	Constraints
cascade string	The level to attempt to delete similar rules defined for other zones with the same owner. The default value is `none`, which will only delete the current rule. Using `basic` will delete rules that match the same action (mode) and configuration, while using `aggressive` will delete rules that match the same configuration. `"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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"cascade":"none"}'

Response (example)

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

WAF packages

Web Application Firewall (WAF) rule packages applied to a zone.

WAF packages are collections of WAF rule groups.

waf-packages

Object definitions

View properties and constraints defined on the object

Show definitions

waf-packages-get-waf-packages

GET Get WAF packages
free
pro
business
enterprise

Fetches WAF packages for a zone.

GET zones/:zone_identifier/firewall/waf/packages

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the WAF package. `"USER"`	read only
page number	The page number of paginated results. `1`	default value: 1 min value:1
per_page number	The number of packages per page. `50`	default value: 50 min value:5 max value:100
order string	The field used to sort returned packages. `"status"`	valid values: name
direction string	The direction used to sort returned packages. `"desc"`	valid values: asc, desc
match string	When set to `all`, all the search requirements must match. When set to `any`, only one of the search requirements has to match. `"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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

waf-packages-get-a-waf-package

GET Get a WAF package
free
pro
business
enterprise

Fetches the details of a WAF 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

waf-packages-update-a-waf-package

PATCH Update a WAF package
free
pro
business
enterprise

Updates a WAF package. You can update the sensitivity and the action of an anomaly detection WAF package.

PATCH zones/:zone_identifier/firewall/waf/packages/:identifier

Optional parameters

Name /type	Description /example	Constraints
sensitivity string	The sensitivity of the WAF package. `"high"`	default value: high valid values: high, medium, low, off
action_mode string	The default action performed by the rules in the WAF 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: user@example.com" \
     -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 (WAF) 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-get-waf-rule-groups

GET Get WAF rule groups
free
pro
business
enterprise

Fetches the WAF rule groups in a WAF package.

GET zones/:zone_identifier/firewall/waf/packages/:package_identifier/groups

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the rule group. `"Project Honey Pot"`	read only
mode string	The state of the rules contained in the rule group. When `on`, the rules in the group are configurable/usable. `"on"`	default value: on valid values: on, off
rules_count number	The number of rules in the current rule group. `10`	default value: 0 read only
page number	The page number of paginated results. `1`	default value: 1 min value:1
per_page number	The number of rule groups per page. `50`	default value: 50 min value:5 max value:100
order	The field used to sort returned rule groups. `"mode"`	valid values: mode, rules_count
direction	The direction used to sort returned rule groups. `"desc"`	valid values: asc, desc
match	When set to `all`, all the search requirements must match. When set to `any`, only one of the search requirements has to match. `"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: user@example.com" \
     -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-get-a-waf-rule-group

GET Get a WAF rule group
free
pro
business
enterprise

Fetches the details of a WAF 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: user@example.com" \
     -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-update-a-waf-rule-group

PATCH Update a WAF rule group
free
pro
business
enterprise

Updates a WAF rule group. You can update the state (mode parameter) of a rule group.

PATCH zones/:zone_identifier/firewall/waf/packages/:package_identifier/groups/:identifier

Optional parameters

Name /type	Description /example	Constraints
mode string	The state of the rules contained in the rule group. When `on`, the rules in the 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: user@example.com" \
     -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

Web Application Firewall (WAF) rules of a WAF package applied to a zone.

waf-rules

Object definitions

View properties and constraints defined on the object

Show definitions

waf-rules-get-waf-rules

GET Get WAF rules
free
pro
business
enterprise

Fetches WAF rules in a WAF package.

GET zones/:zone_id/firewall/waf/packages/:package_id/rules

Optional parameters

Name /type	Description /example	Constraints
mode string	The action/mode a rule has been overridden to perform. `"CHL"`	valid values: DIS, CHL, BLK, SIM
priority string	The order in which the individual WAF rule is executed within its rule group. `5`	read only
match string	When set to `all`, all the search requirements must match. When set to `any`, only one of the search requirements has to match. `"all"`	default value: all valid values: any, all
order string	The field used to sort returned rules. `"status"`	valid values: priority, group_id, description
page number	The page number of paginated results. `1`	default value: 1 min value:1
per_page number	The number of rules per page. `50`	default value: 50 min value:5 max value:100
group_id string	The unique identifier of the rule group. `"de677e5818985db1285d0e80225f06e5"`	max length: 32 read only
description string	The public description of the WAF rule. `"SQL injection prevention for SELECT statements"`	read only
direction string	The direction used to sort returned 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: user@example.com" \
     -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-get-a-waf-rule

GET Get a WAF rule
free
pro
business
enterprise

Fetches the details of a WAF rule in a WAF package.

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: user@example.com" \
     -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-update-a-waf-rule

PATCH Update a WAF rule
free
pro
business
enterprise

Updates a WAF rule. You can only update the mode/action of the rule.

PATCH zones/:zone_id/firewall/waf/packages/:package_id/rules/:identifier

Optional parameters

Name /type	Description /example	Constraints
mode	The mode/action of the rule when triggered. You must use a value from the `allowed_modes` array of the current 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: user@example.com" \
     -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"
  }
}

WAF overrides

WAF configuration overrides allow you to enable or disable WAF packages for specific URL patterns.

waf-overrides

Object definition

View properties and constraints defined on the object

Show definition

waf-overrides-get-waf-overrides

GET Get WAF overrides
free
pro
business
enterprise

Fetches the URI-based WAF overrides in a zone.

GET zones/:zone_identifier/firewall/waf/overrides

Optional parameters

Name /type	Description /example	Constraints
page number	The page number of paginated results. `1`	default value: 1 min value:1
per_page number	The number of WAF overrides per page. `50`	default value: 50 min value:5 max value:100

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/waf/overrides?page=1&per_page=50" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "de677e5818985db1285d0e80225f06e5",
      "description": "Enable Cloudflare Magento ruleset for shop.example.com",
      "urls": [
        "shop.example.com/*"
      ],
      "priority": 1,
      "groups": {
        "ea8687e59929c1fd05ba97574ad43f77": "default"
      },
      "rules": {
        "100015": "disable"
      },
      "rewrite_action": {
        "default": "block",
        "challenge": "block",
        "simulate": "disable"
      }
    }
  ]
}

waf-overrides-create-a-waf-override

POST Create a WAF override
free
pro
business
enterprise

Creates a URI-based WAF override for a zone.

POST zones/:zone_identifier/firewall/waf/overrides

Required parameters

Name /type	Description /example	Constraints
urls array	The URLs to include in the current WAF override. You can use wildcards. Each entered URL will be escaped before use, which means you can only use simple wildcard patterns. `[ "shop.example.com/*" ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
paused boolean	When true, indicates that the WAF package is currently paused.	valid values: (true,false)
description stringnull	An informative summary of the current URI-based WAF override. `"Enable Cloudflare Magento ruleset for shop.example.com"`	max length: 1024
priority number	The relative priority of the current URI-based WAF override when multiple overrides match a single URL. A lower number indicates higher priority. Higher priority overrides may overwrite values set by lower priority overrides. `1`	min value:-1000000000 max value:1000000000
groups object	An object that allows you to enable or disable WAF rule groups for the current WAF override. Each key of this object must be the ID of a WAF rule group, and each value must be a valid WAF action (usually `default` or `disable`). When creating a new URI-based WAF override, you must provide a `groups` object or a `rules` object. `{ "ea8687e59929c1fd05ba97574ad43f77": "default" }`
rules object	An object that allows you to override the action of specific WAF rules. Each key of this object must be the ID of a WAF rule, and each value must be a valid WAF action. Unless you are disabling a rule, ensure that you also enable the rule group that this WAF rule belongs to. When creating a new URI-based WAF override, you must provide a `groups` object or a `rules` object. `{ "100015": "disable" }`
rewrite_action object	Specifies that, when a WAF rule matches, its configured action will be replaced by the action configured in this object. `{ "default": "block", "challenge": "block", "simulate": "disable" }` An object with the following properties: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/waf/overrides" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Enable Cloudflare Magento ruleset for shop.example.com","urls":["shop.example.com/*"],"priority":1,"groups":{"ea8687e59929c1fd05ba97574ad43f77":"default"},"rules":{"100015":"disable"},"rewrite_action":{"default":"block","challenge":"block","simulate":"disable"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "de677e5818985db1285d0e80225f06e5",
    "description": "Enable Cloudflare Magento ruleset for shop.example.com",
    "urls": [
      "shop.example.com/*"
    ],
    "priority": 1,
    "groups": {
      "ea8687e59929c1fd05ba97574ad43f77": "default"
    },
    "rules": {
      "100015": "disable"
    },
    "rewrite_action": {
      "default": "block",
      "challenge": "block",
      "simulate": "disable"
    }
  }
}

waf-overrides-get-a-waf-override

GET Get a WAF override
free
pro
business
enterprise

Fetches the details of a URI-based WAF override.

GET zones/:zone_identifier/firewall/waf/overrides/:id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/waf/overrides/de677e5818985db1285d0e80225f06e5" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "de677e5818985db1285d0e80225f06e5",
    "description": "Enable Cloudflare Magento ruleset for shop.example.com",
    "urls": [
      "shop.example.com/*"
    ],
    "priority": 1,
    "groups": {
      "ea8687e59929c1fd05ba97574ad43f77": "default"
    },
    "rules": {
      "100015": "disable"
    },
    "rewrite_action": {
      "default": "block",
      "challenge": "block",
      "simulate": "disable"
    }
  }
}

waf-overrides-update-waf-override

PUT Update WAF override
free
pro
business
enterprise

Updates an existing URI-based WAF override.

PUT zones/:zone_identifier/firewall/waf/overrides/:id

Required parameters

Name /type	Description /example	Constraints
urls array	The URLs to include in the current WAF override. You can use wildcards. Each entered URL will be escaped before use, which means you can only use simple wildcard patterns. `[ "shop.example.com/*" ]` An array with items in the following form: Show definition »
rules object	An object that allows you to override the action of specific WAF rules. Each key of this object must be the ID of a WAF rule, and each value must be a valid WAF action. Unless you are disabling a rule, ensure that you also enable the rule group that this WAF rule belongs to. When creating a new URI-based WAF override, you must provide a `groups` object or a `rules` object. `{ "100015": "disable" }`
rewrite_action object	Specifies that, when a WAF rule matches, its configured action will be replaced by the action configured in this object. `{ "default": "block", "challenge": "block", "simulate": "disable" }` An object with the following properties: Show definition »

Optional parameters

Name /type	Description /example	Constraints
paused boolean	When true, indicates that the WAF package is currently paused.	valid values: (true,false)
description stringnull	An informative summary of the current URI-based WAF override. `"Enable Cloudflare Magento ruleset for shop.example.com"`	max length: 1024
priority number	The relative priority of the current URI-based WAF override when multiple overrides match a single URL. A lower number indicates higher priority. Higher priority overrides may overwrite values set by lower priority overrides. `1`	min value:-1000000000 max value:1000000000
groups object	An object that allows you to enable or disable WAF rule groups for the current WAF override. Each key of this object must be the ID of a WAF rule group, and each value must be a valid WAF action (usually `default` or `disable`). When creating a new URI-based WAF override, you must provide a `groups` object or a `rules` object. `{ "ea8687e59929c1fd05ba97574ad43f77": "default" }`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/waf/overrides/de677e5818985db1285d0e80225f06e5" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Enable Cloudflare Magento ruleset for shop.example.com","urls":["shop.example.com/*"],"priority":1,"groups":{"ea8687e59929c1fd05ba97574ad43f77":"default"},"rules":{"100015":"disable"},"rewrite_action":{"default":"block","challenge":"block","simulate":"disable"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "de677e5818985db1285d0e80225f06e5",
    "description": "Enable Cloudflare Magento ruleset for shop.example.com",
    "urls": [
      "shop.example.com/*"
    ],
    "priority": 1,
    "groups": {
      "ea8687e59929c1fd05ba97574ad43f77": "default"
    },
    "rules": {
      "100015": "disable"
    },
    "rewrite_action": {
      "default": "block",
      "challenge": "block",
      "simulate": "disable"
    }
  }
}

waf-overrides-delete-a-waf-override

DELETE Delete a WAF override
free
pro
business
enterprise

Deletes an existing URI-based WAF override.

DELETE zones/:zone_identifier/firewall/waf/overrides/:id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/waf/overrides/de677e5818985db1285d0e80225f06e5" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "result": {
    "id": "de677e5818985db1285d0e80225f06e5"
  }
}

WAF overrides 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

User Agent Blocking rules

User Agent Blocking rules perform access control for incoming requests that exactly match the "User-Agent" HTTP header value reported by the client.

user-agent-blocking-rules

Object definition

View properties and constraints defined on the object

Show definition

user-agent-blocking-rules-get-user-agent-blocking-rules

GET Get User Agent Blocking rules
free
pro
business
enterprise

Fetches User Agent Blocking rules in a zone. You can filter the results using several optional parameters.

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	The maximum number of results per page. You can only set the value to `1` or to a multiple of 5 such as `5`, `10`, `15`, or `20`. `20`	default value: 20 min value:1 max value:1000
description string	A string to search for in the description of existing rules. `"abusive"`
user_agent string	A string to search for in the user agent values of existing rules. `"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: user@example.com" \
     -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 User Agent to mitigate a 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-create-a-user-agent-blocking-rule

POST Create a User Agent Blocking rule
free
pro
business
enterprise

Creates a new User Agent Blocking rule in a zone.

POST zones/:zone_identifier/firewall/ua_rules

Required parameters

Name /type	Description /example	Constraints
mode	The action to apply to a matched request. `"js_challenge"`	max length: 12 valid values: block, challenge, js_challenge, managed_challenge
configuration object	The configuration object for the current rule. `{ "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	The unique identifier of the User Agent Blocking rule. `"372e67954025e0ba6aaa6d586b9e0b59"`	max length: 32 read only
paused boolean	When true, indicates that the rule is currently paused. `false`	valid values: (true,false)
description string	An informative summary of the rule. `"Prevent access from abusive clients identified by this User Agent to mitigate a 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"372e67954025e0ba6aaa6d586b9e0b59","paused":false,"description":"Prevent access from abusive clients identified by this User Agent to mitigate a 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 User Agent to mitigate a 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-get-a-user-agent-blocking-rule

GET Get a User Agent Blocking rule
free
pro
business
enterprise

Fetches the details of a User Agent Blocking rule.

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: user@example.com" \
     -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 User Agent to mitigate a 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-a-user-agent-blocking-rule

PUT Update a User Agent Blocking rule
free
pro
business
enterprise

Updates an existing User Agent Blocking rule.

PUT zones/:zone_identifier/firewall/ua_rules/:id

Required parameters

Name /type	Description /example	Constraints
id string	The unique identifier of the User Agent Blocking rule. `"372e67954025e0ba6aaa6d586b9e0b59"`	max length: 32 read only
mode	The action to apply to a matched request. `"js_challenge"`	max length: 12 valid values: block, challenge, js_challenge, managed_challenge
configuration object	The configuration object for the current rule. `{ "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	When true, indicates that the rule is currently paused. `false`	valid values: (true,false)
description string	An informative summary of the rule. `"Prevent access from abusive clients identified by this User Agent to mitigate a 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"372e67954025e0ba6aaa6d586b9e0b59","paused":false,"description":"Prevent access from abusive clients identified by this User Agent to mitigate a 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 User Agent to mitigate a 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-a-user-agent-blocking-rule

DELETE Delete a User Agent Blocking rule
free
pro
business
enterprise

Deletes an existing User Agent Blocking rule.

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: user@example.com" \
     -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

Zone Lockdown allows you to restrict access to URLs in a zone to specific IP addresses and IP address ranges.

The URLs configured in a Zone Lockdown rule support wildcard matching on the domain or path.

zone-lockdown

Object definition

View properties and constraints defined on the object

Show definition

zone-lockdown-get-zone-lockdown-rules

GET Get Zone Lockdown rules
free
pro
business
enterprise

Fetches Zone Lockdown rules. You can filter the results using several optional parameters.

GET zones/:zone_identifier/firewall/lockdowns

Optional parameters

Name /type	Description /example	Constraints
priority number	The priority of the rule to control the processing order. A lower number indicates higher priority. If not provided, any rules with a configured priority will be processed before rules without a priority. `"5"`
ip_range string	A single IP address range to search for in existing rules. `"1.2.3.0/16"`
ip string	A single IP address to search for in existing rules. `"1.2.3.4"`
uri string	A single URI to search for in the list of URLs of existing rules. `"/some/path"`
page number	Page number of paginated results. `1`	default value: 1 min value:1
per_page number	The maximum number of results per page. You can only set the value to `1` or to a multiple of 5 such as `5`, `10`, `15`, or `20`. `20`	default value: 20 min value:1 max value:1000
modified_on string (date-time)	The timestamp of when the rule was last modified. `"2014-01-01T05:20:00.12345Z"`	read only
created_on string (date-time)	The timestamp of when the rule was created. `"2014-01-01T05:20:00.12345Z"`	read only
description string	A string to search for in the description of existing rules. `"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: user@example.com" \
     -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-create-a-zone-lockdown-rule

POST Create a Zone Lockdown rule
free
pro
business
enterprise

Creates a new Zone Lockdown rule.

POST zones/:zone_identifier/firewall/lockdowns

Required parameters

Name /type	Description /example	Constraints
urls array	The URLs to include in the rule definition. You can use wildcards. Each entered URL will be escaped before use, which means you can only use simple wildcard patterns. `[ "api.mysite.com/some/endpoint*" ]` An array with items in the following form: Show definition »
configurations array	A list of IP addresses or CIDR ranges that will be allowed to access the URLs specified in the Zone Lockdown rule. You can include any number of `ip` or `ip_range` configurations. `[ { "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	When true, indicates that the rule is currently paused. `false`	valid values: (true,false)
description string	An informative summary of the 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: user@example.com" \
     -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-get-a-zone-lockdown-rule

GET Get a Zone Lockdown rule
free
pro
business
enterprise

Fetches the details of a Zone Lockdown rule.

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: user@example.com" \
     -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-a-zone-lockdown-rule

PUT Update a Zone Lockdown rule
free
pro
business
enterprise

Updates an existing Zone Lockdown rule.

PUT zones/:zone_identifier/firewall/lockdowns/:id

Required parameters

Name /type	Description /example	Constraints
urls array	The URLs to include in the rule definition. You can use wildcards. Each entered URL will be escaped before use, which means you can only use simple wildcard patterns. `[ "api.mysite.com/some/endpoint*" ]` An array with items in the following form: Show definition »
configurations array	A list of IP addresses or CIDR ranges that will be allowed to access the URLs specified in the Zone Lockdown rule. You can include any number of `ip` or `ip_range` configurations. `[ { "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	When true, indicates that the rule is currently paused. `false`	valid values: (true,false)
description string	An informative summary of the 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: user@example.com" \
     -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-a-zone-lockdown-rule

DELETE Delete a Zone Lockdown rule
free
pro
business
enterprise

Deletes an existing Zone Lockdown rule.

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: user@example.com" \
     -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 rules

Firewall rules allow you to create rules that inspect incoming traffic and take action on specific requests.

A firewall rule uses a filter to select traffic. For more information, refer to Manage firewall rules via the APIs.

firewall-rules

Object definition

View properties and constraints defined on the object

Show definition

firewall-rules-get-firewall-rules

GET Get firewall rules
free
pro
business
enterprise

Fetches firewall rules in a zone. You can filter the results using several optional parameters.

GET zones/:zone_identifier/firewall/rules

Optional parameters

Name /type	Description /example	Constraints
id string	The unique identifier of the firewall rule. `"372e67954025e0ba6aaa6d586b9e0b60"`	max length: 32 read only
description string	A case-insensitive string to find in the description. `"mir"`
action string	The action to search for. Must be an exact match. `"block"`
paused boolean	When true, indicates that the firewall rule is currently paused. `false`	valid values: (true,false)
page number	Page number of paginated results. `1`	default value: 1 min value:1
per_page number	Number of firewall rules per page. `25`	default value: 25 min value:5 max value:100

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/rules?id=372e67954025e0ba6aaa6d586b9e0b60&description=mir&action=block&paused=false&page=1&per_page=25" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "372e67954025e0ba6aaa6d586b9e0b60",
      "action": "block",
      "products": [
        "waf"
      ],
      "priority": 50,
      "paused": false,
      "description": "Blocks traffic identified during investigation for MIR-31",
      "ref": "MIR-31",
      "filter": {
        "id": "372e67954025e0ba6aaa6d586b9e0b61",
        "expression": "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155",
        "paused": false,
        "description": "Restrict access from these browsers on this address range.",
        "ref": "FIL-100"
      }
    }
  ]
}

firewall-rules-get-a-firewall-rule

GET Get a firewall rule
free
pro
business
enterprise

Fetches the details of a firewall rule.

GET zones/:zone_identifier/firewall/rules/:id

Required parameters

Name /type	Description /example	Constraints
id string	The unique identifier of the firewall rule. `"372e67954025e0ba6aaa6d586b9e0b60"`	max length: 32 read only

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/rules/372e67954025e0ba6aaa6d586b9e0b60?id=372e67954025e0ba6aaa6d586b9e0b60" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b60",
    "action": "block",
    "products": [
      "waf"
    ],
    "priority": 50,
    "paused": false,
    "description": "Blocks traffic identified during investigation for MIR-31",
    "ref": "MIR-31",
    "filter": {
      "id": "372e67954025e0ba6aaa6d586b9e0b61",
      "expression": "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155",
      "paused": false,
      "description": "Restrict access from these browsers on this address range.",
      "ref": "FIL-100"
    }
  }
}

firewall-rules-create-firewall-rules

POST Create firewall rules
free
pro
business
enterprise

Create one or more firewall rules.

POST zones/:zone_identifier/firewall/rules

Required parameters

Name /type	Description /example	Constraints
action string	The action to apply to a matched request. The `log` action is only available on an Enterprise plan. `"block"`	valid values: block, challenge, js_challenge, managed_challenge, allow, log, bypass
filter object	`{ "id": "372e67954025e0ba6aaa6d586b9e0b61", "expression": "(http.request.uri.path ~ \".wp-login.php\" or http.request.uri.path ~ \".xmlrpc.php\") and ip.addr ne 172.16.22.155", "paused": false, "description": "Restrict access from these browsers on this address range.", "ref": "FIL-100" }` An object with the following properties: Show definition »

Optional parameters

Name /type	Description /example	Constraints
id string	The unique identifier of the firewall rule. `"372e67954025e0ba6aaa6d586b9e0b60"`	max length: 32 read only
products array	`[ "waf" ]` An array with items in the following form: Show definition »
priority number	The priority of the rule. Optional value used to define the processing order. A lower number indicates a higher priority. If not provided, rules with a defined priority will be processed before rules without a priority. `50`	min value:0 max value:2147483647
paused boolean	When true, indicates that the firewall rule is currently paused. `false`	valid values: (true,false)
description string	An informative summary of the firewall rule. `"Blocks traffic identified during investigation for MIR-31"`	max length: 500
ref string	A short reference tag. Allows you to select related firewall rules. `"MIR-31"`	max length: 50

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/rules" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '[{"id":"372e67954025e0ba6aaa6d586b9e0b60","action":"block","products":["waf"],"priority":50,"paused":false,"description":"Blocks traffic identified during investigation for MIR-31","ref":"MIR-31","filter":{"id":"372e67954025e0ba6aaa6d586b9e0b61","expression":"(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155","paused":false,"description":"Restrict access from these browsers on this address range.","ref":"FIL-100"}}]'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "372e67954025e0ba6aaa6d586b9e0b60",
      "action": "block",
      "products": [
        "waf"
      ],
      "priority": 50,
      "paused": false,
      "description": "Blocks traffic identified during investigation for MIR-31",
      "ref": "MIR-31",
      "filter": {
        "id": "372e67954025e0ba6aaa6d586b9e0b61",
        "expression": "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155",
        "paused": false,
        "description": "Restrict access from these browsers on this address range.",
        "ref": "FIL-100"
      }
    }
  ]
}

firewall-rules-update-firewall-rules

PUT Update firewall rules
free
pro
business
enterprise

Updates one or more existing firewall rules.

PUT zones/:zone_identifier/firewall/rules

Required parameters

Name /type	Description /example	Constraints
id string	The unique identifier of the firewall rule. `"372e67954025e0ba6aaa6d586b9e0b60"`	max length: 32 read only

Optional parameters

Name /type	Description /example	Constraints
action string	The action to apply to a matched request. The `log` action is only available on an Enterprise plan. `"block"`	valid values: block, challenge, js_challenge, managed_challenge, allow, log, bypass
products array	`[ "waf" ]` An array with items in the following form: Show definition »
priority number	The priority of the rule. Optional value used to define the processing order. A lower number indicates a higher priority. If not provided, rules with a defined priority will be processed before rules without a priority. `50`	min value:0 max value:2147483647
paused boolean	When true, indicates that the firewall rule is currently paused. `false`	valid values: (true,false)
description string	An informative summary of the firewall rule. `"Blocks traffic identified during investigation for MIR-31"`	max length: 500
ref string	A short reference tag. Allows you to select related firewall rules. `"MIR-31"`	max length: 50
filter object	`{ "id": "372e67954025e0ba6aaa6d586b9e0b61", "expression": "(http.request.uri.path ~ \".wp-login.php\" or http.request.uri.path ~ \".xmlrpc.php\") and ip.addr ne 172.16.22.155", "paused": false, "description": "Restrict access from these browsers on this address range.", "ref": "FIL-100" }` An object with the following properties: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/rules" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '[{"id":"372e67954025e0ba6aaa6d586b9e0b60","action":"block","products":["waf"],"priority":50,"paused":false,"description":"Blocks traffic identified during investigation for MIR-31","ref":"MIR-31","filter":{"id":"372e67954025e0ba6aaa6d586b9e0b61","expression":"(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155","paused":false,"description":"Restrict access from these browsers on this address range.","ref":"FIL-100"}}]'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "372e67954025e0ba6aaa6d586b9e0b60",
      "action": "block",
      "products": [
        "waf"
      ],
      "priority": 50,
      "paused": false,
      "description": "Blocks traffic identified during investigation for MIR-31",
      "ref": "MIR-31",
      "filter": {
        "id": "372e67954025e0ba6aaa6d586b9e0b61",
        "expression": "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155",
        "paused": false,
        "description": "Restrict access from these browsers on this address range.",
        "ref": "FIL-100"
      }
    }
  ]
}

firewall-rules-update-a-firewall-rule

PUT Update a firewall rule
free
pro
business
enterprise

Updates an existing firewall rule.

PUT zones/:zone_identifier/firewall/rules/:id

Required parameters

Name /type	Description /example	Constraints
id string	The unique identifier of the firewall rule. `"372e67954025e0ba6aaa6d586b9e0b60"`	max length: 32 read only
action string	The action to apply to a matched request. The `log` action is only available on an Enterprise plan. `"block"`	valid values: block, challenge, js_challenge, managed_challenge, allow, log, bypass
filter object	`{ "id": "372e67954025e0ba6aaa6d586b9e0b61", "expression": "(http.request.uri.path ~ \".wp-login.php\" or http.request.uri.path ~ \".xmlrpc.php\") and ip.addr ne 172.16.22.155", "paused": false, "description": "Restrict access from these browsers on this address range.", "ref": "FIL-100" }` An object with the following properties: Show definition »

Optional parameters

Name /type	Description /example	Constraints
products array	`[ "waf" ]` An array with items in the following form: Show definition »
priority number	The priority of the rule. Optional value used to define the processing order. A lower number indicates a higher priority. If not provided, rules with a defined priority will be processed before rules without a priority. `50`	min value:0 max value:2147483647
paused boolean	When true, indicates that the firewall rule is currently paused. `false`	valid values: (true,false)
description string	An informative summary of the firewall rule. `"Blocks traffic identified during investigation for MIR-31"`	max length: 500
ref string	A short reference tag. Allows you to select related firewall rules. `"MIR-31"`	max length: 50

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/rules/372e67954025e0ba6aaa6d586b9e0b60" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"372e67954025e0ba6aaa6d586b9e0b60","action":"block","products":["waf"],"priority":50,"paused":false,"description":"Blocks traffic identified during investigation for MIR-31","ref":"MIR-31","filter":{"id":"372e67954025e0ba6aaa6d586b9e0b61","expression":"(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155","paused":false,"description":"Restrict access from these browsers on this address range.","ref":"FIL-100"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b60",
    "action": "block",
    "products": [
      "waf"
    ],
    "priority": 50,
    "paused": false,
    "description": "Blocks traffic identified during investigation for MIR-31",
    "ref": "MIR-31",
    "filter": {
      "id": "372e67954025e0ba6aaa6d586b9e0b61",
      "expression": "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155",
      "paused": false,
      "description": "Restrict access from these browsers on this address range.",
      "ref": "FIL-100"
    }
  }
}

firewall-rules-update-priority-of-firewall-rules-

PATCH Update priority of firewall rules
free
pro
business
enterprise

Updates the priority of existing firewall rules.

PATCH zones/:zone_identifier/firewall/rules

Required parameters

Name /type	Description /example	Constraints
id string	The unique identifier of the firewall rule. `"372e67954025e0ba6aaa6d586b9e0b60"`	max length: 32 read only

Optional parameters

Name /type	Description /example	Constraints
priority number	The priority of the rule. Optional value used to define the processing order. A lower number indicates a higher priority. If not provided, rules with a defined priority will be processed before rules without a priority. `50`	min value:0 max value:2147483647

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/rules" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '[{"id":"372e67954025e0ba6aaa6d586b9e0b60","priority":50}]'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "372e67954025e0ba6aaa6d586b9e0b60",
      "action": "block",
      "products": [
        "waf"
      ],
      "priority": 50,
      "paused": false,
      "description": "Blocks traffic identified during investigation for MIR-31",
      "ref": "MIR-31",
      "filter": {
        "id": "372e67954025e0ba6aaa6d586b9e0b61",
        "expression": "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155",
        "paused": false,
        "description": "Restrict access from these browsers on this address range.",
        "ref": "FIL-100"
      }
    }
  ]
}

firewall-rules-update-priority-of-a-firewall-rule

PATCH Update priority of a firewall rule
free
pro
business
enterprise

Updates the priority of an existing firewall rule.

PATCH zones/:zone_identifier/firewall/rules/:id

Required parameters

Name /type	Description /example	Constraints
id string	The unique identifier of the firewall rule. `"372e67954025e0ba6aaa6d586b9e0b60"`	max length: 32 read only

Optional parameters

Name /type	Description /example	Constraints
priority number	The priority of the rule. Optional value used to define the processing order. A lower number indicates a higher priority. If not provided, rules with a defined priority will be processed before rules without a priority. `50`	min value:0 max value:2147483647

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/rules/372e67954025e0ba6aaa6d586b9e0b60" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"372e67954025e0ba6aaa6d586b9e0b60","priority":50}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "372e67954025e0ba6aaa6d586b9e0b60",
      "action": "block",
      "products": [
        "waf"
      ],
      "priority": 50,
      "paused": false,
      "description": "Blocks traffic identified during investigation for MIR-31",
      "ref": "MIR-31",
      "filter": {
        "id": "372e67954025e0ba6aaa6d586b9e0b61",
        "expression": "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155",
        "paused": false,
        "description": "Restrict access from these browsers on this address range.",
        "ref": "FIL-100"
      }
    }
  ]
}

firewall-rules-delete-firewall-rules

DELETE Delete firewall rules
free
pro
business
enterprise

Deletes existing firewall rules.

DELETE zones/:zone_identifier/firewall/rules

Required parameters

Name /type	Description /example	Constraints
id string	The unique identifier of the firewall rule. `"372e67954025e0ba6aaa6d586b9e0b60"`	max length: 32 read only

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/rules" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"372e67954025e0ba6aaa6d586b9e0b60"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "372e67954025e0ba6aaa6d586b9e0b60",
      "action": "block",
      "products": [
        "waf"
      ],
      "priority": 50,
      "paused": false,
      "description": "Blocks traffic identified during investigation for MIR-31",
      "ref": "MIR-31",
      "filter": {
        "id": "372e67954025e0ba6aaa6d586b9e0b61",
        "expression": "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155",
        "paused": false,
        "description": "Restrict access from these browsers on this address range.",
        "ref": "FIL-100"
      }
    }
  ]
}

firewall-rules-delete-a-firewall-rule

DELETE Delete a firewall rule
free
pro
business
enterprise

Deletes an existing firewall rule.

DELETE zones/:zone_identifier/firewall/rules/:id

Optional parameters

Name /type	Description /example	Constraints
delete_filter_if_unused boolean	When true, indicates that Cloudflare should also delete the associated filter if there are no other firewall rules referencing the filter.	valid values: (true,false)

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/firewall/rules/372e67954025e0ba6aaa6d586b9e0b60" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b60",
    "action": "block",
    "products": [
      "waf"
    ],
    "priority": 50,
    "paused": false,
    "description": "Blocks traffic identified during investigation for MIR-31",
    "ref": "MIR-31",
    "filter": {
      "id": "372e67954025e0ba6aaa6d586b9e0b61",
      "expression": "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155",
      "paused": false,
      "description": "Restrict access from these browsers on this address range.",
      "ref": "FIL-100"
    }
  }
}

Firewall rules error codes

Code	Description
10000	Invalid user

Filters

A filter defines an expression that you can use across multiple features.

Currently, the only API that uses filters is the Firewall Rules API. For more information, refer to Manage firewall rules via the APIs.

filters

Object definition

View properties and constraints defined on the object

Show definition

filters-get-filters

GET Get filters
free
pro
business
enterprise

Fetches filters in a zone. You can filter the results using several optional parameters.

GET zones/:zone_identifier/filters

Optional parameters

Name /type	Description /example	Constraints
id string	The unique identifier of the filter. `"372e67954025e0ba6aaa6d586b9e0b61"`	min length: 32 max length: 32 read only
paused boolean	When true, indicates that the filter is currently paused. `false`	valid values: (true,false)
expression string	A case-insensitive string to find in the expression. `"php"`
description string	A case-insensitive string to find in the description. `"browsers"`
ref string	The filter ref (a short reference tag) to search for. Must be an exact match. `"FIL-100"`
page number	Page number of paginated results. `1`	default value: 1 min value:1
per_page number	Number of filters per page. `25`	default value: 25 min value:5 max value:100

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/filters?id=372e67954025e0ba6aaa6d586b9e0b61&paused=false&expression=php&description=browsers&ref=FIL-100&page=1&per_page=25" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "372e67954025e0ba6aaa6d586b9e0b61",
      "expression": "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155",
      "paused": false,
      "description": "Restrict access from these browsers on this address range.",
      "ref": "FIL-100"
    }
  ]
}

filters-get-a-filter

GET Get a filter
free
pro
business
enterprise

Fetches the details of a filter.

GET zones/:zone_identifier/filters/:id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/filters/372e67954025e0ba6aaa6d586b9e0b61" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b61",
    "expression": "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155",
    "paused": false,
    "description": "Restrict access from these browsers on this address range.",
    "ref": "FIL-100"
  }
}

filters-create-filters

POST Create filters
free
pro
business
enterprise

Creates one or more filters.

POST zones/:zone_identifier/filters

Required parameters

Name /type	Description /example	Constraints
expression string	The filter expression. For more information, refer to Expressions. `"(http.request.uri.path ~ \".wp-login.php\" or http.request.uri.path ~ \".xmlrpc.php\") and ip.addr ne 172.16.22.155"`

Optional parameters

Name /type	Description /example	Constraints
id string	The unique identifier of the filter. `"372e67954025e0ba6aaa6d586b9e0b61"`	min length: 32 max length: 32 read only
paused boolean	When true, indicates that the filter is currently paused. `false`	valid values: (true,false)
description string	An informative summary of the filter. `"Restrict access from these browsers on this address range."`	max length: 500
ref string	A short reference tag. Allows you to select related filters. `"FIL-100"`	max length: 50

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/filters" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '[{"id":"372e67954025e0ba6aaa6d586b9e0b61","expression":"(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155","paused":false,"description":"Restrict access from these browsers on this address range.","ref":"FIL-100"}]'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "372e67954025e0ba6aaa6d586b9e0b61",
      "expression": "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155",
      "paused": false,
      "description": "Restrict access from these browsers on this address range.",
      "ref": "FIL-100"
    }
  ]
}

filters-update-filters

PUT Update filters
free
pro
business
enterprise

Updates one or more existing filters.

PUT zones/:zone_identifier/filters

Required parameters

Name /type	Description /example	Constraints
id string	The unique identifier of the filter. `"372e67954025e0ba6aaa6d586b9e0b61"`	min length: 32 max length: 32 read only

Optional parameters

Name /type	Description /example	Constraints
expression string	The filter expression. For more information, refer to Expressions. `"(http.request.uri.path ~ \".wp-login.php\" or http.request.uri.path ~ \".xmlrpc.php\") and ip.addr ne 172.16.22.155"`
paused boolean	When true, indicates that the filter is currently paused. `false`	valid values: (true,false)
description string	An informative summary of the filter. `"Restrict access from these browsers on this address range."`	max length: 500
ref string	A short reference tag. Allows you to select related filters. `"FIL-100"`	max length: 50

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/filters" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '[{"id":"372e67954025e0ba6aaa6d586b9e0b61","expression":"(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155","paused":false,"description":"Restrict access from these browsers on this address range.","ref":"FIL-100"}]'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "372e67954025e0ba6aaa6d586b9e0b61",
      "expression": "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155",
      "paused": false,
      "description": "Restrict access from these browsers on this address range.",
      "ref": "FIL-100"
    }
  ]
}

filters-update-a-filter

PUT Update a filter
free
pro
business
enterprise

Updates an existing filter.

PUT zones/:zone_identifier/filters/:id

Required parameters

Name /type	Description /example	Constraints
id string	The unique identifier of the filter. `"372e67954025e0ba6aaa6d586b9e0b61"`	min length: 32 max length: 32 read only

Optional parameters

Name /type	Description /example	Constraints
expression string	The filter expression. For more information, refer to Expressions. `"(http.request.uri.path ~ \".wp-login.php\" or http.request.uri.path ~ \".xmlrpc.php\") and ip.addr ne 172.16.22.155"`
paused boolean	When true, indicates that the filter is currently paused. `false`	valid values: (true,false)
description string	An informative summary of the filter. `"Restrict access from these browsers on this address range."`	max length: 500
ref string	A short reference tag. Allows you to select related filters. `"FIL-100"`	max length: 50

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/filters/372e67954025e0ba6aaa6d586b9e0b61" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"372e67954025e0ba6aaa6d586b9e0b61","expression":"(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155","paused":false,"description":"Restrict access from these browsers on this address range.","ref":"FIL-100"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b61",
    "expression": "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155",
    "paused": false,
    "description": "Restrict access from these browsers on this address range.",
    "ref": "FIL-100"
  }
}

filters-delete-filters

DELETE Delete filters
free
pro
business
enterprise

Deletes one or more existing filters.

DELETE zones/:zone_identifier/filters

Required parameters

Name /type	Description /example	Constraints
id string	The unique identifier of the filter. `"372e67954025e0ba6aaa6d586b9e0b61"`	min length: 32 max length: 32 read only

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/filters" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"id":"372e67954025e0ba6aaa6d586b9e0b61"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "372e67954025e0ba6aaa6d586b9e0b61",
      "expression": "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155",
      "paused": false,
      "description": "Restrict access from these browsers on this address range.",
      "ref": "FIL-100"
    }
  ]
}

filters-delete-a-filter

DELETE Delete a filter
free
pro
business
enterprise

Deletes an existing filter.

DELETE zones/:zone_identifier/filters/:id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/filters/372e67954025e0ba6aaa6d586b9e0b61" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "372e67954025e0ba6aaa6d586b9e0b61",
    "expression": "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155",
    "paused": false,
    "description": "Restrict access from these browsers on this address range.",
    "ref": "FIL-100"
  }
}

Filters error codes

Code	Description
10000	Invalid user

Lists

Lists you can use in filter and rule expressions.

There are two types of lists: IP address lists and redirect lists.

lists

Object definition

View properties and constraints defined on the object

Show definition

lists-get-lists

GET Get lists
free
pro
business
enterprise

Fetches all lists in the account.

GET accounts/:account_identifier/rules/lists

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rules/lists" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "2c0fc9fa937b11eaa1b71c4d701ab86e",
      "name": "list1",
      "description": "This is a note.",
      "kind": "ip",
      "num_items": 10,
      "num_referencing_filters": 2,
      "created_on": "2020-01-01T08:00:00Z",
      "modified_on": "2020-01-10T14:00:00Z"
    }
  ]
}

lists-create-a-list

POST Create a list
free
pro
business
enterprise

Creates a new list of the specified type.

POST accounts/:account_identifier/rules/lists

Required parameters

Name /type	Description /example	Constraints
name string	An informative name for the list. Use this name in filter and rule expressions. `"list1"`	max length: 50 pattern: ^[a-zA-Z0-9_]+$
kind string	The type of the list. Each type supports specific list items (IP addresses or redirects). `"ip"`	valid values: ip, redirect

Optional parameters

Name /type	Description /example	Constraints
description string	An informative summary of the list. `"This is a note."`	max length: 500

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rules/lists" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"list1","description":"This is a note.","kind":"ip"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2c0fc9fa937b11eaa1b71c4d701ab86e",
    "name": "list1",
    "description": "This is a note.",
    "kind": "ip",
    "num_items": 10,
    "num_referencing_filters": 2,
    "created_on": "2020-01-01T08:00:00Z",
    "modified_on": "2020-01-10T14:00:00Z"
  }
}

lists-get-a-list

GET Get a list
free
pro
business
enterprise

Fetches the details of a list.

GET accounts/:account_identifier/rules/lists/:list_id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rules/lists/2c0fc9fa937b11eaa1b71c4d701ab86e" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2c0fc9fa937b11eaa1b71c4d701ab86e",
    "name": "list1",
    "description": "This is a note.",
    "kind": "ip",
    "num_items": 10,
    "num_referencing_filters": 2,
    "created_on": "2020-01-01T08:00:00Z",
    "modified_on": "2020-01-10T14:00:00Z"
  }
}

lists-update-a-list

PUT Update a list
free
pro
business
enterprise

Updates the description of a list.

PUT accounts/:account_identifier/rules/lists/:list_id

Optional parameters

Name /type	Description /example	Constraints
description string	An informative summary of the list. `"This is a note."`	max length: 500

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rules/lists/2c0fc9fa937b11eaa1b71c4d701ab86e" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"This is a note."}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2c0fc9fa937b11eaa1b71c4d701ab86e",
    "name": "list1",
    "description": "This is a note.",
    "kind": "ip",
    "num_items": 10,
    "num_referencing_filters": 2,
    "created_on": "2020-01-01T08:00:00Z",
    "modified_on": "2020-01-10T14:00:00Z"
  }
}

lists-delete-a-list

DELETE Delete a list
free
pro
business
enterprise

Deletes a specific list and all its items.

DELETE accounts/:account_identifier/rules/lists/:list_id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rules/lists/2c0fc9fa937b11eaa1b71c4d701ab86e" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

lists-get-list-items

GET Get list items
free
pro
business
enterprise

Fetches all the items in the list.

GET accounts/:account_identifier/rules/lists/:list_id/items

Optional parameters

Name /type	Description /example	Constraints
cursor string	The pagination cursor. An opaque string token indicating the position from which to continue when requesting the next/previous set of records. Cursor values are provided under `result_info.cursors` in the response. You should make no assumptions about a cursor's content or length. `"zzz"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rules/lists/2c0fc9fa937b11eaa1b71c4d701ab86e/items?cursor=zzz" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "2c0fc9fa937b11eaa1b71c4d701ab86e",
      "ip": "10.0.0.1",
      "comment": "Private IP address",
      "created_on": "2020-01-01T08:00:00Z",
      "modified_on": "2020-01-10T14:00:00Z"
    }
  ],
  "result_info": {
    "cursors": {
      "before": "xxx",
      "after": "yyy"
    }
  }
}

lists-create-list-items

POST Create list items
free
pro
business
enterprise

Appends new items to the list.

This operation is asynchronous. To get current the operation status, invoke the Get bulk operation status endpoint with the returned operation_id.

POST accounts/:account_identifier/rules/lists/:list_id/items

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rules/lists/2c0fc9fa937b11eaa1b71c4d701ab86e/items" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '[{}]'

Response (example)

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

lists-update-all-list-items

PUT Update all list items
free
pro
business
enterprise

Removes all existing items from the list and adds the provided items to the list.

This operation is asynchronous. To get current the operation status, invoke the Get bulk operation status endpoint with the returned operation_id.

PUT accounts/:account_identifier/rules/lists/:list_id/items

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rules/lists/2c0fc9fa937b11eaa1b71c4d701ab86e/items" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '[{}]'

Response (example)

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

lists-delete-list-items

DELETE Delete list items
free
pro
business
enterprise

Removes one or more items from a list.

This operation is asynchronous. To get current the operation status, invoke the Get bulk operation status endpoint with the returned operation_id.

DELETE accounts/:account_identifier/rules/lists/:list_id/items

Optional parameters

Name /type	Description /example	Constraints
items array	`[ { "id": "34b12448945f11eaa1b71c4d701ab86e" } ]` An array with items in the following form: Show definition »	min items: 1

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rules/lists/2c0fc9fa937b11eaa1b71c4d701ab86e/items" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"items":[{"id":"34b12448945f11eaa1b71c4d701ab86e"}]}'

Response (example)

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

lists-get-a-list-item

GET Get a list item
free
pro
business
enterprise

Fetches a list item in the list.

GET accounts/:account_identifier/rules/lists/:list_id/items/:item_id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rules/lists/2c0fc9fa937b11eaa1b71c4d701ab86e/items/34b12448945f11eaa1b71c4d701ab86e" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2c0fc9fa937b11eaa1b71c4d701ab86e",
    "ip": "10.0.0.1",
    "redirect": {
      "source_url": "example.com/arch",
      "target_url": "https://archlinux.org/",
      "status_code": 301,
      "include_subdomains": false,
      "subpath_matching": false,
      "preserve_query_string": false,
      "preserve_path_suffix": true
    },
    "comment": "Private IP address",
    "created_on": "2020-01-01T08:00:00Z",
    "modified_on": "2020-01-10T14:00:00Z"
  }
}

lists-get-bulk-operation-status

GET Get bulk operation status
free
pro
business
enterprise

Gets the current status of an asynchronous operation on a list.

The status property can have one of the following values: pending, running, completed, or failed. If the status is failed, the error property will contain a message describing the error.

GET accounts/:account_identifier/rules/lists/bulk_operations/:operation_id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rules/lists/bulk_operations/4da8780eeb215e6cb7f48dd981c4ea02" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "4da8780eeb215e6cb7f48dd981c4ea02",
    "status": "failed",
    "error": "This list is at the maximum number of items",
    "completed": "2020-01-01T08:00:00Z"
  }
}

Lists error codes

Code	Description
10000	Invalid user

Account Rulesets

Rulesets at the account level

account-rulesets

Object definition

View properties and constraints defined on the object

Show definition

account-rulesets-list-account-rulesets

GET List account rulesets
free
pro
business
enterprise

List all rulesets for an account

GET accounts/:account_id/rulesets

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rulesets" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "2f2feab2026849078ba485f918791bdc",
      "name": "My ruleset",
      "description": "My ruleset to execute managed rulesets",
      "kind": "root",
      "phase": "http_request_firewall_managed",
      "version": "1",
      "last_updated": "2000-01-01T00:00:00.000000Z"
    }
  ]
}

account-rulesets-create-account-ruleset

POST Create account ruleset
free
pro
business
enterprise

Create an account ruleset

POST accounts/:account_id/rulesets

Required parameters

Name /type	Description /example	Constraints
name string	The human readable name for the ruleset `"My ruleset"`
kind string	The kind of the ruleset `"root"`	valid values: custom, root, zone
phase string	The phase of the ruleset `"http_request_firewall_managed"`	pattern: ^[a-z_]+$
rules array	The rules in the ruleset `[ { "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1", "expression": "ip.src ne 1.1.1.1", "action": "execute", "action_parameters": { "id": "4814384a9e5d4991b9815dcfc25d2f1f" }, "ref": "my_ref", "enabled": "true", "logging": { "enabled": "true" } } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
description string	A description of the ruleset `"My ruleset to execute managed rulesets"`	default value:

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rulesets" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"My ruleset","description":"My ruleset to execute managed rulesets","kind":"root","phase":"http_request_firewall_managed","rules":[{"description":"Execute the OWASP ruleset when the IP address is not 1.1.1.1","expression":"ip.src ne 1.1.1.1","action":"execute","action_parameters":{"id":"4814384a9e5d4991b9815dcfc25d2f1f"},"ref":"my_ref","enabled":"true","logging":{"enabled":"true"}}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2f2feab2026849078ba485f918791bdc",
    "name": "My ruleset",
    "description": "My ruleset to execute managed rulesets",
    "kind": "root",
    "phase": "http_request_firewall_managed",
    "version": "1",
    "rules": [
      {
        "id": "3a03d665bac047339bb530ecb439a90d",
        "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1",
        "version": "1",
        "expression": "ip.src ne 1.1.1.1",
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "ref": "my_ref",
        "enabled": "true",
        "logging": {
          "enabled": "true"
        },
        "last_updated": "2000-01-01T00:00:00.000000Z"
      }
    ],
    "last_updated": "2000-01-01T00:00:00.000000Z"
  }
}

account-rulesets-get-account-ruleset

GET Get account ruleset
free
pro
business
enterprise

Get the latest version of an account ruleset

GET accounts/:account_id/rulesets/:ruleset_id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rulesets/2f2feab2026849078ba485f918791bdc" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2f2feab2026849078ba485f918791bdc",
    "name": "My ruleset",
    "description": "My ruleset to execute managed rulesets",
    "kind": "root",
    "phase": "http_request_firewall_managed",
    "version": "1",
    "rules": [
      {
        "id": "3a03d665bac047339bb530ecb439a90d",
        "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1",
        "version": "1",
        "expression": "ip.src ne 1.1.1.1",
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "ref": "my_ref",
        "enabled": "true",
        "logging": {
          "enabled": "true"
        },
        "last_updated": "2000-01-01T00:00:00.000000Z"
      }
    ],
    "last_updated": "2000-01-01T00:00:00.000000Z"
  }
}

account-rulesets-update-account-ruleset

PUT Update account ruleset
free
pro
business
enterprise

Update an account ruleset, creating a new version

PUT accounts/:account_id/rulesets/:ruleset_id

Required parameters

Name /type	Description /example	Constraints
rules array	The rules in the ruleset `[ { "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1", "expression": "ip.src ne 1.1.1.1", "action": "execute", "action_parameters": { "id": "4814384a9e5d4991b9815dcfc25d2f1f" }, "ref": "my_ref", "enabled": "true", "logging": { "enabled": "true" } } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
description string	A description of the ruleset `"My ruleset to execute managed rulesets"`	default value:

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rulesets/2f2feab2026849078ba485f918791bdc" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"My ruleset to execute managed rulesets","rules":[{"description":"Execute the OWASP ruleset when the IP address is not 1.1.1.1","expression":"ip.src ne 1.1.1.1","action":"execute","action_parameters":{"id":"4814384a9e5d4991b9815dcfc25d2f1f"},"ref":"my_ref","enabled":"true","logging":{"enabled":"true"}}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2f2feab2026849078ba485f918791bdc",
    "name": "My ruleset",
    "description": "My ruleset to execute managed rulesets",
    "kind": "root",
    "phase": "http_request_firewall_managed",
    "version": "1",
    "rules": [
      {
        "id": "3a03d665bac047339bb530ecb439a90d",
        "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1",
        "version": "1",
        "expression": "ip.src ne 1.1.1.1",
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "ref": "my_ref",
        "enabled": "true",
        "logging": {
          "enabled": "true"
        },
        "last_updated": "2000-01-01T00:00:00.000000Z"
      }
    ],
    "last_updated": "2000-01-01T00:00:00.000000Z"
  }
}

account-rulesets-delete-account-ruleset

DELETE Delete account ruleset
free
pro
business
enterprise

Delete all versions of an account ruleset

DELETE accounts/:account_id/rulesets/:ruleset_id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rulesets/2f2feab2026849078ba485f918791bdc" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

account-rulesets-list-account-ruleset-versions

GET List account ruleset versions
free
pro
business
enterprise

List the versions of an account ruleset

GET accounts/:account_id/rulesets/:ruleset_id/versions

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rulesets/2f2feab2026849078ba485f918791bdc/versions" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "2f2feab2026849078ba485f918791bdc",
      "name": "My ruleset",
      "description": "My ruleset to execute managed rulesets",
      "kind": "root",
      "phase": "http_request_firewall_managed",
      "version": "1",
      "last_updated": "2000-01-01T00:00:00.000000Z"
    }
  ]
}

account-rulesets-get-account-ruleset-version

GET Get account ruleset version
free
pro
business
enterprise

Get a version of an account ruleset

GET accounts/:account_id/rulesets/:ruleset_id/versions/:ruleset_version

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rulesets/2f2feab2026849078ba485f918791bdc/versions/1" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2f2feab2026849078ba485f918791bdc",
    "name": "My ruleset",
    "description": "My ruleset to execute managed rulesets",
    "kind": "root",
    "phase": "http_request_firewall_managed",
    "version": "1",
    "rules": [
      {
        "id": "3a03d665bac047339bb530ecb439a90d",
        "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1",
        "version": "1",
        "expression": "ip.src ne 1.1.1.1",
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "ref": "my_ref",
        "enabled": "true",
        "logging": {
          "enabled": "true"
        },
        "last_updated": "2000-01-01T00:00:00.000000Z"
      }
    ],
    "last_updated": "2000-01-01T00:00:00.000000Z"
  }
}

account-rulesets-delete-account-ruleset-version

DELETE Delete account ruleset version
free
pro
business
enterprise

Delete a version of an account ruleset

DELETE accounts/:account_id/rulesets/:ruleset_id/versions/:ruleset_version

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rulesets/2f2feab2026849078ba485f918791bdc/versions/1" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

account-rulesets-create-account-ruleset-rule

POST Create account ruleset rule
free
pro
business
enterprise

Add a new rule to an account ruleset

POST accounts/:account_id/rulesets/:ruleset_id/rules

Required parameters

Name /type	Description /example	Constraints
expression string	The expression of the rule to match traffic on `"ip.src ne 1.1.1.1"`
action string	The action to take when the rule matches `"execute"`	pattern: ^[a-z_]+$

Optional parameters

Name /type	Description /example	Constraints
description string	A description of the rule `"Execute the OWASP ruleset when the IP address is not 1.1.1.1"`	default value:
action_parameters object	The parameters to configure the given action `{ "id": "4814384a9e5d4991b9815dcfc25d2f1f" }`
ref string	A reference for the rule, defaults to the ID `"my_ref"`
enabled boolean	Whether the rule should be run `"true"`	default value: true valid values: (true,false)
logging object	The parameters to configure how the rule generates logs `{ "enabled": "true" }` An object with the following properties: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rulesets/2f2feab2026849078ba485f918791bdc/rules" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Execute the OWASP ruleset when the IP address is not 1.1.1.1","expression":"ip.src ne 1.1.1.1","action":"execute","action_parameters":{"id":"4814384a9e5d4991b9815dcfc25d2f1f"},"ref":"my_ref","enabled":"true","logging":{"enabled":"true"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2f2feab2026849078ba485f918791bdc",
    "name": "My ruleset",
    "description": "My ruleset to execute managed rulesets",
    "kind": "root",
    "phase": "http_request_firewall_managed",
    "version": "1",
    "rules": [
      {
        "id": "3a03d665bac047339bb530ecb439a90d",
        "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1",
        "version": "1",
        "expression": "ip.src ne 1.1.1.1",
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "ref": "my_ref",
        "enabled": "true",
        "logging": {
          "enabled": "true"
        },
        "last_updated": "2000-01-01T00:00:00.000000Z"
      }
    ],
    "last_updated": "2000-01-01T00:00:00.000000Z"
  }
}

account-rulesets-update-account-ruleset-rule

PATCH Update account ruleset rule
free
pro
business
enterprise

Update a rule in an account ruleset

PATCH accounts/:account_id/rulesets/:ruleset_id/rules/:rule_id

Required parameters

Name /type	Description /example	Constraints
expression string	The expression of the rule to match traffic on `"ip.src ne 1.1.1.1"`
action string	The action to take when the rule matches `"execute"`	pattern: ^[a-z_]+$

Optional parameters

Name /type	Description /example	Constraints
description string	A description of the rule `"Execute the OWASP ruleset when the IP address is not 1.1.1.1"`	default value:
action_parameters object	The parameters to configure the given action `{ "id": "4814384a9e5d4991b9815dcfc25d2f1f" }`
ref string	A reference for the rule, defaults to the ID `"my_ref"`
enabled boolean	Whether the rule should be run `"true"`	default value: true valid values: (true,false)
logging object	The parameters to configure how the rule generates logs `{ "enabled": "true" }` An object with the following properties: Show definition »

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rulesets/2f2feab2026849078ba485f918791bdc/rules/3a03d665bac047339bb530ecb439a90d" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Execute the OWASP ruleset when the IP address is not 1.1.1.1","expression":"ip.src ne 1.1.1.1","action":"execute","action_parameters":{"id":"4814384a9e5d4991b9815dcfc25d2f1f"},"ref":"my_ref","enabled":"true","logging":{"enabled":"true"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2f2feab2026849078ba485f918791bdc",
    "name": "My ruleset",
    "description": "My ruleset to execute managed rulesets",
    "kind": "root",
    "phase": "http_request_firewall_managed",
    "version": "1",
    "rules": [
      {
        "id": "3a03d665bac047339bb530ecb439a90d",
        "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1",
        "version": "1",
        "expression": "ip.src ne 1.1.1.1",
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "ref": "my_ref",
        "enabled": "true",
        "logging": {
          "enabled": "true"
        },
        "last_updated": "2000-01-01T00:00:00.000000Z"
      }
    ],
    "last_updated": "2000-01-01T00:00:00.000000Z"
  }
}

account-rulesets-delete-account-ruleset-rule

DELETE Delete account ruleset rule
free
pro
business
enterprise

Delete a rule from an account ruleset

DELETE accounts/:account_id/rulesets/:ruleset_id/rules/:rule_id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rulesets/2f2feab2026849078ba485f918791bdc/rules/3a03d665bac047339bb530ecb439a90d" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2f2feab2026849078ba485f918791bdc",
    "name": "My ruleset",
    "description": "My ruleset to execute managed rulesets",
    "kind": "root",
    "phase": "http_request_firewall_managed",
    "version": "1",
    "rules": [
      {
        "id": "3a03d665bac047339bb530ecb439a90d",
        "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1",
        "version": "1",
        "expression": "ip.src ne 1.1.1.1",
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "ref": "my_ref",
        "enabled": "true",
        "logging": {
          "enabled": "true"
        },
        "last_updated": "2000-01-01T00:00:00.000000Z"
      }
    ],
    "last_updated": "2000-01-01T00:00:00.000000Z"
  }
}

account-rulesets-get-account-entrypoint-ruleset

GET Get account entrypoint ruleset
free
pro
business
enterprise

Get the latest version of an account entrypoint ruleset

GET accounts/:account_id/rulesets/phases/:ruleset_phase/entrypoint

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rulesets/phases/http_request_firewall_managed/entrypoint" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2f2feab2026849078ba485f918791bdc",
    "name": "My ruleset",
    "description": "My ruleset to execute managed rulesets",
    "kind": "root",
    "phase": "http_request_firewall_managed",
    "version": "1",
    "rules": [
      {
        "id": "3a03d665bac047339bb530ecb439a90d",
        "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1",
        "version": "1",
        "expression": "ip.src ne 1.1.1.1",
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "ref": "my_ref",
        "enabled": "true",
        "logging": {
          "enabled": "true"
        },
        "last_updated": "2000-01-01T00:00:00.000000Z"
      }
    ],
    "last_updated": "2000-01-01T00:00:00.000000Z"
  }
}

account-rulesets-update-account-entrypoint-ruleset

PUT Update account entrypoint ruleset
free
pro
business
enterprise

Update an account entrypoint ruleset, creating a new version

PUT accounts/:account_id/rulesets/phases/:ruleset_phase/entrypoint

Required parameters

Name /type	Description /example	Constraints
rules array	The rules in the ruleset `[ { "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1", "expression": "ip.src ne 1.1.1.1", "action": "execute", "action_parameters": { "id": "4814384a9e5d4991b9815dcfc25d2f1f" }, "ref": "my_ref", "enabled": "true", "logging": { "enabled": "true" } } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
description string	A description of the ruleset `"My ruleset to execute managed rulesets"`	default value:

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/rulesets/phases/http_request_firewall_managed/entrypoint" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"My ruleset to execute managed rulesets","rules":[{"description":"Execute the OWASP ruleset when the IP address is not 1.1.1.1","expression":"ip.src ne 1.1.1.1","action":"execute","action_parameters":{"id":"4814384a9e5d4991b9815dcfc25d2f1f"},"ref":"my_ref","enabled":"true","logging":{"enabled":"true"}}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2f2feab2026849078ba485f918791bdc",
    "name": "My ruleset",
    "description": "My ruleset to execute managed rulesets",
    "kind": "root",
    "phase": "http_request_firewall_managed",
    "version": "1",
    "rules": [
      {
        "id": "3a03d665bac047339bb530ecb439a90d",
        "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1",
        "version": "1",
        "expression": "ip.src ne 1.1.1.1",
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "ref": "my_ref",
        "enabled": "true",
        "logging": {
          "enabled": "true"
        },
        "last_updated": "2000-01-01T00:00:00.000000Z"
      }
    ],
    "last_updated": "2000-01-01T00:00:00.000000Z"
  }
}

Zone Rulesets

Rulesets at the zone level

zone-rulesets

Object definition

View properties and constraints defined on the object

Show definition

zone-rulesets-list-zone-rulesets

GET List zone rulesets
free
pro
business
enterprise

List all rulesets for a zone

GET zones/:zone_id/rulesets

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rulesets" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "2f2feab2026849078ba485f918791bdc",
      "name": "My ruleset",
      "description": "My ruleset to execute managed rulesets",
      "kind": "root",
      "phase": "http_request_firewall_managed",
      "version": "1",
      "last_updated": "2000-01-01T00:00:00.000000Z"
    }
  ]
}

zone-rulesets-create-zone-ruleset

POST Create zone ruleset
free
pro
business
enterprise

Create a zone ruleset

POST zones/:zone_id/rulesets

Required parameters

Name /type	Description /example	Constraints
name string	The human readable name for the ruleset `"My ruleset"`
kind string	The kind of the ruleset `"root"`	valid values: custom, root, zone
phase string	The phase of the ruleset `"http_request_firewall_managed"`	pattern: ^[a-z_]+$
rules array	The rules in the ruleset `[ { "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1", "expression": "ip.src ne 1.1.1.1", "action": "execute", "action_parameters": { "id": "4814384a9e5d4991b9815dcfc25d2f1f" }, "ref": "my_ref", "enabled": "true", "logging": { "enabled": "true" } } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
description string	A description of the ruleset `"My ruleset to execute managed rulesets"`	default value:

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rulesets" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"My ruleset","description":"My ruleset to execute managed rulesets","kind":"root","phase":"http_request_firewall_managed","rules":[{"description":"Execute the OWASP ruleset when the IP address is not 1.1.1.1","expression":"ip.src ne 1.1.1.1","action":"execute","action_parameters":{"id":"4814384a9e5d4991b9815dcfc25d2f1f"},"ref":"my_ref","enabled":"true","logging":{"enabled":"true"}}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2f2feab2026849078ba485f918791bdc",
    "name": "My ruleset",
    "description": "My ruleset to execute managed rulesets",
    "kind": "root",
    "phase": "http_request_firewall_managed",
    "version": "1",
    "rules": [
      {
        "id": "3a03d665bac047339bb530ecb439a90d",
        "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1",
        "version": "1",
        "expression": "ip.src ne 1.1.1.1",
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "ref": "my_ref",
        "enabled": "true",
        "logging": {
          "enabled": "true"
        },
        "last_updated": "2000-01-01T00:00:00.000000Z"
      }
    ],
    "last_updated": "2000-01-01T00:00:00.000000Z"
  }
}

zone-rulesets-get-zone-ruleset

GET Get zone ruleset
free
pro
business
enterprise

Get the latest version of a zone ruleset

GET zones/:zone_id/rulesets/:ruleset_id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rulesets/2f2feab2026849078ba485f918791bdc" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2f2feab2026849078ba485f918791bdc",
    "name": "My ruleset",
    "description": "My ruleset to execute managed rulesets",
    "kind": "root",
    "phase": "http_request_firewall_managed",
    "version": "1",
    "rules": [
      {
        "id": "3a03d665bac047339bb530ecb439a90d",
        "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1",
        "version": "1",
        "expression": "ip.src ne 1.1.1.1",
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "ref": "my_ref",
        "enabled": "true",
        "logging": {
          "enabled": "true"
        },
        "last_updated": "2000-01-01T00:00:00.000000Z"
      }
    ],
    "last_updated": "2000-01-01T00:00:00.000000Z"
  }
}

zone-rulesets-update-zone-ruleset

PUT Update zone ruleset
free
pro
business
enterprise

Update a zone ruleset, creating a new version

PUT zones/:zone_id/rulesets/:ruleset_id

Required parameters

Name /type	Description /example	Constraints
rules array	The rules in the ruleset `[ { "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1", "expression": "ip.src ne 1.1.1.1", "action": "execute", "action_parameters": { "id": "4814384a9e5d4991b9815dcfc25d2f1f" }, "ref": "my_ref", "enabled": "true", "logging": { "enabled": "true" } } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
description string	A description of the ruleset `"My ruleset to execute managed rulesets"`	default value:

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rulesets/2f2feab2026849078ba485f918791bdc" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"My ruleset to execute managed rulesets","rules":[{"description":"Execute the OWASP ruleset when the IP address is not 1.1.1.1","expression":"ip.src ne 1.1.1.1","action":"execute","action_parameters":{"id":"4814384a9e5d4991b9815dcfc25d2f1f"},"ref":"my_ref","enabled":"true","logging":{"enabled":"true"}}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2f2feab2026849078ba485f918791bdc",
    "name": "My ruleset",
    "description": "My ruleset to execute managed rulesets",
    "kind": "root",
    "phase": "http_request_firewall_managed",
    "version": "1",
    "rules": [
      {
        "id": "3a03d665bac047339bb530ecb439a90d",
        "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1",
        "version": "1",
        "expression": "ip.src ne 1.1.1.1",
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "ref": "my_ref",
        "enabled": "true",
        "logging": {
          "enabled": "true"
        },
        "last_updated": "2000-01-01T00:00:00.000000Z"
      }
    ],
    "last_updated": "2000-01-01T00:00:00.000000Z"
  }
}

zone-rulesets-delete-zone-ruleset

DELETE Delete zone ruleset
free
pro
business
enterprise

Delete all versions of a zone ruleset

DELETE zones/:zone_id/rulesets/:ruleset_id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rulesets/2f2feab2026849078ba485f918791bdc" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

zone-rulesets-list-zone-ruleset-versions

GET List zone ruleset versions
free
pro
business
enterprise

List the versions of a zone ruleset

GET zones/:zone_id/rulesets/:ruleset_id/versions

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rulesets/2f2feab2026849078ba485f918791bdc/versions" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "2f2feab2026849078ba485f918791bdc",
      "name": "My ruleset",
      "description": "My ruleset to execute managed rulesets",
      "kind": "root",
      "phase": "http_request_firewall_managed",
      "version": "1",
      "last_updated": "2000-01-01T00:00:00.000000Z"
    }
  ]
}

zone-rulesets-get-zone-ruleset-version

GET Get zone ruleset version
free
pro
business
enterprise

Get a version of a zone ruleset

GET zones/:zone_id/rulesets/:ruleset_id/versions/:ruleset_version

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rulesets/2f2feab2026849078ba485f918791bdc/versions/1" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2f2feab2026849078ba485f918791bdc",
    "name": "My ruleset",
    "description": "My ruleset to execute managed rulesets",
    "kind": "root",
    "phase": "http_request_firewall_managed",
    "version": "1",
    "rules": [
      {
        "id": "3a03d665bac047339bb530ecb439a90d",
        "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1",
        "version": "1",
        "expression": "ip.src ne 1.1.1.1",
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "ref": "my_ref",
        "enabled": "true",
        "logging": {
          "enabled": "true"
        },
        "last_updated": "2000-01-01T00:00:00.000000Z"
      }
    ],
    "last_updated": "2000-01-01T00:00:00.000000Z"
  }
}

zone-rulesets-delete-zone-ruleset-version

DELETE Delete zone ruleset version
free
pro
business
enterprise

Delete a version of a zone ruleset

DELETE zones/:zone_id/rulesets/:ruleset_id/versions/:ruleset_version

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rulesets/2f2feab2026849078ba485f918791bdc/versions/1" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

zone-rulesets-create-zone-ruleset-rule

POST Create zone ruleset rule
free
pro
business
enterprise

Add a new rule to a zone ruleset

POST zones/:zone_id/rulesets/:ruleset_id/rules

Required parameters

Name /type	Description /example	Constraints
expression string	The expression of the rule to match traffic on `"ip.src ne 1.1.1.1"`
action string	The action to take when the rule matches `"execute"`	pattern: ^[a-z_]+$

Optional parameters

Name /type	Description /example	Constraints
description string	A description of the rule `"Execute the OWASP ruleset when the IP address is not 1.1.1.1"`	default value:
action_parameters object	The parameters to configure the given action `{ "id": "4814384a9e5d4991b9815dcfc25d2f1f" }`
ref string	A reference for the rule, defaults to the ID `"my_ref"`
enabled boolean	Whether the rule should be run `"true"`	default value: true valid values: (true,false)
logging object	The parameters to configure how the rule generates logs `{ "enabled": "true" }` An object with the following properties: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rulesets/2f2feab2026849078ba485f918791bdc/rules" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Execute the OWASP ruleset when the IP address is not 1.1.1.1","expression":"ip.src ne 1.1.1.1","action":"execute","action_parameters":{"id":"4814384a9e5d4991b9815dcfc25d2f1f"},"ref":"my_ref","enabled":"true","logging":{"enabled":"true"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2f2feab2026849078ba485f918791bdc",
    "name": "My ruleset",
    "description": "My ruleset to execute managed rulesets",
    "kind": "root",
    "phase": "http_request_firewall_managed",
    "version": "1",
    "rules": [
      {
        "id": "3a03d665bac047339bb530ecb439a90d",
        "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1",
        "version": "1",
        "expression": "ip.src ne 1.1.1.1",
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "ref": "my_ref",
        "enabled": "true",
        "logging": {
          "enabled": "true"
        },
        "last_updated": "2000-01-01T00:00:00.000000Z"
      }
    ],
    "last_updated": "2000-01-01T00:00:00.000000Z"
  }
}

zone-rulesets-update-zone-ruleset-rule

PATCH Update zone ruleset rule
free
pro
business
enterprise

Update a rule in a zone ruleset

PATCH zones/:zone_id/rulesets/:ruleset_id/rules/:rule_id

Required parameters

Name /type	Description /example	Constraints
expression string	The expression of the rule to match traffic on `"ip.src ne 1.1.1.1"`
action string	The action to take when the rule matches `"execute"`	pattern: ^[a-z_]+$

Optional parameters

Name /type	Description /example	Constraints
description string	A description of the rule `"Execute the OWASP ruleset when the IP address is not 1.1.1.1"`	default value:
action_parameters object	The parameters to configure the given action `{ "id": "4814384a9e5d4991b9815dcfc25d2f1f" }`
ref string	A reference for the rule, defaults to the ID `"my_ref"`
enabled boolean	Whether the rule should be run `"true"`	default value: true valid values: (true,false)
logging object	The parameters to configure how the rule generates logs `{ "enabled": "true" }` An object with the following properties: Show definition »

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rulesets/2f2feab2026849078ba485f918791bdc/rules/3a03d665bac047339bb530ecb439a90d" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Execute the OWASP ruleset when the IP address is not 1.1.1.1","expression":"ip.src ne 1.1.1.1","action":"execute","action_parameters":{"id":"4814384a9e5d4991b9815dcfc25d2f1f"},"ref":"my_ref","enabled":"true","logging":{"enabled":"true"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2f2feab2026849078ba485f918791bdc",
    "name": "My ruleset",
    "description": "My ruleset to execute managed rulesets",
    "kind": "root",
    "phase": "http_request_firewall_managed",
    "version": "1",
    "rules": [
      {
        "id": "3a03d665bac047339bb530ecb439a90d",
        "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1",
        "version": "1",
        "expression": "ip.src ne 1.1.1.1",
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "ref": "my_ref",
        "enabled": "true",
        "logging": {
          "enabled": "true"
        },
        "last_updated": "2000-01-01T00:00:00.000000Z"
      }
    ],
    "last_updated": "2000-01-01T00:00:00.000000Z"
  }
}

zone-rulesets-delete-zone-ruleset-rule

DELETE Delete zone ruleset rule
free
pro
business
enterprise

Delete a rule from a zone ruleset

DELETE zones/:zone_id/rulesets/:ruleset_id/rules/:rule_id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rulesets/2f2feab2026849078ba485f918791bdc/rules/3a03d665bac047339bb530ecb439a90d" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2f2feab2026849078ba485f918791bdc",
    "name": "My ruleset",
    "description": "My ruleset to execute managed rulesets",
    "kind": "root",
    "phase": "http_request_firewall_managed",
    "version": "1",
    "rules": [
      {
        "id": "3a03d665bac047339bb530ecb439a90d",
        "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1",
        "version": "1",
        "expression": "ip.src ne 1.1.1.1",
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "ref": "my_ref",
        "enabled": "true",
        "logging": {
          "enabled": "true"
        },
        "last_updated": "2000-01-01T00:00:00.000000Z"
      }
    ],
    "last_updated": "2000-01-01T00:00:00.000000Z"
  }
}

zone-rulesets-get-zone-entrypoint-ruleset

GET Get zone entrypoint ruleset
free
pro
business
enterprise

Get the latest version of a zone entrypoint ruleset

GET zones/:zone_id/rulesets/phases/:ruleset_phase/entrypoint

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rulesets/phases/http_request_firewall_managed/entrypoint" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2f2feab2026849078ba485f918791bdc",
    "name": "My ruleset",
    "description": "My ruleset to execute managed rulesets",
    "kind": "root",
    "phase": "http_request_firewall_managed",
    "version": "1",
    "rules": [
      {
        "id": "3a03d665bac047339bb530ecb439a90d",
        "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1",
        "version": "1",
        "expression": "ip.src ne 1.1.1.1",
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "ref": "my_ref",
        "enabled": "true",
        "logging": {
          "enabled": "true"
        },
        "last_updated": "2000-01-01T00:00:00.000000Z"
      }
    ],
    "last_updated": "2000-01-01T00:00:00.000000Z"
  }
}

zone-rulesets-update-zone-entrypoint-ruleset

PUT Update zone entrypoint ruleset
free
pro
business
enterprise

Update a zone entrypoint ruleset, creating a new version

PUT zones/:zone_id/rulesets/phases/:ruleset_phase/entrypoint

Required parameters

Name /type	Description /example	Constraints
rules array	The rules in the ruleset `[ { "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1", "expression": "ip.src ne 1.1.1.1", "action": "execute", "action_parameters": { "id": "4814384a9e5d4991b9815dcfc25d2f1f" }, "ref": "my_ref", "enabled": "true", "logging": { "enabled": "true" } } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
description string	A description of the ruleset `"My ruleset to execute managed rulesets"`	default value:

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rulesets/phases/http_request_firewall_managed/entrypoint" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"My ruleset to execute managed rulesets","rules":[{"description":"Execute the OWASP ruleset when the IP address is not 1.1.1.1","expression":"ip.src ne 1.1.1.1","action":"execute","action_parameters":{"id":"4814384a9e5d4991b9815dcfc25d2f1f"},"ref":"my_ref","enabled":"true","logging":{"enabled":"true"}}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "2f2feab2026849078ba485f918791bdc",
    "name": "My ruleset",
    "description": "My ruleset to execute managed rulesets",
    "kind": "root",
    "phase": "http_request_firewall_managed",
    "version": "1",
    "rules": [
      {
        "id": "3a03d665bac047339bb530ecb439a90d",
        "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1",
        "version": "1",
        "expression": "ip.src ne 1.1.1.1",
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "ref": "my_ref",
        "enabled": "true",
        "logging": {
          "enabled": "true"
        },
        "last_updated": "2000-01-01T00:00:00.000000Z"
      }
    ],
    "last_updated": "2000-01-01T00:00:00.000000Z"
  }
}

Transform Rules

transform-rules

Object definition

View properties and constraints defined on the object

Show definition

transform-rules-get-transform-rules

GET Get Transform Rules
free
pro
business
enterprise

Fetches all Transform Rules in a zone.

GET zones/:zone_id/rulesets/phases/:phase/entrypoint

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rulesets/phases/undefined/entrypoint" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "id": "2f2feab2026849078ba485f918791bdc",
  "name": "default",
  "description": "",
  "kind": "zone",
  "phase": "http_request_transform",
  "rules": [
    {
      "id": "3a03d665bac047339bb530ecb439a90d",
      "version": "1",
      "action": "rewrite",
      "expression": "ip.geoip.country eq \"AL\"",
      "description": "change request based on ip location",
      "action_parameters": {
        "uri": {
          "path": {
            "expression": "concat(\"/new/\", http.request.uri)"
          },
          "query": {
            "expression": "concat(\"/new/\", http.request.uri)"
          }
        }
      }
    }
  ]
}

transform-rules-update-transform-rules

PUT Update Transform Rules
free
pro
business
enterprise

Updates the Transform Rules of a zone.

PUT zones/:zone_id/rulesets/phases/:phase/entrypoint

Required parameters

Name /type	Description /example	Constraints
rules array	The rules in the ruleset `[ { "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1", "expression": "ip.src ne 1.1.1.1", "action": "execute", "action_parameters": { "id": "4814384a9e5d4991b9815dcfc25d2f1f" }, "ref": "my_ref", "enabled": "true", "logging": { "enabled": "true" } } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
description string	A description of the ruleset `"My ruleset to execute managed rulesets"`	default value:

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rulesets/phases/undefined/entrypoint" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"My ruleset to execute managed rulesets","rules":[{"description":"Execute the OWASP ruleset when the IP address is not 1.1.1.1","expression":"ip.src ne 1.1.1.1","action":"execute","action_parameters":{"id":"4814384a9e5d4991b9815dcfc25d2f1f"},"ref":"my_ref","enabled":"true","logging":{"enabled":"true"}}]}'

Response (example)

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

Managed Transforms

Managed Transforms perform common adjustments to HTTP request and response headers.

managed-transforms

Object definition

View properties and constraints defined on the object

Show definition

managed-transforms-list-managed-transforms

GET List Managed Transforms
free
pro
business
enterprise

Fetches a list of all Managed Transforms.

GET zones/:zone_id/managed_headers

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/managed_headers" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "managed_request_headers": [
    {
      "id": "add_cf-bot-score_header",
      "enabled": true
    }
  ],
  "managed_response_headers": [
    {
      "id": "add_cf-bot-score_header",
      "enabled": true
    }
  ]
}

managed-transforms-update-status-of-managed-transforms

PATCH Update status of Managed Transforms
free
pro
business
enterprise

Updates the status of one or more Managed Transforms.

PATCH zones/:zone_id/managed_headers

Required parameters

Name /type	Description /example	Constraints
managed_request_headers array	`[ { "id": "add_cf-bot-score_header", "enabled": true } ]` An array with items in the following form: Show definition »
managed_response_headers array	`[ { "id": "add_cf-bot-score_header", "enabled": true } ]` An array with items in the following form: Show definition »

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/managed_headers" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"managed_request_headers":[{"id":"add_cf-bot-score_header","enabled":true}],"managed_response_headers":[{"id":"add_cf-bot-score_header","enabled":true}]}'

Response (example)

{
  "managed_request_headers": [
    {
      "id": "add_cf-bot-score_header",
      "enabled": true,
      "available": true
    }
  ],
  "managed_response_headers": [
    {
      "id": "add_cf-bot-score_header",
      "enabled": true,
      "available": true
    }
  ]
}

URL Normalization

The URL normalization settings of a zone.

url-normalization

Object definition

View properties and constraints defined on the object

Show definition

url-normalization-get-url-normalization-settings

GET Get URL normalization settings
free
pro
business
enterprise

Fetches the current URL normalization settings.

GET zones/:zone_id/url_normalization

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/url_normalization" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "type": "cloudflare",
  "scope": "incoming"
}

url-normalization-update-url-normalization-settings

PUT Update URL normalization settings
free
pro
business
enterprise

Updates the URL normalization settings.

PUT zones/:zone_id/url_normalization

Optional parameters

Name /type	Description /example	Constraints
type string	The type of URL normalization performed by Cloudflare. `"cloudflare"`
scope string	The scope of the URL normalization. `"incoming"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/url_normalization" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"cloudflare","scope":"incoming"}'

Response (example)

{
  "type": "cloudflare",
  "scope": "incoming"
}

Custom Error Responses

custom-error-responses

Object definition

View properties and constraints defined on the object

Show definition

custom-error-responses-get-custom-error-responses

GET Get Custom Error Responses
free
pro
business
enterprise

Fetches all Custom Error Responses in a zone.

GET zones/:zone_id/rulesets/phases/http_custom_errors/entrypoint

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rulesets/phases/http_custom_errors/entrypoint" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "id": "2f2feab2026849078ba485f918791bdc",
  "name": "default",
  "description": "",
  "kind": "zone",
  "phase": "http_custom_errors",
  "rules": [
    {
      "id": "3a03d665bac047339bb530ecb439a90d",
      "version": "1",
      "action": "serve_error",
      "expression": "ip.geoip.country eq \"AL\"",
      "description": "Change error response based on geolocation",
      "action_parameters": {
        "content": "some html error page",
        "content_type": "text/html",
        "status_code": 530
      }
    }
  ]
}

custom-error-responses-update-custom-error-responses

PUT Update Custom Error Responses
free
pro
business
enterprise

Updates the Custom Error Responses of a zone.

PUT zones/:zone_id/rulesets/phases/http_custom_errors/entrypoint

Required parameters

Name /type	Description /example	Constraints
rules array	The rules in the ruleset `[ { "description": "Execute the OWASP ruleset when the IP address is not 1.1.1.1", "expression": "ip.src ne 1.1.1.1", "action": "execute", "action_parameters": { "id": "4814384a9e5d4991b9815dcfc25d2f1f" }, "ref": "my_ref", "enabled": "true", "logging": { "enabled": "true" } } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
description string	A description of the ruleset `"My ruleset to execute managed rulesets"`	default value:

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/rulesets/phases/http_custom_errors/entrypoint" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"My ruleset to execute managed rulesets","rules":[{"description":"Execute the OWASP ruleset when the IP address is not 1.1.1.1","expression":"ip.src ne 1.1.1.1","action":"execute","action_parameters":{"id":"4814384a9e5d4991b9815dcfc25d2f1f"},"ref":"my_ref","enabled":"true","logging":{"enabled":"true"}}]}'

Response (example)

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

Page Shield

Page Shield monitors your zone for new JavaScript dependencies.

page-shield

Object definition

View properties and constraints defined on the object

Show definition

page-shield-get-page-shield-status

GET Get Page Shield status
free
pro
business
enterprise

Fetches the Page Shield status.

GET zones/:zone_id/page_shield

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/page_shield" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

page-shield-update-page-shield-status

PUT Update Page Shield status
free
pro
business
enterprise

Updates the status of Page Shield.

PUT zones/:zone_id/page_shield

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/page_shield" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

page-shield-list-page-shield-scripts

GET List Page Shield scripts
free
pro
business
enterprise

Lists all scripts detected by Page Shield.

GET zones/:zone_id/page_shield/scripts

Optional parameters

Name /type	Description /example	Constraints
script_page string	Filters the returned scripts by the page URL where they were last seen. `"example.com/page"`
order_by string	The field used to sort returned scripts. `"first_seen_at"`	valid values: first_seen_at, last_seen_at
hosts string	Filters the returned scripts by one or more URL-encoded hostname substrings separated by commas. `"blog.cloudflare.com,www.example"`
exclude_cdn_cgi boolean	When true, excludes scripts seen in a `/cdn-cgi` path from the returned scripts. The default value is true. `true`	valid values: (true,false)
page number	The current page number of the paginated results. `2`	min value:1
per_page number	The number of results per page. `100`	min value:1 max value:100
status string	Filters the returned scripts using a comma-separated list of script statuses. Accepted values: `active`, `infrequent`, and `inactive`. The default value is `active`. `"active,inactive"`
exclude_script_urls string	Excludes scripts whose URL contains one the URL-encoded URL substrings (separated by commas) from the returned scripts. `"blog.cloudflare.com,www.example"`
prioritize_malicious boolean	When true, malicious scripts appear first in the returned scripts. `true`	valid values: (true,false)
script_urls string	Filters the returned scripts by one or more URL-encoded URL substrings separated by commas. `"blog.cloudflare.com,www.example"`
direction string	The direction used to sort returned scripts. `"asc"`	valid values: asc, desc

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/page_shield/scripts?exclude_script_urls=blog.cloudflare.com,www.example&script_urls=blog.cloudflare.com,www.example&hosts=blog.cloudflare.com,www.example&page=2&per_page=100&order_by=first_seen_at&direction=asc&prioritize_malicious=true&exclude_cdn_cgi=true&status=active,inactive&script_page=example.com/page" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "script_id": "c9ef84a6bf5e47138c75d95e2f933e8f",
      "script_url": "https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.6.0/js/bootstrap.min.js",
      "added_at": "2021-08-18T10:51:10.09615Z",
      "first_seen_at": "2021-08-18T10:51:08Z",
      "last_seen_at": "2021-09-02T09:57:54Z",
      "host": "blog.cloudflare.com",
      "domain_reported_malicious": false,
      "seen_on_first": "blog.cloudflare.com/page",
      "seen_on": [
        "blog.cloudflare.com/page1",
        "blog.cloudflare.com/page2"
      ],
      "appears_in_cdn_cgi_path": false,
      "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "js_integrity_score": 10,
      "fetched_at": "2021-09-02T10:17:54Z"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

page-shield-get-a-page-shield-script

GET Get a Page Shield script
free
pro
business
enterprise

Fetches a script detected by Page Shield by script ID.

GET zones/:zone_id/page_shield/scripts/:script_id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/023e105f4ecef8ad9ca31a8372d0c353/page_shield/scripts/c9ef84a6bf5e47138c75d95e2f933e8f" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "script_id": "c9ef84a6bf5e47138c75d95e2f933e8f",
  "script_url": "https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.6.0/js/bootstrap.min.js",
  "added_at": "2021-08-18T10:51:10.09615Z",
  "first_seen_at": "2021-08-18T10:51:08Z",
  "last_seen_at": "2021-09-02T09:57:54Z",
  "host": "blog.cloudflare.com",
  "domain_reported_malicious": false,
  "seen_on_first": "blog.cloudflare.com/page",
  "seen_on": [
    "blog.cloudflare.com/page1",
    "blog.cloudflare.com/page2"
  ],
  "appears_in_cdn_cgi_path": false,
  "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "js_integrity_score": 10,
  "fetched_at": "2021-09-02T10:17:54Z",
  "versions": [
    {
      "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b423",
      "js_integrity_score": 2,
      "fetched_at": "2021-08-18T10:51:08Z"
    }
  ]
}

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: user@example.com" \
     -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-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, UDP, and SMTP 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 you want to conduct a 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', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. `"https"`	default value: http valid values: http, https, tcp, udp_icmp, icmp_ping, smtp
probe_zone string	Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors. `"example.com"`
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: user@example.com" \
     -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
  }
}

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: user@example.com" \
     -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, UDP, and SMTP 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 you want to conduct a 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', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. `"https"`	default value: http valid values: http, https, tcp, udp_icmp, icmp_ping, smtp
probe_zone string	Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors. `"example.com"`
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: user@example.com" \
     -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
  }
}

load-balancer-monitors-patch-monitor

PATCH Patch Monitor

Apply changes to an existing monitor, overwriting the supplied properties.

PATCH user/load_balancers/monitors/:identifier

Optional parameters

Name /type	Description /example	Constraints
port integer	Port number to connect to for the health check. Required for TCP, UDP, and SMTP 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 you want to conduct a 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', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. `"https"`	default value: http valid values: http, https, tcp, udp_icmp, icmp_ping, smtp
probe_zone string	Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors. `"example.com"`
description string	Object description `"Login page monitor"`
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

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/user/load_balancers/monitors/f1aba936b94213e5b8dca0c0dbf1f9cc" \
     -H "X-Auth-Email: user@example.com" \
     -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
  }
}

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

load-balancer-monitors-preview-monitor

POST Preview Monitor

Preview pools using the specified monitor with provided monitor details. The returned preview_id can be used in the preview endpoint to retrieve the results.

POST user/load_balancers/monitors/:identifier/preview

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, UDP, and SMTP 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 you want to conduct a health check against. This parameter is only valid for HTTP and HTTPS monitors. `"/health"`	default value: /
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', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. `"https"`	default value: http valid values: http, https, tcp, udp_icmp, icmp_ping, smtp

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/user/load_balancers/monitors/f1aba936b94213e5b8dca0c0dbf1f9cc/preview" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"https","method":"GET","path":"/health","header":{"Host":["example.com"],"X-App-ID":["abc123"]},"port":8080,"timeout":3,"retries":0,"expected_body":"alive","expected_codes":"2xx","follow_redirects":true,"allow_insecure":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "preview_id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "pools": {
      "abwlnp5jbqn45ecgxd03erbgtxtqai0d": "WNAM Datacenter",
      "ve8h9lrcip5n5bbga9yqmdws28ay5d0l": "EEU Datacenter"
    }
  }
}

load-balancer-monitors-preview-result

GET Preview Result

Get the result of a previous preview operation using the provided preview_id

GET user/load_balancers/preview/:preview_id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/user/load_balancers/preview/f1aba936b94213e5b8dca0c0dbf1f9cc?" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "abwlnp5jbqn45ecgxd03erbgtxtqai0d": {
    "healthy": true,
    "origins": [
      {
        "originone.example.com.": {
          "healthy": true,
          "rtt": "66ms",
          "failure_reason": "No failures",
          "response_code": 200
        }
      }
    ]
  }
}

load-balancer-monitors-list-monitor-references

GET List Monitor References

Get the list of resources that reference the provided monitor

GET user/load_balancers/monitors/:identifier/references

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/user/load_balancers/monitors/f1aba936b94213e5b8dca0c0dbf1f9cc/references" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "resource_id": "17b5962d775c646f3f9725cbc7a53df4",
      "resource_name": "primary-dc-1",
      "resource_type": "pool",
      "reference_type": "referrer"
    }
  ]
}

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

Optional parameters

Name /type	Description /example	Constraints
monitor string	The ID of the Monitor to use for checking the health of origins within this pool. `"f1aba936b94213e5b8dca0c0dbf1f9cc"`	max length: 32 read only

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/user/load_balancers/pools?monitor=f1aba936b94213e5b8dca0c0dbf1f9cc" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "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": false,
      "load_shedding": {
        "default_percent": 0,
        "default_policy": "random",
        "session_percent": 0,
        "session_policy": "hash"
      },
      "minimum_origins": 2,
      "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
      "check_regions": [
        "WEU",
        "ENAM"
      ],
      "origins": [
        {
          "name": "app-server-1",
          "address": "0.0.0.0",
          "enabled": true,
          "weight": 0.56,
          "header": {
            "Host": [
              "example.com"
            ]
          }
        }
      ],
      "origin_steering": {
        "policy": "random"
      },
      "notification_email": "someone@example.com,sometwo@example.com",
      "notification_filter": {
        "origin": {
          "disable": false,
          "healthy": null
        },
        "pool": {
          "disable": false,
          "healthy": null
        }
      }
    }
  ]
}

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, "header": { "Host": [ "example.com" ] } } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
enabled boolean	Whether to enable (the default) or disable 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). `false`	default value: true valid values: (true,false)
notification_email string	The email address to send health status notifications to. This can be an individual mailbox or a mailing list. Multiple emails can be supplied as a comma delimited list. `"someone@example.com,sometwo@example.com"`
check_regions arraynull	A list of regions from which to run health checks. Null means every Cloudflare data center. `[ "WEU", "ENAM" ]` An array with items in the following form: Show definition »	default value: null
origin_steering object	Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. `{ "policy": "random" }` An object with the following properties: Show definition »
load_shedding object	Configures load shedding policies and percentages for the pool. `{ "default_percent": 0, "default_policy": "random", "session_percent": 0, "session_policy": "hash" }` An object with the following properties: Show definition »
latitude number	The latitude of the data center containing the origins used in this pool in decimal degrees. If this is set, longitude must also be set.
notification_filter objectnull	Filter pool and origin health notifications by resource type or health status. Use null to reset. `{ "origin": { "disable": false, "healthy": null }, "pool": { "disable": false, "healthy": null } }` An object with the following properties: Show definition »
longitude number	The longitude of the data center containing the origins used in this pool in decimal degrees. If this is set, latitude must also be set.
monitor string	The ID of the Monitor to use for checking the health of origins within this pool. `"f1aba936b94213e5b8dca0c0dbf1f9cc"`	max length: 32 read only
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 will failover to the next available pool. `2`	default value: 1
description string	A human-readable description of the pool. `"Primary data center - Provider XYZ"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/user/load_balancers/pools" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Primary data center - Provider XYZ","name":"primary-dc-1","enabled":false,"check_regions":["WEU","ENAM"],"load_shedding":{"default_percent":0,"default_policy":"random","session_percent":0,"session_policy":"hash"},"minimum_origins":2,"monitor":"f1aba936b94213e5b8dca0c0dbf1f9cc","origins":[{"name":"app-server-1","address":"0.0.0.0","enabled":true,"weight":0.56,"header":{"Host":["example.com"]}}],"origin_steering":{"policy":"random"},"notification_email":"someone@example.com,sometwo@example.com","notification_filter":{"origin":{"disable":false,"healthy":null},"pool":{"disable":false,"healthy":null}}}'

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": false,
    "load_shedding": {
      "default_percent": 0,
      "default_policy": "random",
      "session_percent": 0,
      "session_policy": "hash"
    },
    "minimum_origins": 2,
    "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "origins": [
      {
        "name": "app-server-1",
        "address": "0.0.0.0",
        "enabled": true,
        "weight": 0.56,
        "header": {
          "Host": [
            "example.com"
          ]
        }
      }
    ],
    "origin_steering": {
      "policy": "random"
    },
    "notification_email": "someone@example.com,sometwo@example.com",
    "notification_filter": {
      "origin": {
        "disable": false,
        "healthy": null
      },
      "pool": {
        "disable": false,
        "healthy": null
      }
    }
  }
}

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: user@example.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": false,
    "load_shedding": {
      "default_percent": 0,
      "default_policy": "random",
      "session_percent": 0,
      "session_policy": "hash"
    },
    "minimum_origins": 2,
    "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "origins": [
      {
        "name": "app-server-1",
        "address": "0.0.0.0",
        "enabled": true,
        "weight": 0.56,
        "header": {
          "Host": [
            "example.com"
          ]
        }
      }
    ],
    "origin_steering": {
      "policy": "random"
    },
    "notification_email": "someone@example.com,sometwo@example.com",
    "notification_filter": {
      "origin": {
        "disable": false,
        "healthy": null
      },
      "pool": {
        "disable": false,
        "healthy": null
      }
    }
  }
}

load-balancer-pools-pool-health-details

GET Pool Health Details

Fetch the latest pool health status 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: user@example.com" \
     -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, "header": { "Host": [ "example.com" ] } } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
enabled boolean	Whether to enable (the default) or disable 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). `false`	default value: true valid values: (true,false)
notification_email string	The email address to send health status notifications to. This can be an individual mailbox or a mailing list. Multiple emails can be supplied as a comma delimited list. `"someone@example.com,sometwo@example.com"`
check_regions arraynull	A list of regions from which to run health checks. Null means every Cloudflare data center. `[ "WEU", "ENAM" ]` An array with items in the following form: Show definition »	default value: null
origin_steering object	Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. `{ "policy": "random" }` An object with the following properties: Show definition »
load_shedding object	Configures load shedding policies and percentages for the pool. `{ "default_percent": 0, "default_policy": "random", "session_percent": 0, "session_policy": "hash" }` An object with the following properties: Show definition »
latitude number	The latitude of the data center containing the origins used in this pool in decimal degrees. If this is set, longitude must also be set.
notification_filter objectnull	Filter pool and origin health notifications by resource type or health status. Use null to reset. `{ "origin": { "disable": false, "healthy": null }, "pool": { "disable": false, "healthy": null } }` An object with the following properties: Show definition »
longitude number	The longitude of the data center containing the origins used in this pool in decimal degrees. If this is set, latitude must also be set.
disabled_at string (date-time)	This field shows up only if the pool is disabled. This field is set with the time the pool was disabled at.	read only
monitor string	The ID of the Monitor to use for checking the health of origins within this pool. `"f1aba936b94213e5b8dca0c0dbf1f9cc"`	max length: 32 read only
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 will failover to the next available pool. `2`	default value: 1
description string	A human-readable description of the pool. `"Primary data center - Provider XYZ"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/user/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Primary data center - Provider XYZ","name":"primary-dc-1","enabled":false,"check_regions":["WEU","ENAM"],"load_shedding":{"default_percent":0,"default_policy":"random","session_percent":0,"session_policy":"hash"},"minimum_origins":2,"monitor":"f1aba936b94213e5b8dca0c0dbf1f9cc","origins":[{"name":"app-server-1","address":"0.0.0.0","enabled":true,"weight":0.56,"header":{"Host":["example.com"]}}],"origin_steering":{"policy":"random"},"notification_email":"someone@example.com,sometwo@example.com","notification_filter":{"origin":{"disable":false,"healthy":null},"pool":{"disable":false,"healthy":null}}}'

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": false,
    "load_shedding": {
      "default_percent": 0,
      "default_policy": "random",
      "session_percent": 0,
      "session_policy": "hash"
    },
    "minimum_origins": 2,
    "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "origins": [
      {
        "name": "app-server-1",
        "address": "0.0.0.0",
        "enabled": true,
        "weight": 0.56,
        "header": {
          "Host": [
            "example.com"
          ]
        }
      }
    ],
    "origin_steering": {
      "policy": "random"
    },
    "notification_email": "someone@example.com,sometwo@example.com",
    "notification_filter": {
      "origin": {
        "disable": false,
        "healthy": null
      },
      "pool": {
        "disable": false,
        "healthy": null
      }
    }
  }
}

load-balancer-pools-patch-pool

PATCH Patch Pool

Apply changes to an existing pool, overwriting the supplied properties.

PATCH user/load_balancers/pools/:identifier

Optional parameters

Name /type	Description /example	Constraints
enabled boolean	Whether to enable (the default) or disable 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). `false`	default value: true valid values: (true,false)
notification_email string	The email address to send health status notifications to. This can be an individual mailbox or a mailing list. Multiple emails can be supplied as a comma delimited list. `"someone@example.com,sometwo@example.com"`
check_regions arraynull	A list of regions from which to run health checks. Null means every Cloudflare data center. `[ "WEU", "ENAM" ]` An array with items in the following form: Show definition »	default value: null
origin_steering object	Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. `{ "policy": "random" }` An object with the following properties: Show definition »
name string	A short name (tag) for the pool. Only alphanumeric characters, hyphens, and underscores are allowed. `"primary-dc-1"`
load_shedding object	Configures load shedding policies and percentages for the pool. `{ "default_percent": 0, "default_policy": "random", "session_percent": 0, "session_policy": "hash" }` An object with the following properties: Show definition »
latitude number	The latitude of the data center containing the origins used in this pool in decimal degrees. If this is set, longitude must also be set.
notification_filter objectnull	Filter pool and origin health notifications by resource type or health status. Use null to reset. `{ "origin": { "disable": false, "healthy": null }, "pool": { "disable": false, "healthy": null } }` An object with the following properties: Show definition »
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, "header": { "Host": [ "example.com" ] } } ]` An array with items in the following form: Show definition »
longitude number	The longitude of the data center containing the origins used in this pool in decimal degrees. If this is set, latitude must also be set.
disabled_at string (date-time)	This field shows up only if the pool is disabled. This field is set with the time the pool was disabled at.	read only
monitor string	The ID of the Monitor to use for checking the health of origins within this pool. `"f1aba936b94213e5b8dca0c0dbf1f9cc"`	max length: 32 read only
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 will failover to the next available pool. `2`	default value: 1
description string	A human-readable description of the pool. `"Primary data center - Provider XYZ"`

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/user/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Primary data center - Provider XYZ","name":"primary-dc-1","enabled":false,"check_regions":["WEU","ENAM"],"load_shedding":{"default_percent":0,"default_policy":"random","session_percent":0,"session_policy":"hash"},"minimum_origins":2,"monitor":"f1aba936b94213e5b8dca0c0dbf1f9cc","origins":[{"name":"app-server-1","address":"0.0.0.0","enabled":true,"weight":0.56,"header":{"Host":["example.com"]}}],"origin_steering":{"policy":"random"},"notification_email":"someone@example.com,sometwo@example.com","notification_filter":{"origin":{"disable":false,"healthy":null},"pool":{"disable":false,"healthy":null}}}'

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": false,
    "load_shedding": {
      "default_percent": 0,
      "default_policy": "random",
      "session_percent": 0,
      "session_policy": "hash"
    },
    "minimum_origins": 2,
    "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "origins": [
      {
        "name": "app-server-1",
        "address": "0.0.0.0",
        "enabled": true,
        "weight": 0.56,
        "header": {
          "Host": [
            "example.com"
          ]
        }
      }
    ],
    "origin_steering": {
      "policy": "random"
    },
    "notification_email": "someone@example.com,sometwo@example.com",
    "notification_filter": {
      "origin": {
        "disable": false,
        "healthy": null
      },
      "pool": {
        "disable": false,
        "healthy": null
      }
    }
  }
}

load-balancer-pools-patch-pools

PATCH Patch Pools

Apply changes to a number of existing pools, overwriting the supplied properties. Pools are ordered by ascending name. Returns the list of affected pools. Supports the standard pagination query parameters, either limit/offset or per_page/page.

PATCH user/load_balancers/pools

Optional parameters

Name /type	Description /example	Constraints
notification_email string	The email address to send health status notifications to. This field is now deprecated in favor of Cloudflare Notifications for Load Balancing, so only resetting this field with an empty string `""` is accepted. `""`	valid values: ""

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/user/load_balancers/pools" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"notification_email":""}'

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": false,
      "load_shedding": {
        "default_percent": 0,
        "default_policy": "random",
        "session_percent": 0,
        "session_policy": "hash"
      },
      "minimum_origins": 2,
      "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
      "check_regions": [
        "WEU",
        "ENAM"
      ],
      "origins": [
        {
          "name": "app-server-1",
          "address": "0.0.0.0",
          "enabled": true,
          "weight": 0.56,
          "header": {
            "Host": [
              "example.com"
            ]
          }
        }
      ],
      "origin_steering": {
        "policy": "random"
      },
      "notification_email": "someone@example.com,sometwo@example.com",
      "notification_filter": {
        "origin": {
          "disable": false,
          "healthy": null
        },
        "pool": {
          "disable": false,
          "healthy": null
        }
      }
    }
  ]
}

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

load-balancer-pools-preview-pool

POST Preview Pool

Preview pool health using provided monitor details. The returned preview_id can be used in the preview endpoint to retrieve the results.

POST user/load_balancers/pools/:identifier/preview

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, UDP, and SMTP 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 you want to conduct a health check against. This parameter is only valid for HTTP and HTTPS monitors. `"/health"`	default value: /
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', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. `"https"`	default value: http valid values: http, https, tcp, udp_icmp, icmp_ping, smtp

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/user/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4/preview" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"https","method":"GET","path":"/health","header":{"Host":["example.com"],"X-App-ID":["abc123"]},"port":8080,"timeout":3,"retries":0,"expected_body":"alive","expected_codes":"2xx","follow_redirects":true,"allow_insecure":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "preview_id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "pools": {
      "abwlnp5jbqn45ecgxd03erbgtxtqai0d": "WNAM Datacenter",
      "ve8h9lrcip5n5bbga9yqmdws28ay5d0l": "EEU Datacenter"
    }
  }
}

load-balancer-pools-list-pool-references

GET List Pool References

Get the list of resources that reference the provided pool.

GET user/load_balancers/pools/:identifier/references

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/user/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4/references" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "resource_id": "699d98642c564d2e855e9661899b7252",
      "resource_name": "www.example.com",
      "resource_type": "load_balancer",
      "reference_type": "referrer"
    },
    {
      "resource_id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
      "resource_name": "Login page monitor",
      "resource_type": "monitor",
      "reference_type": "referral"
    }
  ]
}

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. `"primary-dc-1"`
pool_name string	The name for the pool to filter. `"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: user@example.com" \
     -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
        }
      ]
    }
  ]
}

Load Balancer Regions

Region-Country geographic mappings for load balancers

load-balancer-regions

Object definition

View properties and constraints defined on the object

Show definition

load-balancer-regions-list-regions

GET List Regions

List all region mappings.

GET accounts/:account_identifier/load_balancers/regions

Optional parameters

Name /type	Description /example	Constraints
country_code string	Two-letter alpha-2 country code followed in ISO 3166-1. `"US"`
subdivision_code string	Two-letter subdivision code followed in ISO 3166-2. `"CA"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/regions?country_code=US&subdivision_code=CA" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "iso_standard": "Country and subdivision codes follow ISO 3166-1 alpha-2 and ISO 3166-2",
    "regions": [
      {
        "region_code": "WNAM",
        "countries": [
          {
            "country_code_a2": "US",
            "country_name": "United States",
            "country_subdivisions": [
              {
                "subdivision_code_a2": "CA",
                "subdivision_name": "California"
              }
            ]
          }
        ]
      }
    ]
  }
}

load-balancer-regions-get-region

GET Get Region

Get a single region mapping.

GET accounts/:account_identifier/load_balancers/regions/:region_code

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/regions/WNAM" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "iso_standard": "Country and subdivision codes follow ISO 3166-1 alpha-2 and ISO 3166-2",
    "regions": [
      {
        "region_code": "WNAM",
        "countries": [
          {
            "country_code_a2": "CA",
            "country_name": "Canada",
            "country_subdivisions": [
              {
                "subdivision_code_a2": "AB",
                "subdivision_name": "Alberta"
              },
              {
                "subdivision_code_a2": "BC",
                "subdivision_name": "British Columbia"
              }
            ]
          },
          {
            "country_code_a2": "HT",
            "country_name": "Haiti"
          },
          {
            "country_code_a2": "MX",
            "country_name": "Mexico"
          },
          {
            "country_code_a2": "US",
            "country_name": "United States",
            "country_subdivisions": [
              {
                "subdivision_code_a2": "AZ",
                "subdivision_name": "Arizona"
              },
              {
                "subdivision_code_a2": "CA",
                "subdivision_name": "California"
              },
              {
                "subdivision_code_a2": "CO",
                "subdivision_name": "Colorado"
              },
              {
                "subdivision_code_a2": "HI",
                "subdivision_name": "Hawaii"
              },
              {
                "subdivision_code_a2": "MN",
                "subdivision_name": "Minnesota"
              },
              {
                "subdivision_code_a2": "MO",
                "subdivision_name": "Missouri"
              },
              {
                "subdivision_code_a2": "NV",
                "subdivision_name": "Nevada"
              },
              {
                "subdivision_code_a2": "OR",
                "subdivision_name": "Oregon"
              },
              {
                "subdivision_code_a2": "TX",
                "subdivision_name": "Texas"
              },
              {
                "subdivision_code_a2": "UT",
                "subdivision_name": "Utah"
              },
              {
                "subdivision_code_a2": "WA",
                "subdivision_name": "Washington"
              }
            ]
          }
        ]
      }
    ]
  }
}

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: user@example.com" \
     -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,
      "consecutive_up": 3,
      "consecutive_down": 2,
      "probe_zone": "example.com"
    }
  ]
}

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 codes or code ranges of the health check, comma-separated. This parameter is only valid for HTTP and HTTPS monitors. `"2xx"`	default value: 200

Optional parameters

Name /type	Description /example	Constraints
port integer	The port number to connect to for the health check. Required for TCP, UDP, and SMTP 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 you want to conduct a 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" ] }`
consecutive_up integer	To be marked healthy the monitored origin must pass this healthcheck N consecutive times `3`	default value: 0
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)
consecutive_down integer	To be marked unhealthy the monitored origin must fail this healthcheck N consecutive times `2`	default value: 0
type string	The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. `"https"`	default value: http valid values: http, https, tcp, udp_icmp, icmp_ping, smtp
probe_zone string	Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors. `"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: user@example.com" \
     -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,"consecutive_up":3,"consecutive_down":2,"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,
    "consecutive_up": 3,
    "consecutive_down": 2,
    "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: user@example.com" \
     -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,
    "consecutive_up": 3,
    "consecutive_down": 2,
    "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 codes or code ranges of the health check, comma-separated. This parameter is only valid for HTTP and HTTPS monitors. `"2xx"`	default value: 200

Optional parameters

Name /type	Description /example	Constraints
port integer	The port number to connect to for the health check. Required for TCP, UDP, and SMTP 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 you want to conduct a 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" ] }`
consecutive_up integer	To be marked healthy the monitored origin must pass this healthcheck N consecutive times `3`	default value: 0
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)
consecutive_down integer	To be marked unhealthy the monitored origin must fail this healthcheck N consecutive times `2`	default value: 0
type string	The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. `"https"`	default value: http valid values: http, https, tcp, udp_icmp, icmp_ping, smtp
probe_zone string	Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors. `"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: user@example.com" \
     -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,"consecutive_up":3,"consecutive_down":2,"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,
    "consecutive_up": 3,
    "consecutive_down": 2,
    "probe_zone": "example.com"
  }
}

account-load-balancer-monitors-patch-monitor

PATCH Patch Monitor

Apply changes to an existing monitor, overwriting the supplied properties.

PATCH accounts/:account_identifier/load_balancers/monitors/:identifier

Optional parameters

Name /type	Description /example	Constraints
port integer	The port number to connect to for the health check. Required for TCP, UDP, and SMTP 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 you want to conduct a 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" ] }`
consecutive_up integer	To be marked healthy the monitored origin must pass this healthcheck N consecutive times `3`	default value: 0
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)
consecutive_down integer	To be marked unhealthy the monitored origin must fail this healthcheck N consecutive times `2`	default value: 0
type string	The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. `"https"`	default value: http valid values: http, https, tcp, udp_icmp, icmp_ping, smtp
probe_zone string	Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors. `"example.com"`
description string	Object description `"Login page monitor"`
expected_codes string	The expected HTTP response codes or code ranges of the health check, comma-separated. This parameter is only valid for HTTP and HTTPS monitors. `"2xx"`	default value: 200

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/monitors/f1aba936b94213e5b8dca0c0dbf1f9cc" \
     -H "X-Auth-Email: user@example.com" \
     -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,"consecutive_up":3,"consecutive_down":2,"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,
    "consecutive_up": 3,
    "consecutive_down": 2,
    "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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

account-load-balancer-monitors-preview-monitor

POST Preview Monitor

Preview pools using the specified monitor with provided monitor details. The returned preview_id can be used in the preview endpoint to retrieve the results.

POST accounts/:account_identifier/load_balancers/monitors/:identifier/preview

Required parameters

Name /type	Description /example	Constraints
expected_codes string	The expected HTTP response codes or code ranges of the health check, comma-separated. This parameter is only valid for HTTP and HTTPS monitors. `"2xx"`	default value: 200

Optional parameters

Name /type	Description /example	Constraints
port integer	The port number to connect to for the health check. Required for TCP, UDP, and SMTP 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 you want to conduct a health check against. This parameter is only valid for HTTP and HTTPS monitors. `"/health"`	default value: /
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', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. `"https"`	default value: http valid values: http, https, tcp, udp_icmp, icmp_ping, smtp
probe_zone string	Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors. `"example.com"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/monitors/f1aba936b94213e5b8dca0c0dbf1f9cc/preview" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"https","method":"GET","path":"/health","header":{"Host":["example.com"],"X-App-ID":["abc123"]},"port":8080,"timeout":3,"retries":0,"expected_body":"alive","expected_codes":"2xx","follow_redirects":true,"allow_insecure":true,"probe_zone":"example.com"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "preview_id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "pools": {
      "abwlnp5jbqn45ecgxd03erbgtxtqai0d": "WNAM Datacenter",
      "ve8h9lrcip5n5bbga9yqmdws28ay5d0l": "EEU Datacenter"
    }
  }
}

account-load-balancer-monitors-preview-result

GET Preview Result

Get the result of a previous preview operation using the provided preview_id.

GET accounts/:account_identifier/load_balancers/preview/:preview_id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/preview/p1aba936b94213e5b8dca0c0dbf1f9cc?" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "abwlnp5jbqn45ecgxd03erbgtxtqai0d": {
    "healthy": true,
    "origins": [
      {
        "originone.example.com.": {
          "healthy": true,
          "rtt": "66ms",
          "failure_reason": "No failures",
          "response_code": 200
        }
      }
    ]
  }
}

account-load-balancer-monitors-list-monitor-references

GET List Monitor References

Get the list of resources that reference the provided monitor.

GET accounts/:account_identifier/load_balancers/monitors/:identifier/references

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/monitors/f1aba936b94213e5b8dca0c0dbf1f9cc/references" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "resource_id": "17b5962d775c646f3f9725cbc7a53df4",
      "resource_name": "primary-dc-1",
      "resource_type": "pool",
      "reference_type": "referrer"
    }
  ]
}

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

Optional parameters

Name /type	Description /example	Constraints
monitor string	The ID of the Monitor to use for checking the health of origins within this pool. `"f1aba936b94213e5b8dca0c0dbf1f9cc"`	max length: 32 read only

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/pools?monitor=f1aba936b94213e5b8dca0c0dbf1f9cc" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "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": false,
      "load_shedding": {
        "default_percent": 0,
        "default_policy": "random",
        "session_percent": 0,
        "session_policy": "hash"
      },
      "minimum_origins": 2,
      "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
      "check_regions": [
        "WEU",
        "ENAM"
      ],
      "origins": [
        {
          "name": "app-server-1",
          "address": "0.0.0.0",
          "enabled": true,
          "weight": 0.56,
          "header": {
            "Host": [
              "example.com"
            ]
          }
        }
      ],
      "origin_steering": {
        "policy": "random"
      },
      "notification_email": "someone@example.com,sometwo@example.com",
      "notification_filter": {
        "origin": {
          "disable": false,
          "healthy": null
        },
        "pool": {
          "disable": false,
          "healthy": null
        }
      }
    }
  ]
}

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, "header": { "Host": [ "example.com" ] } } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
enabled boolean	Whether to enable (the default) or disable 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). `false`	default value: true valid values: (true,false)
notification_email string	The email address to send health status notifications to. This can be an individual mailbox or a mailing list. Multiple emails can be supplied as a comma delimited list. `"someone@example.com,sometwo@example.com"`
origin_steering object	Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. `{ "policy": "random" }` An object with the following properties: Show definition »
load_shedding object	Configures load shedding policies and percentages for the pool. `{ "default_percent": 0, "default_policy": "random", "session_percent": 0, "session_policy": "hash" }` An object with the following properties: Show definition »
latitude number	The latitude of the data center containing the origins used in this pool in decimal degrees. If this is set, longitude must also be set.
notification_filter objectnull	Filter pool and origin health notifications by resource type or health status. Use null to reset. `{ "origin": { "disable": false, "healthy": null }, "pool": { "disable": false, "healthy": null } }` An object with the following properties: Show definition »
longitude number	The longitude of the data center containing the origins used in this pool in decimal degrees. If this is set, latitude must also be set.
monitor string	The ID of the Monitor to use for checking the health of origins within this pool. `"f1aba936b94213e5b8dca0c0dbf1f9cc"`	max length: 32 read only
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 will failover to the next available pool. `2`	default value: 1
description string	A human-readable description of the pool. `"Primary data center - Provider XYZ"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/pools" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Primary data center - Provider XYZ","name":"primary-dc-1","enabled":false,"load_shedding":{"default_percent":0,"default_policy":"random","session_percent":0,"session_policy":"hash"},"minimum_origins":2,"monitor":"f1aba936b94213e5b8dca0c0dbf1f9cc","origins":[{"name":"app-server-1","address":"0.0.0.0","enabled":true,"weight":0.56,"header":{"Host":["example.com"]}}],"origin_steering":{"policy":"random"},"notification_email":"someone@example.com,sometwo@example.com","notification_filter":{"origin":{"disable":false,"healthy":null},"pool":{"disable":false,"healthy":null}}}'

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": false,
    "load_shedding": {
      "default_percent": 0,
      "default_policy": "random",
      "session_percent": 0,
      "session_policy": "hash"
    },
    "minimum_origins": 2,
    "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "origins": [
      {
        "name": "app-server-1",
        "address": "0.0.0.0",
        "enabled": true,
        "weight": 0.56,
        "header": {
          "Host": [
            "example.com"
          ]
        }
      }
    ],
    "origin_steering": {
      "policy": "random"
    },
    "notification_email": "someone@example.com,sometwo@example.com",
    "notification_filter": {
      "origin": {
        "disable": false,
        "healthy": null
      },
      "pool": {
        "disable": false,
        "healthy": null
      }
    }
  }
}

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: user@example.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": false,
    "load_shedding": {
      "default_percent": 0,
      "default_policy": "random",
      "session_percent": 0,
      "session_policy": "hash"
    },
    "minimum_origins": 2,
    "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "origins": [
      {
        "name": "app-server-1",
        "address": "0.0.0.0",
        "enabled": true,
        "weight": 0.56,
        "header": {
          "Host": [
            "example.com"
          ]
        }
      }
    ],
    "origin_steering": {
      "policy": "random"
    },
    "notification_email": "someone@example.com,sometwo@example.com",
    "notification_filter": {
      "origin": {
        "disable": false,
        "healthy": null
      },
      "pool": {
        "disable": false,
        "healthy": null
      }
    }
  }
}

account-load-balancer-pools-pool-health-details

GET Pool Health Details

Fetch the latest pool health status 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: user@example.com" \
     -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, "header": { "Host": [ "example.com" ] } } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
enabled boolean	Whether to enable (the default) or disable 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). `false`	default value: true valid values: (true,false)
notification_email string	The email address to send health status notifications to. This can be an individual mailbox or a mailing list. Multiple emails can be supplied as a comma delimited list. `"someone@example.com,sometwo@example.com"`
check_regions arraynull	A list of regions from which to run health checks. Null means every Cloudflare data center. `[ "WEU", "ENAM" ]` An array with items in the following form: Show definition »	default value: null
origin_steering object	Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. `{ "policy": "random" }` An object with the following properties: Show definition »
load_shedding object	Configures load shedding policies and percentages for the pool. `{ "default_percent": 0, "default_policy": "random", "session_percent": 0, "session_policy": "hash" }` An object with the following properties: Show definition »
latitude number	The latitude of the data center containing the origins used in this pool in decimal degrees. If this is set, longitude must also be set.
notification_filter objectnull	Filter pool and origin health notifications by resource type or health status. Use null to reset. `{ "origin": { "disable": false, "healthy": null }, "pool": { "disable": false, "healthy": null } }` An object with the following properties: Show definition »
longitude number	The longitude of the data center containing the origins used in this pool in decimal degrees. If this is set, latitude must also be set.
disabled_at string (date-time)	This field shows up only if the pool is disabled. This field is set with the time the pool was disabled at.	read only
monitor string	The ID of the Monitor to use for checking the health of origins within this pool. `"f1aba936b94213e5b8dca0c0dbf1f9cc"`	max length: 32 read only
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 will failover to the next available pool. `2`	default value: 1
description string	A human-readable description of the pool. `"Primary data center - Provider XYZ"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Primary data center - Provider XYZ","name":"primary-dc-1","enabled":false,"check_regions":["WEU","ENAM"],"load_shedding":{"default_percent":0,"default_policy":"random","session_percent":0,"session_policy":"hash"},"minimum_origins":2,"monitor":"f1aba936b94213e5b8dca0c0dbf1f9cc","origins":[{"name":"app-server-1","address":"0.0.0.0","enabled":true,"weight":0.56,"header":{"Host":["example.com"]}}],"origin_steering":{"policy":"random"},"notification_email":"someone@example.com,sometwo@example.com","notification_filter":{"origin":{"disable":false,"healthy":null},"pool":{"disable":false,"healthy":null}}}'

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": false,
    "load_shedding": {
      "default_percent": 0,
      "default_policy": "random",
      "session_percent": 0,
      "session_policy": "hash"
    },
    "minimum_origins": 2,
    "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "origins": [
      {
        "name": "app-server-1",
        "address": "0.0.0.0",
        "enabled": true,
        "weight": 0.56,
        "header": {
          "Host": [
            "example.com"
          ]
        }
      }
    ],
    "origin_steering": {
      "policy": "random"
    },
    "notification_email": "someone@example.com,sometwo@example.com",
    "notification_filter": {
      "origin": {
        "disable": false,
        "healthy": null
      },
      "pool": {
        "disable": false,
        "healthy": null
      }
    }
  }
}

account-load-balancer-pools-patch-pool

PATCH Patch Pool

Apply changes to an existing pool, overwriting the supplied properties.

PATCH accounts/:account_identifier/load_balancers/pools/:identifier

Optional parameters

Name /type	Description /example	Constraints
enabled boolean	Whether to enable (the default) or disable 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). `false`	default value: true valid values: (true,false)
notification_email string	The email address to send health status notifications to. This can be an individual mailbox or a mailing list. Multiple emails can be supplied as a comma delimited list. `"someone@example.com,sometwo@example.com"`
check_regions arraynull	A list of regions from which to run health checks. Null means every Cloudflare data center. `[ "WEU", "ENAM" ]` An array with items in the following form: Show definition »	default value: null
origin_steering object	Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. `{ "policy": "random" }` An object with the following properties: Show definition »
name string	A short name (tag) for the pool. Only alphanumeric characters, hyphens, and underscores are allowed. `"primary-dc-1"`
load_shedding object	Configures load shedding policies and percentages for the pool. `{ "default_percent": 0, "default_policy": "random", "session_percent": 0, "session_policy": "hash" }` An object with the following properties: Show definition »
latitude number	The latitude of the data center containing the origins used in this pool in decimal degrees. If this is set, longitude must also be set.
notification_filter objectnull	Filter pool and origin health notifications by resource type or health status. Use null to reset. `{ "origin": { "disable": false, "healthy": null }, "pool": { "disable": false, "healthy": null } }` An object with the following properties: Show definition »
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, "header": { "Host": [ "example.com" ] } } ]` An array with items in the following form: Show definition »
longitude number	The longitude of the data center containing the origins used in this pool in decimal degrees. If this is set, latitude must also be set.
disabled_at string (date-time)	This field shows up only if the pool is disabled. This field is set with the time the pool was disabled at.	read only
monitor string	The ID of the Monitor to use for checking the health of origins within this pool. `"f1aba936b94213e5b8dca0c0dbf1f9cc"`	max length: 32 read only
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 will failover to the next available pool. `2`	default value: 1
description string	A human-readable description of the pool. `"Primary data center - Provider XYZ"`

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Primary data center - Provider XYZ","name":"primary-dc-1","enabled":false,"check_regions":["WEU","ENAM"],"load_shedding":{"default_percent":0,"default_policy":"random","session_percent":0,"session_policy":"hash"},"minimum_origins":2,"monitor":"f1aba936b94213e5b8dca0c0dbf1f9cc","origins":[{"name":"app-server-1","address":"0.0.0.0","enabled":true,"weight":0.56,"header":{"Host":["example.com"]}}],"origin_steering":{"policy":"random"},"notification_email":"someone@example.com,sometwo@example.com","notification_filter":{"origin":{"disable":false,"healthy":null},"pool":{"disable":false,"healthy":null}}}'

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": false,
    "load_shedding": {
      "default_percent": 0,
      "default_policy": "random",
      "session_percent": 0,
      "session_policy": "hash"
    },
    "minimum_origins": 2,
    "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "origins": [
      {
        "name": "app-server-1",
        "address": "0.0.0.0",
        "enabled": true,
        "weight": 0.56,
        "header": {
          "Host": [
            "example.com"
          ]
        }
      }
    ],
    "origin_steering": {
      "policy": "random"
    },
    "notification_email": "someone@example.com,sometwo@example.com",
    "notification_filter": {
      "origin": {
        "disable": false,
        "healthy": null
      },
      "pool": {
        "disable": false,
        "healthy": null
      }
    }
  }
}

account-load-balancer-pools-patch-pools

PATCH Patch Pools

PATCH accounts/:account_identifier/load_balancers/pools

Optional parameters

Name /type	Description /example	Constraints
notification_email string	The email address to send health status notifications to. This field is now deprecated in favor of Cloudflare Notifications for Load Balancing, so only resetting this field with an empty string `""` is accepted. `""`	valid values: ""

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/pools" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"notification_email":""}'

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": false,
      "load_shedding": {
        "default_percent": 0,
        "default_policy": "random",
        "session_percent": 0,
        "session_policy": "hash"
      },
      "minimum_origins": 2,
      "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
      "check_regions": [
        "WEU",
        "ENAM"
      ],
      "origins": [
        {
          "name": "app-server-1",
          "address": "0.0.0.0",
          "enabled": true,
          "weight": 0.56,
          "header": {
            "Host": [
              "example.com"
            ]
          }
        }
      ],
      "origin_steering": {
        "policy": "random"
      },
      "notification_email": "someone@example.com,sometwo@example.com",
      "notification_filter": {
        "origin": {
          "disable": false,
          "healthy": null
        },
        "pool": {
          "disable": false,
          "healthy": null
        }
      }
    }
  ]
}

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

account-load-balancer-pools-preview-pool

POST Preview Pool

Preview pool health using provided monitor details. The returned preview_id can be used in the preview endpoint to retrieve the results.

POST accounts/:account_identifier/load_balancers/pools/:identifier/preview

Required parameters

Name /type	Description /example	Constraints
expected_codes string	The expected HTTP response codes or code ranges of the health check, comma-separated. This parameter is only valid for HTTP and HTTPS monitors. `"2xx"`	default value: 200

Optional parameters

Name /type	Description /example	Constraints
port integer	The port number to connect to for the health check. Required for TCP, UDP, and SMTP 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 you want to conduct a health check against. This parameter is only valid for HTTP and HTTPS monitors. `"/health"`	default value: /
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', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. `"https"`	default value: http valid values: http, https, tcp, udp_icmp, icmp_ping, smtp
probe_zone string	Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors. `"example.com"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4/preview" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"https","method":"GET","path":"/health","header":{"Host":["example.com"],"X-App-ID":["abc123"]},"port":8080,"timeout":3,"retries":0,"expected_body":"alive","expected_codes":"2xx","follow_redirects":true,"allow_insecure":true,"probe_zone":"example.com"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "preview_id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "pools": {
      "abwlnp5jbqn45ecgxd03erbgtxtqai0d": "WNAM Datacenter",
      "ve8h9lrcip5n5bbga9yqmdws28ay5d0l": "EEU Datacenter"
    }
  }
}

account-load-balancer-pools-list-pool-references

GET List Pool References

Get the list of resources that reference the provided pool.

GET accounts/:account_identifier/load_balancers/pools/:identifier/references

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/pools/17b5962d775c646f3f9725cbc7a53df4/references" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "resource_id": "699d98642c564d2e855e9661899b7252",
      "resource_name": "www.example.com",
      "resource_type": "load_balancer",
      "reference_type": "referrer"
    },
    {
      "resource_id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
      "resource_name": "Login page monitor",
      "resource_type": "monitor",
      "reference_type": "referral"
    }
  ]
}

Account Load Balancer Search

Account-level Load Balancer Search

account-load-balancer-search

Object definition

View properties and constraints defined on the object

Show definition

account-load-balancer-search-search-resources

GET Search Resources

Search for Load Balancing resources.

GET accounts/:account_identifier/load_balancers/search

Optional parameters

Name /type	Description /example	Constraints
page number	Requested page within paginated list of results `1`	min value:1
per_page number	Maximum number of results requested `25`	default value: 25 min value:1 max value:1000
query string	Search query term `"primary"`	default value:
references string	The type of references to include ("" for all). `""`	default value: valid values: , *, referral, referrer

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/load_balancers/search?page=undefined&per_page=25&query=primary&references=*" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "resources": [
      {
        "resource_id": "17b5962d775c646f3f9725cbc7a53df4",
        "resource_name": "primary-dc-1",
        "resource_type": "pool",
        "references": [
          {
            "resource_id": "699d98642c564d2e855e9661899b7252",
            "resource_name": "www.example.com",
            "resource_type": "load_balancer",
            "reference_type": "referrer"
          },
          {
            "resource_id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
            "resource_name": "Login page monitor",
            "resource_type": "monitor",
            "reference_type": "referral"
          }
        ]
      }
    ]
  }
}

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: user@example.com" \
     -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"
        ]
      },
      "country_pools": {
        "US": [
          "de90f38ced07c2e2f4df50b1f61d4194",
          "00920f38ce07c2e2f4df50b1f61d4194"
        ],
        "GB": [
          "abd90f38ced07c2e2f4df50b1f61d4194"
        ]
      },
      "pop_pools": {
        "LAX": [
          "de90f38ced07c2e2f4df50b1f61d4194",
          "9290f38c5d07c2e2f4df57b1f61d4196"
        ],
        "LHR": [
          "abd90f38ced07c2e2f4df50b1f61d4194",
          "f9138c5d07c2e2f4df57b1f61d4196"
        ],
        "SJC": [
          "00920f38ce07c2e2f4df50b1f61d4194"
        ]
      },
      "proxied": true,
      "steering_policy": "dynamic_latency",
      "session_affinity": "cookie",
      "session_affinity_attributes": {
        "samesite": "Auto",
        "secure": "Auto",
        "drain_duration": 100,
        "zero_downtime_failover": "sticky"
      },
      "session_affinity_ttl": 5000,
      "adaptive_routing": {
        "failover_across_pools": true
      },
      "location_strategy": {
        "prefer_ecs": "always",
        "mode": "resolver_ip"
      },
      "random_steering": {
        "pool_weights": {
          "de90f38ced07c2e2f4df50b1f61d4194": 0.3,
          "9290f38c5d07c2e2f4df57b1f61d4196": 0.5
        },
        "default_weight": 0.2
      },
      "rules": [
        {
          "name": "route the path /testing to testing datacenter.",
          "condition": "http.request.uri.path contains \"/testing\"",
          "overrides": {
            "session_affinity": "cookie",
            "session_affinity_ttl": 5000,
            "session_affinity_attributes": {
              "samesite": "Auto",
              "secure": "Auto",
              "drain_duration": 100,
              "zero_downtime_failover": "sticky"
            },
            "adaptive_routing": {
              "failover_across_pools": true
            },
            "location_strategy": {
              "prefer_ecs": "always",
              "mode": "resolver_ip"
            },
            "ttl": 30,
            "steering_policy": "dynamic_latency",
            "fallback_pool": "17b5962d775c646f3f9725cbc7a53df4",
            "default_pools": [
              "17b5962d775c646f3f9725cbc7a53df4",
              "9290f38c5d07c2e2f4df57b1f61d4196",
              "00920f38ce07c2e2f4df50b1f61d4194"
            ],
            "pop_pools": {
              "LAX": [
                "de90f38ced07c2e2f4df50b1f61d4194",
                "9290f38c5d07c2e2f4df57b1f61d4196"
              ],
              "LHR": [
                "abd90f38ced07c2e2f4df50b1f61d4194",
                "f9138c5d07c2e2f4df57b1f61d4196"
              ],
              "SJC": [
                "00920f38ce07c2e2f4df50b1f61d4194"
              ]
            },
            "region_pools": {
              "WNAM": [
                "de90f38ced07c2e2f4df50b1f61d4194",
                "9290f38c5d07c2e2f4df57b1f61d4196"
              ],
              "ENAM": [
                "00920f38ce07c2e2f4df50b1f61d4194"
              ]
            },
            "country_pools": {
              "US": [
                "de90f38ced07c2e2f4df50b1f61d4194",
                "00920f38ce07c2e2f4df50b1f61d4194"
              ],
              "GB": [
                "abd90f38ced07c2e2f4df50b1f61d4194"
              ]
            },
            "random_steering": {
              "pool_weights": {
                "de90f38ced07c2e2f4df50b1f61d4194": 0.3,
                "9290f38c5d07c2e2f4df57b1f61d4196": 0.5
              },
              "default_weight": 0.2
            }
          },
          "priority": 55,
          "disabled": false,
          "terminates": false,
          "fixed_response": {
            "message_body": "Testing Hello",
            "status_code": 200,
            "content_type": "application/json",
            "location": "www.example.com"
          }
        }
      ]
    }
  ]
}

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" ]` An array with items in the following form: Show definition »
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`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. `"random"`: Select a pool randomly. `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). `"proximity"`: Use the pools' latitude and longitude to select the closest pool using the Cloudflare PoP location for proxied requests or the location determined by `location_strategy` for non-proxied requests. `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. `"dynamic_latency"`	default value: "" valid values: off, geo, random, dynamic_latency, proximity, ""
session_affinity_attributes object	Configures cookie attributes for session affinity cookie. `{ "samesite": "Auto", "secure": "Auto", "drain_duration": 100, "zero_downtime_failover": "sticky" }` An object with the following properties: Show definition »
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 the corresponding country_pool, then region_pool mapping if it exists else to 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 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" ] }`
random_steering object	Configures pool weights for random steering. When steering_policy is 'random', a random pool is selected with probability proportional to these pool weights. `{ "pool_weights": { "de90f38ced07c2e2f4df50b1f61d4194": 0.3, "9290f38c5d07c2e2f4df57b1f61d4196": 0.5 }, "default_weight": 0.2 }` An object with the following properties: Show definition »
country_pools object	A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. `{ "US": [ "de90f38ced07c2e2f4df50b1f61d4194", "00920f38ce07c2e2f4df50b1f61d4194" ], "GB": [ "abd90f38ced07c2e2f4df50b1f61d4194" ] }`
session_affinity string	The session_affinity specifies the type of session affinity the load balancer 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, ""
rules array	BETA Field Not General Access: A list of rules for this load balancer to execute. [ { "name": "route the path /testing to testing datacenter.", "condition": "http.request.uri.path contains \"/testing\"", "overrides": { "session_affinity": "cookie", "session_affinity_ttl": 5000, "session_affinity_attributes": { "samesite": "Auto", "secure": "Auto", "drain_duration": 100, "zero_downtime_failover": "sticky" }, "adaptive_routing": { "failover_across_pools": true }, "location_strategy": { "prefer_ecs": "always", "mode": "resolver_ip" }, "ttl": 30, "steering_policy": "dynamic_latency", "fallback_pool": "17b5962d775c646f3f9725cbc7a53df4", "default_pools": [ "17b5962d775c646f3f9725cbc7a53df4", "9290f38c5d07c2e2f4df57b1f61d4196", "00920f38ce07c2e2f4df50b1f61d4194" ], "pop_pools": { "LAX": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "LHR": [ "abd90f38ced07c2e2f4df50b1f61d4194", "f9138c5d07c2e2f4df57b1f61d4196" ], "SJC": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }, "region_pools": { "WNAM": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "ENAM": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }, "country_pools": { "US": [ "de90f38ced07c2e2f4df50b1f61d4194", "00920f38ce07c2e2f4df50b1f61d4194" ], "GB": [ "abd90f38ced07c2e2f4df50b1f61d4194" ] }, "random_steering": { "pool_weights": { "de90f38ced07c2e2f4df50b1f61d4194": 0.3, "9290f38c5d07c2e2f4df57b1f61d4196": 0.5 }, "default_weight": 0.2 } }, "priority": 55, "disabled": false, "terminates": false, "fixed_response": { "message_body": "Testing Hello", "status_code": 200, "content_type": "application/json", "location": "www.example.com" } } ] An array with items in the following form: Show definition »
description string	Object description `"Load Balancer for www.example.com"`
location_strategy object	Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. `{ "prefer_ecs": "always", "mode": "resolver_ip" }` An object with the following properties: Show definition »
proxied boolean	Whether the hostname should be gray clouded (false) or orange clouded (true). `true`	default value: false valid values: (true,false)
adaptive_routing object	Controls features that modify the routing of requests to pools and origins in response to dynamic conditions, such as during the interval between active health monitoring requests. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. `{ "failover_across_pools": true }` An object with the following properties: Show definition »
session_affinity_ttl number	Time, in seconds, until this load balancer's 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: user@example.com" \
     -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"]},"country_pools":{"US":["de90f38ced07c2e2f4df50b1f61d4194","00920f38ce07c2e2f4df50b1f61d4194"],"GB":["abd90f38ced07c2e2f4df50b1f61d4194"]},"pop_pools":{"LAX":["de90f38ced07c2e2f4df50b1f61d4194","9290f38c5d07c2e2f4df57b1f61d4196"],"LHR":["abd90f38ced07c2e2f4df50b1f61d4194","f9138c5d07c2e2f4df57b1f61d4196"],"SJC":["00920f38ce07c2e2f4df50b1f61d4194"]},"proxied":true,"steering_policy":"dynamic_latency","session_affinity":"cookie","session_affinity_attributes":{"samesite":"Auto","secure":"Auto","drain_duration":100,"zero_downtime_failover":"sticky"},"session_affinity_ttl":5000,"adaptive_routing":{"failover_across_pools":true},"location_strategy":{"prefer_ecs":"always","mode":"resolver_ip"},"random_steering":{"pool_weights":{"de90f38ced07c2e2f4df50b1f61d4194":0.3,"9290f38c5d07c2e2f4df57b1f61d4196":0.5},"default_weight":0.2},"rules":[{"name":"route the path /testing to testing datacenter.","condition":"http.request.uri.path contains \"/testing\"","overrides":{"session_affinity":"cookie","session_affinity_ttl":5000,"session_affinity_attributes":{"samesite":"Auto","secure":"Auto","drain_duration":100,"zero_downtime_failover":"sticky"},"adaptive_routing":{"failover_across_pools":true},"location_strategy":{"prefer_ecs":"always","mode":"resolver_ip"},"ttl":30,"steering_policy":"dynamic_latency","fallback_pool":"17b5962d775c646f3f9725cbc7a53df4","default_pools":["17b5962d775c646f3f9725cbc7a53df4","9290f38c5d07c2e2f4df57b1f61d4196","00920f38ce07c2e2f4df50b1f61d4194"],"pop_pools":{"LAX":["de90f38ced07c2e2f4df50b1f61d4194","9290f38c5d07c2e2f4df57b1f61d4196"],"LHR":["abd90f38ced07c2e2f4df50b1f61d4194","f9138c5d07c2e2f4df57b1f61d4196"],"SJC":["00920f38ce07c2e2f4df50b1f61d4194"]},"region_pools":{"WNAM":["de90f38ced07c2e2f4df50b1f61d4194","9290f38c5d07c2e2f4df57b1f61d4196"],"ENAM":["00920f38ce07c2e2f4df50b1f61d4194"]},"country_pools":{"US":["de90f38ced07c2e2f4df50b1f61d4194","00920f38ce07c2e2f4df50b1f61d4194"],"GB":["abd90f38ced07c2e2f4df50b1f61d4194"]},"random_steering":{"pool_weights":{"de90f38ced07c2e2f4df50b1f61d4194":0.3,"9290f38c5d07c2e2f4df57b1f61d4196":0.5},"default_weight":0.2}},"priority":55,"disabled":false,"terminates":false,"fixed_response":{"message_body":"Testing Hello","status_code":200,"content_type":"application/json","location":"www.example.com"}}]}'

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"
      ]
    },
    "country_pools": {
      "US": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "00920f38ce07c2e2f4df50b1f61d4194"
      ],
      "GB": [
        "abd90f38ced07c2e2f4df50b1f61d4194"
      ]
    },
    "pop_pools": {
      "LAX": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "9290f38c5d07c2e2f4df57b1f61d4196"
      ],
      "LHR": [
        "abd90f38ced07c2e2f4df50b1f61d4194",
        "f9138c5d07c2e2f4df57b1f61d4196"
      ],
      "SJC": [
        "00920f38ce07c2e2f4df50b1f61d4194"
      ]
    },
    "proxied": true,
    "steering_policy": "dynamic_latency",
    "session_affinity": "cookie",
    "session_affinity_attributes": {
      "samesite": "Auto",
      "secure": "Auto",
      "drain_duration": 100,
      "zero_downtime_failover": "sticky"
    },
    "session_affinity_ttl": 5000,
    "adaptive_routing": {
      "failover_across_pools": true
    },
    "location_strategy": {
      "prefer_ecs": "always",
      "mode": "resolver_ip"
    },
    "random_steering": {
      "pool_weights": {
        "de90f38ced07c2e2f4df50b1f61d4194": 0.3,
        "9290f38c5d07c2e2f4df57b1f61d4196": 0.5
      },
      "default_weight": 0.2
    },
    "rules": [
      {
        "name": "route the path /testing to testing datacenter.",
        "condition": "http.request.uri.path contains \"/testing\"",
        "overrides": {
          "session_affinity": "cookie",
          "session_affinity_ttl": 5000,
          "session_affinity_attributes": {
            "samesite": "Auto",
            "secure": "Auto",
            "drain_duration": 100,
            "zero_downtime_failover": "sticky"
          },
          "adaptive_routing": {
            "failover_across_pools": true
          },
          "location_strategy": {
            "prefer_ecs": "always",
            "mode": "resolver_ip"
          },
          "ttl": 30,
          "steering_policy": "dynamic_latency",
          "fallback_pool": "17b5962d775c646f3f9725cbc7a53df4",
          "default_pools": [
            "17b5962d775c646f3f9725cbc7a53df4",
            "9290f38c5d07c2e2f4df57b1f61d4196",
            "00920f38ce07c2e2f4df50b1f61d4194"
          ],
          "pop_pools": {
            "LAX": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "9290f38c5d07c2e2f4df57b1f61d4196"
            ],
            "LHR": [
              "abd90f38ced07c2e2f4df50b1f61d4194",
              "f9138c5d07c2e2f4df57b1f61d4196"
            ],
            "SJC": [
              "00920f38ce07c2e2f4df50b1f61d4194"
            ]
          },
          "region_pools": {
            "WNAM": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "9290f38c5d07c2e2f4df57b1f61d4196"
            ],
            "ENAM": [
              "00920f38ce07c2e2f4df50b1f61d4194"
            ]
          },
          "country_pools": {
            "US": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "00920f38ce07c2e2f4df50b1f61d4194"
            ],
            "GB": [
              "abd90f38ced07c2e2f4df50b1f61d4194"
            ]
          },
          "random_steering": {
            "pool_weights": {
              "de90f38ced07c2e2f4df50b1f61d4194": 0.3,
              "9290f38c5d07c2e2f4df57b1f61d4196": 0.5
            },
            "default_weight": 0.2
          }
        },
        "priority": 55,
        "disabled": false,
        "terminates": false,
        "fixed_response": {
          "message_body": "Testing Hello",
          "status_code": 200,
          "content_type": "application/json",
          "location": "www.example.com"
        }
      }
    ]
  }
}

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: user@example.com" \
     -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"
      ]
    },
    "country_pools": {
      "US": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "00920f38ce07c2e2f4df50b1f61d4194"
      ],
      "GB": [
        "abd90f38ced07c2e2f4df50b1f61d4194"
      ]
    },
    "pop_pools": {
      "LAX": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "9290f38c5d07c2e2f4df57b1f61d4196"
      ],
      "LHR": [
        "abd90f38ced07c2e2f4df50b1f61d4194",
        "f9138c5d07c2e2f4df57b1f61d4196"
      ],
      "SJC": [
        "00920f38ce07c2e2f4df50b1f61d4194"
      ]
    },
    "proxied": true,
    "steering_policy": "dynamic_latency",
    "session_affinity": "cookie",
    "session_affinity_attributes": {
      "samesite": "Auto",
      "secure": "Auto",
      "drain_duration": 100,
      "zero_downtime_failover": "sticky"
    },
    "session_affinity_ttl": 5000,
    "adaptive_routing": {
      "failover_across_pools": true
    },
    "location_strategy": {
      "prefer_ecs": "always",
      "mode": "resolver_ip"
    },
    "random_steering": {
      "pool_weights": {
        "de90f38ced07c2e2f4df50b1f61d4194": 0.3,
        "9290f38c5d07c2e2f4df57b1f61d4196": 0.5
      },
      "default_weight": 0.2
    },
    "rules": [
      {
        "name": "route the path /testing to testing datacenter.",
        "condition": "http.request.uri.path contains \"/testing\"",
        "overrides": {
          "session_affinity": "cookie",
          "session_affinity_ttl": 5000,
          "session_affinity_attributes": {
            "samesite": "Auto",
            "secure": "Auto",
            "drain_duration": 100,
            "zero_downtime_failover": "sticky"
          },
          "adaptive_routing": {
            "failover_across_pools": true
          },
          "location_strategy": {
            "prefer_ecs": "always",
            "mode": "resolver_ip"
          },
          "ttl": 30,
          "steering_policy": "dynamic_latency",
          "fallback_pool": "17b5962d775c646f3f9725cbc7a53df4",
          "default_pools": [
            "17b5962d775c646f3f9725cbc7a53df4",
            "9290f38c5d07c2e2f4df57b1f61d4196",
            "00920f38ce07c2e2f4df50b1f61d4194"
          ],
          "pop_pools": {
            "LAX": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "9290f38c5d07c2e2f4df57b1f61d4196"
            ],
            "LHR": [
              "abd90f38ced07c2e2f4df50b1f61d4194",
              "f9138c5d07c2e2f4df57b1f61d4196"
            ],
            "SJC": [
              "00920f38ce07c2e2f4df50b1f61d4194"
            ]
          },
          "region_pools": {
            "WNAM": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "9290f38c5d07c2e2f4df57b1f61d4196"
            ],
            "ENAM": [
              "00920f38ce07c2e2f4df50b1f61d4194"
            ]
          },
          "country_pools": {
            "US": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "00920f38ce07c2e2f4df50b1f61d4194"
            ],
            "GB": [
              "abd90f38ced07c2e2f4df50b1f61d4194"
            ]
          },
          "random_steering": {
            "pool_weights": {
              "de90f38ced07c2e2f4df50b1f61d4194": 0.3,
              "9290f38c5d07c2e2f4df57b1f61d4196": 0.5
            },
            "default_weight": 0.2
          }
        },
        "priority": 55,
        "disabled": false,
        "terminates": false,
        "fixed_response": {
          "message_body": "Testing Hello",
          "status_code": 200,
          "content_type": "application/json",
          "location": "www.example.com"
        }
      }
    ]
  }
}

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" ]` An array with items in the following form: Show definition »
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`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. `"random"`: Select a pool randomly. `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). `"proximity"`: Use the pools' latitude and longitude to select the closest pool using the Cloudflare PoP location for proxied requests or the location determined by `location_strategy` for non-proxied requests. `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. `"dynamic_latency"`	default value: "" valid values: off, geo, random, dynamic_latency, proximity, ""
enabled boolean	Whether to enable (the default) this load balancer. `true`	default value: true valid values: (true,false)
session_affinity_attributes object	Configures cookie attributes for session affinity cookie. `{ "samesite": "Auto", "secure": "Auto", "drain_duration": 100, "zero_downtime_failover": "sticky" }` An object with the following properties: Show definition »
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 the corresponding country_pool, then region_pool mapping if it exists else to 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 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" ] }`
random_steering object	Configures pool weights for random steering. When steering_policy is 'random', a random pool is selected with probability proportional to these pool weights. `{ "pool_weights": { "de90f38ced07c2e2f4df50b1f61d4194": 0.3, "9290f38c5d07c2e2f4df57b1f61d4196": 0.5 }, "default_weight": 0.2 }` An object with the following properties: Show definition »
country_pools object	A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. `{ "US": [ "de90f38ced07c2e2f4df50b1f61d4194", "00920f38ce07c2e2f4df50b1f61d4194" ], "GB": [ "abd90f38ced07c2e2f4df50b1f61d4194" ] }`
session_affinity string	The session_affinity specifies the type of session affinity the load balancer 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, ""
rules array	BETA Field Not General Access: A list of rules for this load balancer to execute. [ { "name": "route the path /testing to testing datacenter.", "condition": "http.request.uri.path contains \"/testing\"", "overrides": { "session_affinity": "cookie", "session_affinity_ttl": 5000, "session_affinity_attributes": { "samesite": "Auto", "secure": "Auto", "drain_duration": 100, "zero_downtime_failover": "sticky" }, "adaptive_routing": { "failover_across_pools": true }, "location_strategy": { "prefer_ecs": "always", "mode": "resolver_ip" }, "ttl": 30, "steering_policy": "dynamic_latency", "fallback_pool": "17b5962d775c646f3f9725cbc7a53df4", "default_pools": [ "17b5962d775c646f3f9725cbc7a53df4", "9290f38c5d07c2e2f4df57b1f61d4196", "00920f38ce07c2e2f4df50b1f61d4194" ], "pop_pools": { "LAX": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "LHR": [ "abd90f38ced07c2e2f4df50b1f61d4194", "f9138c5d07c2e2f4df57b1f61d4196" ], "SJC": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }, "region_pools": { "WNAM": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "ENAM": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }, "country_pools": { "US": [ "de90f38ced07c2e2f4df50b1f61d4194", "00920f38ce07c2e2f4df50b1f61d4194" ], "GB": [ "abd90f38ced07c2e2f4df50b1f61d4194" ] }, "random_steering": { "pool_weights": { "de90f38ced07c2e2f4df50b1f61d4194": 0.3, "9290f38c5d07c2e2f4df57b1f61d4196": 0.5 }, "default_weight": 0.2 } }, "priority": 55, "disabled": false, "terminates": false, "fixed_response": { "message_body": "Testing Hello", "status_code": 200, "content_type": "application/json", "location": "www.example.com" } } ] An array with items in the following form: Show definition »
description string	Object description `"Load Balancer for www.example.com"`
location_strategy object	Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. `{ "prefer_ecs": "always", "mode": "resolver_ip" }` An object with the following properties: Show definition »
proxied boolean	Whether the hostname should be gray clouded (false) or orange clouded (true). `true`	default value: false valid values: (true,false)
adaptive_routing object	Controls features that modify the routing of requests to pools and origins in response to dynamic conditions, such as during the interval between active health monitoring requests. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. `{ "failover_across_pools": true }` An object with the following properties: Show definition »
session_affinity_ttl number	Time, in seconds, until this load balancer's 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: user@example.com" \
     -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"]},"country_pools":{"US":["de90f38ced07c2e2f4df50b1f61d4194","00920f38ce07c2e2f4df50b1f61d4194"],"GB":["abd90f38ced07c2e2f4df50b1f61d4194"]},"pop_pools":{"LAX":["de90f38ced07c2e2f4df50b1f61d4194","9290f38c5d07c2e2f4df57b1f61d4196"],"LHR":["abd90f38ced07c2e2f4df50b1f61d4194","f9138c5d07c2e2f4df57b1f61d4196"],"SJC":["00920f38ce07c2e2f4df50b1f61d4194"]},"proxied":true,"enabled":true,"steering_policy":"dynamic_latency","session_affinity":"cookie","session_affinity_attributes":{"samesite":"Auto","secure":"Auto","drain_duration":100,"zero_downtime_failover":"sticky"},"session_affinity_ttl":5000,"adaptive_routing":{"failover_across_pools":true},"location_strategy":{"prefer_ecs":"always","mode":"resolver_ip"},"random_steering":{"pool_weights":{"de90f38ced07c2e2f4df50b1f61d4194":0.3,"9290f38c5d07c2e2f4df57b1f61d4196":0.5},"default_weight":0.2},"rules":[{"name":"route the path /testing to testing datacenter.","condition":"http.request.uri.path contains \"/testing\"","overrides":{"session_affinity":"cookie","session_affinity_ttl":5000,"session_affinity_attributes":{"samesite":"Auto","secure":"Auto","drain_duration":100,"zero_downtime_failover":"sticky"},"adaptive_routing":{"failover_across_pools":true},"location_strategy":{"prefer_ecs":"always","mode":"resolver_ip"},"ttl":30,"steering_policy":"dynamic_latency","fallback_pool":"17b5962d775c646f3f9725cbc7a53df4","default_pools":["17b5962d775c646f3f9725cbc7a53df4","9290f38c5d07c2e2f4df57b1f61d4196","00920f38ce07c2e2f4df50b1f61d4194"],"pop_pools":{"LAX":["de90f38ced07c2e2f4df50b1f61d4194","9290f38c5d07c2e2f4df57b1f61d4196"],"LHR":["abd90f38ced07c2e2f4df50b1f61d4194","f9138c5d07c2e2f4df57b1f61d4196"],"SJC":["00920f38ce07c2e2f4df50b1f61d4194"]},"region_pools":{"WNAM":["de90f38ced07c2e2f4df50b1f61d4194","9290f38c5d07c2e2f4df57b1f61d4196"],"ENAM":["00920f38ce07c2e2f4df50b1f61d4194"]},"country_pools":{"US":["de90f38ced07c2e2f4df50b1f61d4194","00920f38ce07c2e2f4df50b1f61d4194"],"GB":["abd90f38ced07c2e2f4df50b1f61d4194"]},"random_steering":{"pool_weights":{"de90f38ced07c2e2f4df50b1f61d4194":0.3,"9290f38c5d07c2e2f4df57b1f61d4196":0.5},"default_weight":0.2}},"priority":55,"disabled":false,"terminates":false,"fixed_response":{"message_body":"Testing Hello","status_code":200,"content_type":"application/json","location":"www.example.com"}}]}'

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"
      ]
    },
    "country_pools": {
      "US": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "00920f38ce07c2e2f4df50b1f61d4194"
      ],
      "GB": [
        "abd90f38ced07c2e2f4df50b1f61d4194"
      ]
    },
    "pop_pools": {
      "LAX": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "9290f38c5d07c2e2f4df57b1f61d4196"
      ],
      "LHR": [
        "abd90f38ced07c2e2f4df50b1f61d4194",
        "f9138c5d07c2e2f4df57b1f61d4196"
      ],
      "SJC": [
        "00920f38ce07c2e2f4df50b1f61d4194"
      ]
    },
    "proxied": true,
    "steering_policy": "dynamic_latency",
    "session_affinity": "cookie",
    "session_affinity_attributes": {
      "samesite": "Auto",
      "secure": "Auto",
      "drain_duration": 100,
      "zero_downtime_failover": "sticky"
    },
    "session_affinity_ttl": 5000,
    "adaptive_routing": {
      "failover_across_pools": true
    },
    "location_strategy": {
      "prefer_ecs": "always",
      "mode": "resolver_ip"
    },
    "random_steering": {
      "pool_weights": {
        "de90f38ced07c2e2f4df50b1f61d4194": 0.3,
        "9290f38c5d07c2e2f4df57b1f61d4196": 0.5
      },
      "default_weight": 0.2
    },
    "rules": [
      {
        "name": "route the path /testing to testing datacenter.",
        "condition": "http.request.uri.path contains \"/testing\"",
        "overrides": {
          "session_affinity": "cookie",
          "session_affinity_ttl": 5000,
          "session_affinity_attributes": {
            "samesite": "Auto",
            "secure": "Auto",
            "drain_duration": 100,
            "zero_downtime_failover": "sticky"
          },
          "adaptive_routing": {
            "failover_across_pools": true
          },
          "location_strategy": {
            "prefer_ecs": "always",
            "mode": "resolver_ip"
          },
          "ttl": 30,
          "steering_policy": "dynamic_latency",
          "fallback_pool": "17b5962d775c646f3f9725cbc7a53df4",
          "default_pools": [
            "17b5962d775c646f3f9725cbc7a53df4",
            "9290f38c5d07c2e2f4df57b1f61d4196",
            "00920f38ce07c2e2f4df50b1f61d4194"
          ],
          "pop_pools": {
            "LAX": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "9290f38c5d07c2e2f4df57b1f61d4196"
            ],
            "LHR": [
              "abd90f38ced07c2e2f4df50b1f61d4194",
              "f9138c5d07c2e2f4df57b1f61d4196"
            ],
            "SJC": [
              "00920f38ce07c2e2f4df50b1f61d4194"
            ]
          },
          "region_pools": {
            "WNAM": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "9290f38c5d07c2e2f4df57b1f61d4196"
            ],
            "ENAM": [
              "00920f38ce07c2e2f4df50b1f61d4194"
            ]
          },
          "country_pools": {
            "US": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "00920f38ce07c2e2f4df50b1f61d4194"
            ],
            "GB": [
              "abd90f38ced07c2e2f4df50b1f61d4194"
            ]
          },
          "random_steering": {
            "pool_weights": {
              "de90f38ced07c2e2f4df50b1f61d4194": 0.3,
              "9290f38c5d07c2e2f4df57b1f61d4196": 0.5
            },
            "default_weight": 0.2
          }
        },
        "priority": 55,
        "disabled": false,
        "terminates": false,
        "fixed_response": {
          "message_body": "Testing Hello",
          "status_code": 200,
          "content_type": "application/json",
          "location": "www.example.com"
        }
      }
    ]
  }
}

load-balancers-patch-load-balancer

PATCH Patch Load Balancer

Apply changes to an existing load balancer, overwriting the supplied properties.

PATCH zones/:identifier/load_balancers/:identifier

Optional parameters

Name /type	Description /example	Constraints
steering_policy string	Steering Policy for this load balancer. `"off"`: Use `default_pools`. `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. `"random"`: Select a pool randomly. `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). `"proximity"`: Use the pools' latitude and longitude to select the closest pool using the Cloudflare PoP location for proxied requests or the location determined by `location_strategy` for non-proxied requests. `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. `"dynamic_latency"`	default value: "" valid values: off, geo, random, dynamic_latency, proximity, ""
enabled boolean	Whether to enable (the default) this load balancer. `true`	default value: true valid values: (true,false)
session_affinity_attributes object	Configures cookie attributes for session affinity cookie. `{ "samesite": "Auto", "secure": "Auto", "drain_duration": 100, "zero_downtime_failover": "sticky" }` An object with the following properties: Show definition »
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 the corresponding country_pool, then region_pool mapping if it exists else to default_pools. `{ "LAX": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "LHR": [ "abd90f38ced07c2e2f4df50b1f61d4194", "f9138c5d07c2e2f4df57b1f61d4196" ], "SJC": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }`
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"`
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 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" ] }`
random_steering object	Configures pool weights for random steering. When steering_policy is 'random', a random pool is selected with probability proportional to these pool weights. `{ "pool_weights": { "de90f38ced07c2e2f4df50b1f61d4194": 0.3, "9290f38c5d07c2e2f4df57b1f61d4196": 0.5 }, "default_weight": 0.2 }` An object with the following properties: Show definition »
country_pools object	A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. `{ "US": [ "de90f38ced07c2e2f4df50b1f61d4194", "00920f38ce07c2e2f4df50b1f61d4194" ], "GB": [ "abd90f38ced07c2e2f4df50b1f61d4194" ] }`
session_affinity string	The session_affinity specifies the type of session affinity the load balancer 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, ""
rules array	BETA Field Not General Access: A list of rules for this load balancer to execute. [ { "name": "route the path /testing to testing datacenter.", "condition": "http.request.uri.path contains \"/testing\"", "overrides": { "session_affinity": "cookie", "session_affinity_ttl": 5000, "session_affinity_attributes": { "samesite": "Auto", "secure": "Auto", "drain_duration": 100, "zero_downtime_failover": "sticky" }, "adaptive_routing": { "failover_across_pools": true }, "location_strategy": { "prefer_ecs": "always", "mode": "resolver_ip" }, "ttl": 30, "steering_policy": "dynamic_latency", "fallback_pool": "17b5962d775c646f3f9725cbc7a53df4", "default_pools": [ "17b5962d775c646f3f9725cbc7a53df4", "9290f38c5d07c2e2f4df57b1f61d4196", "00920f38ce07c2e2f4df50b1f61d4194" ], "pop_pools": { "LAX": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "LHR": [ "abd90f38ced07c2e2f4df50b1f61d4194", "f9138c5d07c2e2f4df57b1f61d4196" ], "SJC": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }, "region_pools": { "WNAM": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "ENAM": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }, "country_pools": { "US": [ "de90f38ced07c2e2f4df50b1f61d4194", "00920f38ce07c2e2f4df50b1f61d4194" ], "GB": [ "abd90f38ced07c2e2f4df50b1f61d4194" ] }, "random_steering": { "pool_weights": { "de90f38ced07c2e2f4df50b1f61d4194": 0.3, "9290f38c5d07c2e2f4df57b1f61d4196": 0.5 }, "default_weight": 0.2 } }, "priority": 55, "disabled": false, "terminates": false, "fixed_response": { "message_body": "Testing Hello", "status_code": 200, "content_type": "application/json", "location": "www.example.com" } } ] An array with items in the following form: Show definition »
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" ]` An array with items in the following form: Show definition »
fallback_pool string	The pool ID to use when all other pools are detected as unhealthy. `"17b5962d775c646f3f9725cbc7a53df4"`	max length: 32 read only
description string	Object description `"Load Balancer for www.example.com"`
location_strategy object	Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. `{ "prefer_ecs": "always", "mode": "resolver_ip" }` An object with the following properties: Show definition »
proxied boolean	Whether the hostname should be gray clouded (false) or orange clouded (true). `true`	default value: false valid values: (true,false)
adaptive_routing object	Controls features that modify the routing of requests to pools and origins in response to dynamic conditions, such as during the interval between active health monitoring requests. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. `{ "failover_across_pools": true }` An object with the following properties: Show definition »
session_affinity_ttl number	Time, in seconds, until this load balancer's 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 PATCH "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/load_balancers/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -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"]},"country_pools":{"US":["de90f38ced07c2e2f4df50b1f61d4194","00920f38ce07c2e2f4df50b1f61d4194"],"GB":["abd90f38ced07c2e2f4df50b1f61d4194"]},"pop_pools":{"LAX":["de90f38ced07c2e2f4df50b1f61d4194","9290f38c5d07c2e2f4df57b1f61d4196"],"LHR":["abd90f38ced07c2e2f4df50b1f61d4194","f9138c5d07c2e2f4df57b1f61d4196"],"SJC":["00920f38ce07c2e2f4df50b1f61d4194"]},"proxied":true,"enabled":true,"steering_policy":"dynamic_latency","session_affinity":"cookie","session_affinity_attributes":{"samesite":"Auto","secure":"Auto","drain_duration":100,"zero_downtime_failover":"sticky"},"session_affinity_ttl":5000,"adaptive_routing":{"failover_across_pools":true},"location_strategy":{"prefer_ecs":"always","mode":"resolver_ip"},"random_steering":{"pool_weights":{"de90f38ced07c2e2f4df50b1f61d4194":0.3,"9290f38c5d07c2e2f4df57b1f61d4196":0.5},"default_weight":0.2},"rules":[{"name":"route the path /testing to testing datacenter.","condition":"http.request.uri.path contains \"/testing\"","overrides":{"session_affinity":"cookie","session_affinity_ttl":5000,"session_affinity_attributes":{"samesite":"Auto","secure":"Auto","drain_duration":100,"zero_downtime_failover":"sticky"},"adaptive_routing":{"failover_across_pools":true},"location_strategy":{"prefer_ecs":"always","mode":"resolver_ip"},"ttl":30,"steering_policy":"dynamic_latency","fallback_pool":"17b5962d775c646f3f9725cbc7a53df4","default_pools":["17b5962d775c646f3f9725cbc7a53df4","9290f38c5d07c2e2f4df57b1f61d4196","00920f38ce07c2e2f4df50b1f61d4194"],"pop_pools":{"LAX":["de90f38ced07c2e2f4df50b1f61d4194","9290f38c5d07c2e2f4df57b1f61d4196"],"LHR":["abd90f38ced07c2e2f4df50b1f61d4194","f9138c5d07c2e2f4df57b1f61d4196"],"SJC":["00920f38ce07c2e2f4df50b1f61d4194"]},"region_pools":{"WNAM":["de90f38ced07c2e2f4df50b1f61d4194","9290f38c5d07c2e2f4df57b1f61d4196"],"ENAM":["00920f38ce07c2e2f4df50b1f61d4194"]},"country_pools":{"US":["de90f38ced07c2e2f4df50b1f61d4194","00920f38ce07c2e2f4df50b1f61d4194"],"GB":["abd90f38ced07c2e2f4df50b1f61d4194"]},"random_steering":{"pool_weights":{"de90f38ced07c2e2f4df50b1f61d4194":0.3,"9290f38c5d07c2e2f4df57b1f61d4196":0.5},"default_weight":0.2}},"priority":55,"disabled":false,"terminates":false,"fixed_response":{"message_body":"Testing Hello","status_code":200,"content_type":"application/json","location":"www.example.com"}}]}'

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"
      ]
    },
    "country_pools": {
      "US": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "00920f38ce07c2e2f4df50b1f61d4194"
      ],
      "GB": [
        "abd90f38ced07c2e2f4df50b1f61d4194"
      ]
    },
    "pop_pools": {
      "LAX": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "9290f38c5d07c2e2f4df57b1f61d4196"
      ],
      "LHR": [
        "abd90f38ced07c2e2f4df50b1f61d4194",
        "f9138c5d07c2e2f4df57b1f61d4196"
      ],
      "SJC": [
        "00920f38ce07c2e2f4df50b1f61d4194"
      ]
    },
    "proxied": true,
    "steering_policy": "dynamic_latency",
    "session_affinity": "cookie",
    "session_affinity_attributes": {
      "samesite": "Auto",
      "secure": "Auto",
      "drain_duration": 100,
      "zero_downtime_failover": "sticky"
    },
    "session_affinity_ttl": 5000,
    "adaptive_routing": {
      "failover_across_pools": true
    },
    "location_strategy": {
      "prefer_ecs": "always",
      "mode": "resolver_ip"
    },
    "random_steering": {
      "pool_weights": {
        "de90f38ced07c2e2f4df50b1f61d4194": 0.3,
        "9290f38c5d07c2e2f4df57b1f61d4196": 0.5
      },
      "default_weight": 0.2
    },
    "rules": [
      {
        "name": "route the path /testing to testing datacenter.",
        "condition": "http.request.uri.path contains \"/testing\"",
        "overrides": {
          "session_affinity": "cookie",
          "session_affinity_ttl": 5000,
          "session_affinity_attributes": {
            "samesite": "Auto",
            "secure": "Auto",
            "drain_duration": 100,
            "zero_downtime_failover": "sticky"
          },
          "adaptive_routing": {
            "failover_across_pools": true
          },
          "location_strategy": {
            "prefer_ecs": "always",
            "mode": "resolver_ip"
          },
          "ttl": 30,
          "steering_policy": "dynamic_latency",
          "fallback_pool": "17b5962d775c646f3f9725cbc7a53df4",
          "default_pools": [
            "17b5962d775c646f3f9725cbc7a53df4",
            "9290f38c5d07c2e2f4df57b1f61d4196",
            "00920f38ce07c2e2f4df50b1f61d4194"
          ],
          "pop_pools": {
            "LAX": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "9290f38c5d07c2e2f4df57b1f61d4196"
            ],
            "LHR": [
              "abd90f38ced07c2e2f4df50b1f61d4194",
              "f9138c5d07c2e2f4df57b1f61d4196"
            ],
            "SJC": [
              "00920f38ce07c2e2f4df50b1f61d4194"
            ]
          },
          "region_pools": {
            "WNAM": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "9290f38c5d07c2e2f4df57b1f61d4196"
            ],
            "ENAM": [
              "00920f38ce07c2e2f4df50b1f61d4194"
            ]
          },
          "country_pools": {
            "US": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "00920f38ce07c2e2f4df50b1f61d4194"
            ],
            "GB": [
              "abd90f38ced07c2e2f4df50b1f61d4194"
            ]
          },
          "random_steering": {
            "pool_weights": {
              "de90f38ced07c2e2f4df50b1f61d4194": 0.3,
              "9290f38c5d07c2e2f4df57b1f61d4196": 0.5
            },
            "default_weight": 0.2
          }
        },
        "priority": 55,
        "disabled": false,
        "terminates": false,
        "fixed_response": {
          "message_body": "Testing Hello",
          "status_code": 200,
          "content_type": "application/json",
          "location": "www.example.com"
        }
      }
    ]
  }
}

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

IP Address Management Prefixes

Describe and modify the account's IP prefixes.

ip-address-management-prefixes

Object definition

View properties and constraints defined on the object

Show definition

ip-address-management-prefixes-list-prefixes

GET List Prefixes

List all prefixes owned by the account.

GET accounts/:account_identifier/addressing/prefixes

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/addressing/prefixes" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "9a7806061c88ada191ed06f989cc3dac",
      "created_at": "2014-01-01T05:20:00.12345Z",
      "modified_at": "2014-01-01T05:20:00.12345Z",
      "cidr": "192.0.2.0/24",
      "account_id": "01a7362d577a6c3019a474fd6f485823",
      "description": "Internal test prefix",
      "approved": "P",
      "loa_document_id": "d933b1530bc56c9953cf8ce166da8004",
      "on_demand_enabled": true,
      "on_demand_locked": false,
      "advertised": true,
      "advertised_modified_at": "2014-01-01T05:20:00.12345Z",
      "asn": 13335
    }
  ]
}

ip-address-management-prefixes-add-prefix

POST Add Prefix

Add a prefix under the account.

POST accounts/:account_identifier/addressing/prefixes

Required parameters

Name /type	Description /example	Constraints
cidr string	IP Prefix in Classless Inter-Domain Routing format `"192.0.2.0/24"`
loa_document_id stringnull	Identifier for the uploaded LOA document `"d933b1530bc56c9953cf8ce166da8004"`	max length: 32 read only

Optional parameters

Name /type	Description /example	Constraints
asn integernull	Autonomous System Number (ASN) the prefix will be advertised under `13335`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/addressing/prefixes" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"cidr":"192.0.2.0/24","loa_document_id":"d933b1530bc56c9953cf8ce166da8004","asn":13335}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "modified_at": "2014-01-01T05:20:00.12345Z",
    "cidr": "192.0.2.0/24",
    "account_id": "01a7362d577a6c3019a474fd6f485823",
    "description": "Internal test prefix",
    "approved": "P",
    "loa_document_id": "d933b1530bc56c9953cf8ce166da8004",
    "on_demand_enabled": true,
    "on_demand_locked": false,
    "advertised": true,
    "advertised_modified_at": "2014-01-01T05:20:00.12345Z",
    "asn": 13335
  }
}

ip-address-management-prefixes-prefix-details

GET Prefix Details

List a particular prefix owned by the account.

GET accounts/:account_identifier/addressing/prefixes/:prefix_identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/addressing/prefixes/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "modified_at": "2014-01-01T05:20:00.12345Z",
    "cidr": "192.0.2.0/24",
    "account_id": "01a7362d577a6c3019a474fd6f485823",
    "description": "Internal test prefix",
    "approved": "P",
    "loa_document_id": "d933b1530bc56c9953cf8ce166da8004",
    "on_demand_enabled": true,
    "on_demand_locked": false,
    "advertised": true,
    "advertised_modified_at": "2014-01-01T05:20:00.12345Z",
    "asn": 13335
  }
}

ip-address-management-prefixes-delete-prefix

DELETE Delete Prefix

Delete an unapproved prefix owned by the account.

DELETE accounts/:account_identifier/addressing/prefixes/:prefix_identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/addressing/prefixes/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

ip-address-management-prefixes-update-prefix-description

PATCH Update Prefix Description

Modify the description for a prefix owned by the account.

PATCH accounts/:account_identifier/addressing/prefixes/:prefix_identifier

Required parameters

Name /type	Description /example	Constraints
description string	Description of the prefix `"Internal test prefix"`	max length: 1000

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/addressing/prefixes/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"Internal test prefix"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "modified_at": "2014-01-01T05:20:00.12345Z",
    "cidr": "192.0.2.0/24",
    "account_id": "01a7362d577a6c3019a474fd6f485823",
    "description": "Internal test prefix",
    "approved": "P",
    "loa_document_id": "d933b1530bc56c9953cf8ce166da8004",
    "on_demand_enabled": true,
    "on_demand_locked": false,
    "advertised": true,
    "advertised_modified_at": "2014-01-01T05:20:00.12345Z",
    "asn": 13335
  }
}

ip-address-management-prefixes-upload-loa-document

POST Upload LOA Document

Submit LOA document (pdf format) under the account.

POST accounts/:account_identifier/addressing/loa_documents

Required parameters

Name /type	Description /example	Constraints
loa_document string	LOA document to upload `"@document.pdf"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/addressing/loa_documents" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     --form 'loa_document=@document.pdf'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "filename": "document.pdf"
  }
}

ip-address-management-prefixes-download-loa-document

GET Download LOA Document

Download specified LOA document under the account.

GET accounts/:account_identifier/addressing/loa_documents/:loa_document_identifier/download

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/addressing/loa_documents/d933b1530bc56c9953cf8ce166da8004/download" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{}

IP Address Management Dynamic Advertisement

Manage the desired advertisement state of your account's IP prefixes.

ip-address-management-dynamic-advertisement

Object definition

View properties and constraints defined on the object

Show definition

ip-address-management-dynamic-advertisement-get-advertisement-status

GET Get Advertisement Status

List the current advertisement state for a prefix.

GET accounts/:account_identifier/addressing/prefixes/:prefix_identifier/bgp/status

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/addressing/prefixes/9a7806061c88ada191ed06f989cc3dac/bgp/status" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "advertised": true,
    "advertised_modified_at": "2014-01-01T05:20:00.12345Z"
  }
}

ip-address-management-dynamic-advertisement-update-prefix-dynamic-advertisement-status

PATCH Update Prefix Dynamic Advertisement Status

Advertise or withdraw BGP route for a prefix.

PATCH accounts/:account_identifier/addressing/prefixes/:prefix_identifier/bgp/status

Required parameters

Name /type	Description /example	Constraints
advertised boolean	Enablement of prefix advertisement to the Internet. `true`	valid values: (true,false)

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/addressing/prefixes/9a7806061c88ada191ed06f989cc3dac/bgp/status" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"advertised":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "advertised": true,
    "advertised_modified_at": "2014-01-01T05:20:00.12345Z"
  }
}

IP Address Management Prefix Delegation

Describe and modify delegations for the account's IP prefixes.

ip-address-management-prefix-delegation

Object definition

View properties and constraints defined on the object

Show definition

ip-address-management-prefix-delegation-list-prefix-delegations

GET List Prefix Delegations

List all delegations for a given account IP prefix.

GET accounts/:account_identifier/addressing/prefixes/:prefix_identifier/delegations

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/addressing/prefixes/9a7806061c88ada191ed06f989cc3dac/delegations" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "d933b1530bc56c9953cf8ce166da8004",
      "created_at": "2014-01-01T05:20:00.12345Z",
      "modified_at": "2014-01-01T05:20:00.12345Z",
      "cidr": "192.0.2.0/24",
      "delegated_account_id": "b1946ac92492d2347c6235b4d2611184",
      "parent_prefix_id": "9a7806061c88ada191ed06f989cc3dac"
    }
  ]
}

ip-address-management-prefix-delegation-create-prefix-delegation

POST Create Prefix Delegation

Create a new account delegation for a given IP prefix.

POST accounts/:account_identifier/addressing/prefixes/:prefix_identifier/delegations

Required parameters

Name /type	Description /example	Constraints
cidr string	IP Prefix in Classless Inter-Domain Routing format `"192.0.2.0/24"`
delegated_account_id string	Account identifier for the account to which prefix is being delegated `"b1946ac92492d2347c6235b4d2611184"`	max length: 32 read only

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/addressing/prefixes/9a7806061c88ada191ed06f989cc3dac/delegations" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"cidr":"192.0.2.0/24","delegated_account_id":"b1946ac92492d2347c6235b4d2611184"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "d933b1530bc56c9953cf8ce166da8004",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "modified_at": "2014-01-01T05:20:00.12345Z",
    "cidr": "192.0.2.0/24",
    "delegated_account_id": "b1946ac92492d2347c6235b4d2611184",
    "parent_prefix_id": "9a7806061c88ada191ed06f989cc3dac"
  }
}

ip-address-management-prefix-delegation-delete-prefix-delegation

DELETE Delete Prefix Delegation

Delete an account delegation for a given IP prefix.

DELETE accounts/:account_identifier/addressing/prefixes/:prefix_identifier/delegations/:delegation_identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/addressing/prefixes/9a7806061c88ada191ed06f989cc3dac/delegations/d933b1530bc56c9953cf8ce166da8004" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Railgun

Cloudflare Railgun is a WAN optimization technology developed by Cloudflare. It is available to Cloudflare Business and Enterprise customers, as well as Optimized Partners.

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	Sort Railguns in ascending or descending order. `"desc"`	valid values: asc, desc

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/railguns?page=1&per_page=20&direction=desc" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "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"
    }
  ]
}

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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"enabled":true}'

Response (example)

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

railgun-delete-a-railgun

DELETE Delete a Railgun
free
pro
business
enterprise

Disable and delete a Railgun. This will immediately disable that 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: user@example.com" \
     -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

List 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: user@example.com" \
     -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"
    }
  ]
}

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: user@example.com" \
     -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-railgun-details

GET Railgun details permission needed: #zone_settings:read
free
pro
business
enterprise

Lists 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: user@example.com" \
     -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: user@example.com" \
     -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

Tests the 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "method": "GET",
    "host_name": "www.example.com",
    "http_status": 200,
    "railgun": "on",
    "url": "https://www.cloudflare.com",
    "response_status": "200 OK",
    "protocol": "HTTP/1.1",
    "elapsed_time": "0.239013s",
    "body_size": "63910 bytes",
    "body_hash": "be27f2429421e12f200cab1da43ba301bdc70e1d",
    "missing_headers": "No Content-Length or Transfer-Encoding.",
    "connection_close": false,
    "cloudflare": "on",
    "cf-ray": "1ddd7570575207d9-LAX",
    "cf-wan-error": null,
    "cf-cache-status": null
  }
}

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	Sort Railguns in ascending or descending order. `"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: user@example.com" \
     -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"
        }
      }
    }
  ]
}

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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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-a-railgun

DELETE Delete a 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: user@example.com" \
     -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: user@example.com" \
     -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-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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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: user@example.com" \
     -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

Please use equivalent /accounts API endpoints. Account APIs provide a broader range of features and are backwards-compatible to organization APIs.

organization-railgun

Object definition

View properties and constraints defined on the object

Show definition

Deprecation Warning

End of life Date: February 4, 2020

This endpoint and its related APIs are deprecated in favor of the `/accounts` equivalent APIs, which have a broader range of features and are backwards compatible with these API.

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	Sort Railguns in ascending or descending order. `"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: user@example.com" \
     -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"
    }
  ]
}

Deprecation Warning

End of life Date: February 4, 2020

This endpoint and its related APIs are deprecated in favor of the `/accounts` equivalent APIs, which have a broader range of features and are backwards compatible with these API.

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"My Railgun."}'

Response (example)

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

Deprecation Warning

End of life Date: February 4, 2020

This endpoint and its related APIs are deprecated in favor of the `/accounts` equivalent APIs, which have a broader range of features and are backwards compatible with these API.

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Deprecation Warning

End of life Date: February 4, 2020

This endpoint and its related APIs are deprecated in favor of the `/accounts` equivalent APIs, which have a broader range of features and are backwards compatible with these API.

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"enabled":true}'

Response (example)

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

Deprecation Warning

End of life Date: February 4, 2020

This endpoint and its related APIs are deprecated in favor of the `/accounts` equivalent APIs, which have a broader range of features and are backwards compatible with these API.

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Deprecation Warning

End of life Date: February 4, 2020

This endpoint and its related APIs are deprecated in favor of the `/accounts` equivalent APIs, which have a broader range of features and are backwards compatible with these API.

organization-railgun-get-railgun-zones

GET Get Railgun zones
free
pro
business
enterprise

Lists 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: user@example.com" \
     -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"
    }
  ]
}

Custom pages for an account

Custom pages configuration at the account level.

custom-pages-for-an-account

Object definitions

View properties and constraints defined on the object

Show definitions

custom-pages-for-an-account-get-custom-pages

GET Get custom pages permission needed: #organization:read
free
pro
business
enterprise

Fetches all the custom pages at the account level.

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: user@example.com" \
     -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-an-account-get-a-custom-page

GET Get a custom page permission needed: #organization:read
free
pro
business
enterprise

Fetches the details of a custom page.

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: user@example.com" \
     -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-an-account-update-a-custom-page

PUT Update a custom page permission needed: #organization:edit
free
pro
business
enterprise

Updates the configuration of an existing custom page.

PUT accounts/:account_identifier/custom_pages/:identifier

Required parameters

Name /type	Description /example	Constraints
url string (url)	The URL 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: user@example.com" \
     -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 an 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

Zero Trust organization

A Zero Trust organization defines the user login experience.

zero-trust-organization

Object definition

View properties and constraints defined on the object

Show definition

zero-trust-organization-get-your-zero-trust-organization

GET Get your Zero Trust organization

Returns the configuration for your Zero Trust organization.

GET accounts/:identifier/access/organizations

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/organizations" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "name": "Widget Corps Internal Applications",
    "auth_domain": "test.cloudflareaccess.com",
    "login_design": {
      "background_color": "#c5ed1b",
      "text_color": "#c5ed1b",
      "logo_path": "https://example.com/logo.png",
      "header_text": "This is an example description.",
      "footer_text": "This is an example description."
    }
  }
}

zero-trust-organization-create-your-zero-trust-organization

POST Create your Zero Trust organization

Sets up a Zero Trust organization for your account.

POST accounts/:identifier/access/organizations

Required parameters

Name /type	Description /example	Constraints
name string	The name of your Zero Trust organization. `"Widget Corps Internal Applications"`
auth_domain string	The unique subdomain assigned to your Zero Trust organization. `"test.cloudflareaccess.com"`

Optional parameters

Name /type	Description /example	Constraints
login_design	`{ "background_color": "#c5ed1b", "text_color": "#c5ed1b", "logo_path": "https://example.com/logo.png", "header_text": "This is an example description.", "footer_text": "This is an example description." }` An object with the following properties: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/organizations" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Widget Corps Internal Applications","auth_domain":"test.cloudflareaccess.com","login_design":{"background_color":"#c5ed1b","text_color":"#c5ed1b","logo_path":"https://example.com/logo.png","header_text":"This is an example description.","footer_text":"This is an example description."}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "name": "Widget Corps Internal Applications",
    "auth_domain": "test.cloudflareaccess.com",
    "login_design": {
      "background_color": "#c5ed1b",
      "text_color": "#c5ed1b",
      "logo_path": "https://example.com/logo.png",
      "header_text": "This is an example description.",
      "footer_text": "This is an example description."
    }
  }
}

zero-trust-organization-update-your-zero-trust-organization

PUT Update your Zero Trust organization

Updates the configuration for your Zero Trust organization.

PUT accounts/:identifier/access/organizations

Optional parameters

Name /type	Description /example	Constraints
name string	The name of your Zero Trust organization. `"Widget Corps Internal Applications"`
auth_domain string	The unique subdomain assigned to your Zero Trust organization. `"test.cloudflareaccess.com"`
login_design	`{ "background_color": "#c5ed1b", "text_color": "#c5ed1b", "logo_path": "https://example.com/logo.png", "header_text": "This is an example description.", "footer_text": "This is an example description." }` An object with the following properties: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/organizations" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Widget Corps Internal Applications","auth_domain":"test.cloudflareaccess.com","login_design":{"background_color":"#c5ed1b","text_color":"#c5ed1b","logo_path":"https://example.com/logo.png","header_text":"This is an example description.","footer_text":"This is an example description."}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "name": "Widget Corps Internal Applications",
    "auth_domain": "test.cloudflareaccess.com",
    "login_design": {
      "background_color": "#c5ed1b",
      "text_color": "#c5ed1b",
      "logo_path": "https://example.com/logo.png",
      "header_text": "This is an example description.",
      "footer_text": "This is an example description."
    }
  }
}

zero-trust-organization-revoke-all-access-tokens-for-a-user

POST Revoke all Access tokens for a user

Revokes a user's access across all applications.

POST accounts/:identifier/access/organizations/revoke_user

Required parameters

Name /type	Description /example	Constraints
email string	The email of the user to revoke. `"test@example.com"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/organizations/revoke_user" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"email":"test@example.com"}'

Response (example)

{
  "success": true,
  "result": true
}

Access identity providers

Identity providers are services that authenticate users to Access applications.

https://developers.cloudflare.com/cloudflare-one/identity/idp-integration/

access-identity-providers

Object definition

View properties and constraints defined on the object

Show definition

access-identity-providers-list-access-identity-providers

GET List Access identity providers

Lists all configured identity providers.

GET accounts/:identifier/access/identity_providers

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/identity_providers" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "name": "Widget Corps OTP",
      "type": "onetimepin",
      "config": {}
    }
  ]
}

access-identity-providers-get-an-access-identity-provider

GET Get an Access identity provider

Fetches a configured identity provider.

GET accounts/:identifier/access/identity_providers/:uuid

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/identity_providers/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "Widget Corps OTP",
    "type": "onetimepin",
    "config": {}
  }
}

access-identity-providers-add-an-access-identity-provider

POST Add an Access identity provider

Adds a new identity provider to Access.

POST accounts/:identifier/access/identity_providers

Required parameters

Name /type	Description /example	Constraints
name string	The name of the identity provider, shown to users on the login page. `"Widget Corps OTP"`
type string	The type of identity provider. To determine the value for a specific provider, refer to our developer documentation. `"onetimepin"`
config object	The configuration parameters for the identity provider. To view the required parameters for a specific provider, refer to our developer documentation. `{}` An object with the following properties: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/identity_providers" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Widget Corps OTP","type":"onetimepin","config":{}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "Widget Corps OTP",
    "type": "onetimepin",
    "config": {}
  }
}

access-identity-providers-update-an-access-identity-provider

PUT Update an Access identity provider

Updates a configured identity provider.

PUT accounts/:identifier/access/identity_providers/:uuid

Required parameters

Name /type	Description /example	Constraints
name string	The name of the identity provider, shown to users on the login page. `"Widget Corps OTP"`
type string	The type of identity provider. To determine the value for a specific provider, refer to our developer documentation. `"onetimepin"`
config object	The configuration parameters for the identity provider. To view the required parameters for a specific provider, refer to our developer documentation. `{}` An object with the following properties: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/identity_providers/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Widget Corps OTP","type":"onetimepin","config":{}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "Widget Corps OTP",
    "type": "onetimepin",
    "config": {}
  }
}

access-identity-providers-delete-an-access-identity-provider

DELETE Delete an Access identity provider

Deletes an identity provider from Access.

DELETE accounts/:identifier/access/identity_providers/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/identity_providers/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "Widget Corps OTP",
    "type": "onetimepin",
    "config": {}
  }
}

Access groups

An Access group is a set of reusable rules that can be quickly applied across many Access policies.

https://developers.cloudflare.com/cloudflare-one/identity/users/groups/

access-groups

Object definition

View properties and constraints defined on the object

Show definition

access-groups-list-access-groups

GET List Access groups

Lists all Access groups.

GET accounts/:identifier/access/groups

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/access/groups" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z",
      "name": "Allow devs",
      "include": [
        {
          "email": {
            "email": "test@example.com"
          }
        }
      ],
      "exclude": [
        {
          "email": {
            "email": "test@example.com"
          }
        }
      ],
      "require": [
        {
          "email": {
            "email": "test@example.com"
          }
        }
      ]
    }
  ]
}

access-groups-get-an-access-group

GET Get an Access group

Fetches a single Access group.

GET accounts/:identifier/access/groups/:uuid

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/access/groups/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "name": "Allow devs",
    "include": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "exclude": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "require": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ]
  }
}

access-groups-create-an-access-group

POST Create an Access group

Creates a new Access group.

POST accounts/:identifier/access/groups

Required parameters

Name /type	Description /example	Constraints
name string	The name of the Access group. `"Allow devs"`
include array	Rules evaluated with an OR logical operator. A user needs to meet only one of the Include rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
exclude array	Rules evaluated with a NOT logical operator. To match a policy, a user cannot meet any of the Exclude rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »
require array	Rules evaluated with an AND logical operator. To match a policy, a user must meet all of the Require rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/access/groups" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Allow devs","include":[{"email":{"email":"test@example.com"}}],"exclude":[{"email":{"email":"test@example.com"}}],"require":[{"email":{"email":"test@example.com"}}]}'

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",
    "name": "Allow devs",
    "include": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "exclude": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "require": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ]
  }
}

access-groups-update-an-access-group

PUT Update an Access group

Updates a configured Access group.

PUT accounts/:identifier/access/groups/:uuid

Required parameters

Name /type	Description /example	Constraints
name string	The name of the Access group. `"Allow devs"`
include array	Rules evaluated with an OR logical operator. A user needs to meet only one of the Include rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
exclude array	Rules evaluated with a NOT logical operator. To match a policy, a user cannot meet any of the Exclude rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »
require array	Rules evaluated with an AND logical operator. To match a policy, a user must meet all of the Require rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/access/groups/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Allow devs","include":[{"email":{"email":"test@example.com"}}],"exclude":[{"email":{"email":"test@example.com"}}],"require":[{"email":{"email":"test@example.com"}}]}'

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",
    "name": "Allow devs",
    "include": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "exclude": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "require": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ]
  }
}

access-groups-delete-an-access-group

DELETE Delete an Access group

Deletes an Access group.

DELETE accounts/:identifier/access/groups/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/access/groups/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
  }
}

Access service tokens

Service tokens allow automated requests to reach applications protected by Access.

https://developers.cloudflare.com/cloudflare-one/identity/service-tokens/

access-service-tokens

Object definition

View properties and constraints defined on the object

Show definition

access-service-tokens-list-service-tokens

GET List service tokens

Lists all service tokens.

GET accounts/:identifier/access/service_tokens

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/access/service_tokens" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z",
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "name": "CI/CD token",
      "client_id": "88bf3b6d86161464f6509f7219099e57.access.example.com"
    }
  ]
}

access-service-tokens-create-a-service-token

POST Create a service token

Generates a new service token. Note: This is the only time you can get the Client Secret. If you lose the Client Secret, you will have to create a new service token.

POST accounts/:identifier/access/service_tokens

Required parameters

Name /type	Description /example	Constraints
name string	The name of the service token. `"CI/CD token"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/access/service_tokens" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"CI/CD token"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "CI/CD token",
    "client_id": "88bf3b6d86161464f6509f7219099e57.access.example.com",
    "client_secret": "bdd31cbc4dec990953e39163fbbb194c93313ca9f0a6e420346af9d326b1d2a5"
  }
}

access-service-tokens-update-a-service-token

PUT Update a service token

Updates a configured service token.

PUT accounts/:identifier/access/service_tokens/:uuid

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the service token. `"CI/CD token"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/access/service_tokens/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"CI/CD token"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "CI/CD token",
    "client_id": "88bf3b6d86161464f6509f7219099e57.access.example.com"
  }
}

access-service-tokens-delete-a-service-token

DELETE Delete a service token

Deletes a service token.

DELETE accounts/:identifier/access/service_tokens/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/access/service_tokens/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "CI/CD token",
    "client_id": "88bf3b6d86161464f6509f7219099e57.access.example.com"
  }
}

access-service-tokens-refresh-a-service-token

POST Refresh a service token

Refreshes the expiration of a service token

POST accounts/:identifier/access/service_tokens/:uuid/refresh

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/access/service_tokens/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/refresh" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "CI/CD token",
    "client_id": "88bf3b6d86161464f6509f7219099e57.access.example.com"
  }
}

Access short-lived certificate CAs

The certificate authority (CA) issues short-lived certificates during an SSH session. Clients authenticate to the SSH server with ephemeral certificates instead of traditional SSH keys.

https://developers.cloudflare.com/cloudflare-one/identity/users/short-lived-certificates/

access-short-lived-certificate-cas

Object definition

View properties and constraints defined on the object

Show definition

access-short-lived-certificate-cas-list-short-lived-certificate-cas

GET List short-lived certificate CAs

Lists short-lived certificate CAs and their public keys.

GET accounts/:identifier/access/apps/ca

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/access/apps/ca" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "7eddae4619b50ab1361ba8ae9bd72269a432fea041529ed9",
      "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893",
      "public_key": "ecdsa-sha2-nistp256 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx= open-ssh-ca@cloudflareaccess.org"
    }
  ]
}

access-short-lived-certificate-cas-get-a-short-lived-certificate-ca

GET Get a short-lived certificate CA

Fetches a short-lived certificate CA and its public key.

GET accounts/:identifier/access/apps/:uuid/ca

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/ca" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

access-short-lived-certificate-cas-create-a-short-lived-certificate-ca

POST Create a short-lived certificate CA

Generates a new short-lived certificate CA and public key.

POST accounts/:identifier/access/apps/:uuid/ca

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/ca" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

access-short-lived-certificate-cas-delete-a-short-lived-certificate-ca

DELETE Delete a short-lived certificate CA

Deletes a short-lived certificate CA.

DELETE accounts/:identifier/access/apps/:uuid/ca

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/ca" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Access mTLS authentication

Mutual TLS (mTLS) authentication establishes trust between a client and server via a shared certificate.

https://developers.cloudflare.com/cloudflare-one/identity/devices/mutual-tls-authentication/

access-mtls-authentication

Object definition

View properties and constraints defined on the object

Show definition

access-mtls-authentication-list-mtls-certificates

GET List mTLS certificates

Lists all mTLS certificates.

GET accounts/:identifier/access/certificates

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/access/certificates" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z",
      "expires_on": "2014-01-01T05:20:00.12345Z",
      "name": "Allow devs",
      "fingerprint": "MD5 Fingerprint=1E:80:0F:7A:FD:31:55:96:DE:D5:CB:E2:F0:91:F6:91",
      "associated_hostnames": [
        "admin.example.com"
      ]
    }
  ]
}

access-mtls-authentication-get-an-mtls-certificate

GET Get an mTLS certificate

Fetches a single mTLS certificate.

GET accounts/:identifier/access/certificates/:uuid

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/access/certificates/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "expires_on": "2014-01-01T05:20:00.12345Z",
    "name": "Allow devs",
    "fingerprint": "MD5 Fingerprint=1E:80:0F:7A:FD:31:55:96:DE:D5:CB:E2:F0:91:F6:91",
    "associated_hostnames": [
      "admin.example.com"
    ]
  }
}

access-mtls-authentication-add-an-mtls-certificate

POST Add an mTLS certificate

Adds a new mTLS root certificate to Access.

POST accounts/:identifier/access/certificates

Required parameters

Name /type	Description /example	Constraints
name string	The name of the certificate. `"Allow devs"`
certificate string	The certificate content. `"-----BEGIN CERTIFICATE-----\nMIIGAjCCA+qgAwIBAgIJAI7kymlF7CWT...N4RI7KKB7nikiuUf8vhULKy5IX10\nDrUtmu/B\n-----END CERTIFICATE-----"`

Optional parameters

Name /type	Description /example	Constraints
associated_hostnames array	The hostnames of the applications that will use this certificate. `[ "admin.example.com" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/access/certificates" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Allow devs","certificate":"-----BEGIN CERTIFICATE-----\nMIIGAjCCA+qgAwIBAgIJAI7kymlF7CWT...N4RI7KKB7nikiuUf8vhULKy5IX10\nDrUtmu/B\n-----END CERTIFICATE-----","associated_hostnames":["admin.example.com"]}'

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",
    "expires_on": "2014-01-01T05:20:00.12345Z",
    "name": "Allow devs",
    "fingerprint": "MD5 Fingerprint=1E:80:0F:7A:FD:31:55:96:DE:D5:CB:E2:F0:91:F6:91",
    "associated_hostnames": [
      "admin.example.com"
    ]
  }
}

access-mtls-authentication-update-an-mtls-certificate

PUT Update an mTLS certificate

Updates a configured mTLS certificate.

PUT accounts/:identifier/access/certificates/:uuid

Required parameters

Name /type	Description /example	Constraints
name string	The name of the certificate. `"Allow devs"`
associated_hostnames array	The hostnames of the applications that will use this certificate. `[ "admin.example.com" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/access/certificates/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Allow devs","associated_hostnames":["admin.example.com"]}'

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",
    "expires_on": "2014-01-01T05:20:00.12345Z",
    "name": "Allow devs",
    "fingerprint": "MD5 Fingerprint=1E:80:0F:7A:FD:31:55:96:DE:D5:CB:E2:F0:91:F6:91",
    "associated_hostnames": [
      "admin.example.com"
    ]
  }
}

access-mtls-authentication-delete-an-mtls-certificate

DELETE Delete an mTLS certificate

Deletes an mTLS certificate.

DELETE accounts/:identifier/access/certificates/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/access/certificates/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
  }
}

Access applications

Applications secured behind Cloudflare Access.

access-applications

Object definitions

View properties and constraints defined on the object

Show definitions

access-applications-list-access-applications

GET List Access applications

Lists all Access applications in an account.

GET accounts/:identifier/access/apps

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z",
      "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893",
      "type": "self_hosted",
      "name": "Admin Site",
      "domain": "test.example.com/admin",
      "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
      "app_launcher_visible": true,
      "session_duration": "24h",
      "allowed_idps": [
        "699d98642c564d2e855e9661899b7252"
      ],
      "auto_redirect_to_identity": false,
      "enable_binding_cookie": false,
      "http_only_cookie_attribute": true,
      "same_site_cookie_attribute": "strict",
      "cors_headers": {
        "allowed_methods": [
          "GET"
        ],
        "allowed_origins": [
          "https://example.com"
        ],
        "allow_all_headers": true,
        "max_age": -1
      },
      "skip_interstitial": true,
      "service_auth_401_redirect": true
    }
  ]
}

access-applications-get-an-access-application

GET Get an Access application

Fetches information about an Access application.

GET accounts/:identifier/access/apps/:app_id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893",
    "type": "self_hosted",
    "name": "Admin Site",
    "domain": "test.example.com/admin",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "enable_binding_cookie": false,
    "http_only_cookie_attribute": true,
    "same_site_cookie_attribute": "strict",
    "cors_headers": {
      "allowed_methods": [
        "GET"
      ],
      "allowed_origins": [
        "https://example.com"
      ],
      "allow_all_headers": true,
      "max_age": -1
    },
    "skip_interstitial": true,
    "service_auth_401_redirect": true
  }
}

access-applications-add-a-self-hosted-application

POST Add a self-hosted application

Adds a self-hosted application to Access.

POST accounts/:identifier/access/apps

Required parameters

Name /type	Description /example	Constraints
domain string	The domain and path that Access will secure. `"test.example.com/admin"`
name string	The name of the application. `"Admin Site"`
type string	The application type. `"self_hosted"`

Optional parameters

Name /type	Description /example	Constraints
same_site_cookie_attribute string	Sets the SameSite cookie setting, which provides increased security against CSRF attacks. `"strict"`
custom_deny_message string	The custom error message shown to a user when they are denied access to the application.
custom_deny_url string	The custom URL a user is redirected to when they are denied access to the application.
skip_interstitial boolean	Enables automatic authentication through cloudflared. `true`	valid values: (true,false)
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)
service_auth_401_redirect boolean	Returns a 401 status code when the request is blocked by a Service Auth policy. `true`	valid values: (true,false)
cors_headers object	`{ "allowed_methods": [ "GET" ], "allowed_origins": [ "https://example.com" ], "allow_all_headers": true, "max_age": -1 }` An object with the following properties: Show definition »
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
enable_binding_cookie boolean	Enables the binding cookie, which increases security against compromised authorization tokens and CSRF attacks. `false`	default value: false valid values: (true,false)
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
http_only_cookie_attribute boolean	Enables the HttpOnly cookie attribute, which increases security against XSS attacks. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"self_hosted","name":"Admin Site","domain":"test.example.com/admin","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true,"session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false,"enable_binding_cookie":false,"http_only_cookie_attribute":true,"same_site_cookie_attribute":"strict","cors_headers":{"allowed_methods":["GET"],"allowed_origins":["https://example.com"],"allow_all_headers":true,"max_age":-1},"skip_interstitial":true,"service_auth_401_redirect":true}'

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",
    "type": "self_hosted",
    "name": "Admin Site",
    "domain": "test.example.com/admin",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "enable_binding_cookie": false,
    "http_only_cookie_attribute": true,
    "same_site_cookie_attribute": "strict",
    "cors_headers": {
      "allowed_methods": [
        "GET"
      ],
      "allowed_origins": [
        "https://example.com"
      ],
      "allow_all_headers": true,
      "max_age": -1
    },
    "skip_interstitial": true,
    "service_auth_401_redirect": true
  }
}

access-applications-add-an-ssh-application

POST Add an SSH application

Adds a new SSH application to Access. The SSH terminal will render in the user's browser.

POST accounts/:identifier/access/apps

Required parameters

Name /type	Description /example	Constraints
domain string	The domain and path that Access will secure. `"test.example.com/admin"`
name string	The name of the application. `"Admin Site"`
type string	The application type `"ssh"`

Optional parameters

Name /type	Description /example	Constraints
same_site_cookie_attribute string	Sets the SameSite cookie setting, which provides increased security against CSRF attacks. `"strict"`
custom_deny_message string	The custom error message shown to a user when they are denied access to the application.
custom_deny_url string	The custom URL a user is redirected to when they are denied access to the application.
skip_interstitial boolean	Enables automatic authentication through cloudflared. `true`	valid values: (true,false)
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)
service_auth_401_redirect boolean	Returns a 401 status code when the request is blocked by a Service Auth policy. `true`	valid values: (true,false)
cors_headers object	`{ "allowed_methods": [ "GET" ], "allowed_origins": [ "https://example.com" ], "allow_all_headers": true, "max_age": -1 }` An object with the following properties: Show definition »
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
enable_binding_cookie boolean	Enables the binding cookie, which increases security against compromised authorization tokens and CSRF attacks. `false`	default value: false valid values: (true,false)
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
http_only_cookie_attribute boolean	Enables the HttpOnly cookie attribute, which increases security against XSS attacks. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"ssh","name":"Admin Site","domain":"test.example.com/admin","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true,"session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false,"enable_binding_cookie":false,"http_only_cookie_attribute":true,"same_site_cookie_attribute":"strict","cors_headers":{"allowed_methods":["GET"],"allowed_origins":["https://example.com"],"allow_all_headers":true,"max_age":-1},"skip_interstitial":true,"service_auth_401_redirect":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "ssh",
    "name": "Admin Site",
    "domain": "test.example.com/admin",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "enable_binding_cookie": false,
    "http_only_cookie_attribute": true,
    "same_site_cookie_attribute": "strict",
    "cors_headers": {
      "allowed_methods": [
        "GET"
      ],
      "allowed_origins": [
        "https://example.com"
      ],
      "allow_all_headers": true,
      "max_age": -1
    },
    "skip_interstitial": true,
    "service_auth_401_redirect": true,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

access-applications-add-a-vnc-application

POST Add a VNC application

Adds a new VNC application to Access. The VNC terminal will render in the user's browser.

POST accounts/:identifier/access/apps

Required parameters

Name /type	Description /example	Constraints
domain string	The domain and path that Access will secure. `"test.example.com/admin"`
name string	The name of the application. `"Admin Site"`
type string	The application type `"vnc"`

Optional parameters

Name /type	Description /example	Constraints
same_site_cookie_attribute string	Sets the SameSite cookie setting, which provides increased security against CSRF attacks. `"strict"`
custom_deny_message string	The custom error message shown to a user when they are denied access to the application.
custom_deny_url string	The custom URL a user is redirected to when they are denied access to the application.
skip_interstitial boolean	Enables automatic authentication through cloudflared. `true`	valid values: (true,false)
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)
service_auth_401_redirect boolean	Returns a 401 status code when the request is blocked by a Service Auth policy. `true`	valid values: (true,false)
cors_headers object	`{ "allowed_methods": [ "GET" ], "allowed_origins": [ "https://example.com" ], "allow_all_headers": true, "max_age": -1 }` An object with the following properties: Show definition »
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
enable_binding_cookie boolean	Enables the binding cookie, which increases security against compromised authorization tokens and CSRF attacks. `false`	default value: false valid values: (true,false)
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
http_only_cookie_attribute boolean	Enables the HttpOnly cookie attribute, which increases security against XSS attacks. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"vnc","name":"Admin Site","domain":"test.example.com/admin","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true,"session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false,"enable_binding_cookie":false,"http_only_cookie_attribute":true,"same_site_cookie_attribute":"strict","cors_headers":{"allowed_methods":["GET"],"allowed_origins":["https://example.com"],"allow_all_headers":true,"max_age":-1},"skip_interstitial":true,"service_auth_401_redirect":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "vnc",
    "name": "Admin Site",
    "domain": "test.example.com/admin",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "enable_binding_cookie": false,
    "http_only_cookie_attribute": true,
    "same_site_cookie_attribute": "strict",
    "cors_headers": {
      "allowed_methods": [
        "GET"
      ],
      "allowed_origins": [
        "https://example.com"
      ],
      "allow_all_headers": true,
      "max_age": -1
    },
    "skip_interstitial": true,
    "service_auth_401_redirect": true,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

access-applications-add-a-saas-application

POST Add a SaaS application

Adds a new SaaS application to Access.

POST accounts/:identifier/access/apps

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"saas"`
name string	The name of the application. `"Admin Site"`
saas_app object	{ "consumer_service_url": "https://example.com", "sp_entity_id": "example unique name", "public_key": "example unique name", "idp_entity_id": "https://example.cloudflareaccess.com", "name_id_format": "id", "sso_endpoint": "https://example.cloudflareaccess.com/cdn-cgi/access/sso/saml/b3f58a2b414e0b51d45c8c2af26fccca0e27c63763c426fa52f98dcf0b3b3bfd", "custom_attributes": { "name": "family_name", "name_format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic", "source": { "name": "last_name" } }, "created_at": "2014-01-01T05:20:00.12345Z", "updated_at": "2014-01-01T05:20:00.12345Z" } An object with the following properties: Show definition »

Optional parameters

Name /type	Description /example	Constraints
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"saas","name":"Admin Site","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true,"saas_app":{"consumer_service_url":"https://example.com","sp_entity_id":"example unique name","public_key":"example unique name","idp_entity_id":"https://example.cloudflareaccess.com","name_id_format":"id","sso_endpoint":"https://example.cloudflareaccess.com/cdn-cgi/access/sso/saml/b3f58a2b414e0b51d45c8c2af26fccca0e27c63763c426fa52f98dcf0b3b3bfd","custom_attributes":{"name":"family_name","name_format":"urn:oasis:names:tc:SAML:2.0:attrname-format:basic","source":{"name":"last_name"}},"created_at":"2014-01-01T05:20:00.12345Z","updated_at":"2014-01-01T05:20:00.12345Z"},"allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false}'

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",
    "type": "saas",
    "name": "Admin Site",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "saas_app": {
      "consumer_service_url": "https://example.com",
      "sp_entity_id": "example unique name",
      "public_key": "example unique name",
      "idp_entity_id": "https://example.cloudflareaccess.com",
      "name_id_format": "id",
      "sso_endpoint": "https://example.cloudflareaccess.com/cdn-cgi/access/sso/saml/b3f58a2b414e0b51d45c8c2af26fccca0e27c63763c426fa52f98dcf0b3b3bfd",
      "custom_attributes": {
        "name": "family_name",
        "name_format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
        "source": {
          "name": "last_name"
        }
      },
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z"
    },
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false
  }
}

access-applications-add-the-access-app-launcher

POST Add the Access App Launcher

Adds the App Launcher application to Access, allowing you to define which users can access the App Launcher portal.

POST accounts/:identifier/access/apps

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"app_launcher"`	valid values: self_hosted, saas, ssh, vnc, app_launcher, warp, biso, bookmark, dash_sso

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the application. `"App Launcher"`	default value: App Launcher read only
domain string	The domain and path that Access will secure. `"authdomain.cloudflareaccess.com"`	read only
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"app_launcher","name":"App Launcher","domain":"authdomain.cloudflareaccess.com","session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "app_launcher",
    "name": "App Launcher",
    "domain": "authdomain.cloudflareaccess.com",
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

POST Add the WARP login application

Adds the WARP login application to Access, allowing you to define which users can enroll devices.

POST accounts/:identifier/access/apps

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"warp"`	valid values: self_hosted, saas, ssh, vnc, app_launcher, warp, biso, bookmark, dash_sso

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the application. `"Warp Login App"`	default value: Warp Login App read only
domain string	The domain and path that Access will secure. `"authdomain.cloudflareaccess.com/warp"`	read only
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"warp","name":"Warp Login App","domain":"authdomain.cloudflareaccess.com/warp","session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "warp",
    "name": "Warp Login App",
    "domain": "authdomain.cloudflareaccess.com/warp",
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

access-applications-add-the-clientless-web-isolation-application

POST Add the Clientless Web Isolation application

Adds the Clientless Web Isolation application to Access, allowing you to define which users can access the clientless remote browser.

POST accounts/:identifier/access/apps

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"biso"`	valid values: self_hosted, saas, ssh, vnc, app_launcher, warp, biso, bookmark, dash_sso

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the application. `"Clientless Web Isolation"`	default value: Clientless Web Isolation read only
domain string	The domain and path that Access will secure. `"authdomain.cloudflareaccess.com/browser"`	read only
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"biso","name":"Clientless Web Isolation","domain":"authdomain.cloudflareaccess.com/browser","session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "biso",
    "name": "Clientless Web Isolation",
    "domain": "authdomain.cloudflareaccess.com/browser",
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

access-applications-add-a-bookmark-application

POST Add a Bookmark application

Adds a custom link to the App Launcher. Bookmark applications are not protected by Access.

POST accounts/:identifier/access/apps

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"bookmark"`
name string	The name of the application. `"Admin Site"`
domain string	The URL or domain of the bookmark. `"https://mybookmark.com"`

Optional parameters

Name /type	Description /example	Constraints
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"bookmark","name":"Admin Site","domain":"https://mybookmark.com","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true}'

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",
    "type": "bookmark",
    "name": "Admin Site",
    "domain": "https://mybookmark.com",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true
  }
}

access-applications-update-a-self-hosted-application

PUT Update a self-hosted application

Updates the configuration for a self-hosted Access application.

PUT accounts/:identifier/access/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
domain string	The domain and path that Access will secure. `"test.example.com/admin"`
name string	The name of the application. `"Admin Site"`
type string	The application type. `"self_hosted"`

Optional parameters

Name /type	Description /example	Constraints
same_site_cookie_attribute string	Sets the SameSite cookie setting, which provides increased security against CSRF attacks. `"strict"`
custom_deny_message string	The custom error message shown to a user when they are denied access to the application.
custom_deny_url string	The custom URL a user is redirected to when they are denied access to the application.
skip_interstitial boolean	Enables automatic authentication through cloudflared. `true`	valid values: (true,false)
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)
service_auth_401_redirect boolean	Returns a 401 status code when the request is blocked by a Service Auth policy. `true`	valid values: (true,false)
cors_headers object	`{ "allowed_methods": [ "GET" ], "allowed_origins": [ "https://example.com" ], "allow_all_headers": true, "max_age": -1 }` An object with the following properties: Show definition »
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
enable_binding_cookie boolean	Enables the binding cookie, which increases security against compromised authorization tokens and CSRF attacks. `false`	default value: false valid values: (true,false)
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
http_only_cookie_attribute boolean	Enables the HttpOnly cookie attribute, which increases security against XSS attacks. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"self_hosted","name":"Admin Site","domain":"test.example.com/admin","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true,"session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false,"enable_binding_cookie":false,"http_only_cookie_attribute":true,"same_site_cookie_attribute":"strict","cors_headers":{"allowed_methods":["GET"],"allowed_origins":["https://example.com"],"allow_all_headers":true,"max_age":-1},"skip_interstitial":true,"service_auth_401_redirect":true}'

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",
    "type": "self_hosted",
    "name": "Admin Site",
    "domain": "test.example.com/admin",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "enable_binding_cookie": false,
    "http_only_cookie_attribute": true,
    "same_site_cookie_attribute": "strict",
    "cors_headers": {
      "allowed_methods": [
        "GET"
      ],
      "allowed_origins": [
        "https://example.com"
      ],
      "allow_all_headers": true,
      "max_age": -1
    },
    "skip_interstitial": true,
    "service_auth_401_redirect": true
  }
}

access-applications-update-an-ssh-application

PUT Update an SSH application

Updates the configuration for an SSH Access application.

PUT accounts/:identifier/access/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
domain string	The domain and path that Access will secure. `"test.example.com/admin"`
name string	The name of the application. `"Admin Site"`
type string	The application type `"ssh"`

Optional parameters

Name /type	Description /example	Constraints
same_site_cookie_attribute string	Sets the SameSite cookie setting, which provides increased security against CSRF attacks. `"strict"`
custom_deny_message string	The custom error message shown to a user when they are denied access to the application.
custom_deny_url string	The custom URL a user is redirected to when they are denied access to the application.
skip_interstitial boolean	Enables automatic authentication through cloudflared. `true`	valid values: (true,false)
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)
service_auth_401_redirect boolean	Returns a 401 status code when the request is blocked by a Service Auth policy. `true`	valid values: (true,false)
cors_headers object	`{ "allowed_methods": [ "GET" ], "allowed_origins": [ "https://example.com" ], "allow_all_headers": true, "max_age": -1 }` An object with the following properties: Show definition »
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
enable_binding_cookie boolean	Enables the binding cookie, which increases security against compromised authorization tokens and CSRF attacks. `false`	default value: false valid values: (true,false)
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
http_only_cookie_attribute boolean	Enables the HttpOnly cookie attribute, which increases security against XSS attacks. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"ssh","name":"Admin Site","domain":"test.example.com/admin","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true,"session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false,"enable_binding_cookie":false,"http_only_cookie_attribute":true,"same_site_cookie_attribute":"strict","cors_headers":{"allowed_methods":["GET"],"allowed_origins":["https://example.com"],"allow_all_headers":true,"max_age":-1},"skip_interstitial":true,"service_auth_401_redirect":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "ssh",
    "name": "Admin Site",
    "domain": "test.example.com/admin",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "enable_binding_cookie": false,
    "http_only_cookie_attribute": true,
    "same_site_cookie_attribute": "strict",
    "cors_headers": {
      "allowed_methods": [
        "GET"
      ],
      "allowed_origins": [
        "https://example.com"
      ],
      "allow_all_headers": true,
      "max_age": -1
    },
    "skip_interstitial": true,
    "service_auth_401_redirect": true,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

access-applications-update-a-vnc-application

PUT Update a VNC application

Updates the configuration for a VNC Access application.

PUT accounts/:identifier/access/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
domain string	The domain and path that Access will secure. `"test.example.com/admin"`
name string	The name of the application. `"Admin Site"`
type string	The application type `"vnc"`

Optional parameters

Name /type	Description /example	Constraints
same_site_cookie_attribute string	Sets the SameSite cookie setting, which provides increased security against CSRF attacks. `"strict"`
custom_deny_message string	The custom error message shown to a user when they are denied access to the application.
custom_deny_url string	The custom URL a user is redirected to when they are denied access to the application.
skip_interstitial boolean	Enables automatic authentication through cloudflared. `true`	valid values: (true,false)
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)
service_auth_401_redirect boolean	Returns a 401 status code when the request is blocked by a Service Auth policy. `true`	valid values: (true,false)
cors_headers object	`{ "allowed_methods": [ "GET" ], "allowed_origins": [ "https://example.com" ], "allow_all_headers": true, "max_age": -1 }` An object with the following properties: Show definition »
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
enable_binding_cookie boolean	Enables the binding cookie, which increases security against compromised authorization tokens and CSRF attacks. `false`	default value: false valid values: (true,false)
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
http_only_cookie_attribute boolean	Enables the HttpOnly cookie attribute, which increases security against XSS attacks. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"vnc","name":"Admin Site","domain":"test.example.com/admin","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true,"session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false,"enable_binding_cookie":false,"http_only_cookie_attribute":true,"same_site_cookie_attribute":"strict","cors_headers":{"allowed_methods":["GET"],"allowed_origins":["https://example.com"],"allow_all_headers":true,"max_age":-1},"skip_interstitial":true,"service_auth_401_redirect":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "vnc",
    "name": "Admin Site",
    "domain": "test.example.com/admin",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "enable_binding_cookie": false,
    "http_only_cookie_attribute": true,
    "same_site_cookie_attribute": "strict",
    "cors_headers": {
      "allowed_methods": [
        "GET"
      ],
      "allowed_origins": [
        "https://example.com"
      ],
      "allow_all_headers": true,
      "max_age": -1
    },
    "skip_interstitial": true,
    "service_auth_401_redirect": true,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

access-applications-update-a-saas-application

PUT Update a SaaS application

Updates the configuration for a SaaS Access application.

PUT accounts/:identifier/access/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"saas"`
name string	The name of the application. `"Admin Site"`
saas_app object	{ "consumer_service_url": "https://example.com", "sp_entity_id": "example unique name", "public_key": "example unique name", "idp_entity_id": "https://example.cloudflareaccess.com", "name_id_format": "id", "sso_endpoint": "https://example.cloudflareaccess.com/cdn-cgi/access/sso/saml/b3f58a2b414e0b51d45c8c2af26fccca0e27c63763c426fa52f98dcf0b3b3bfd", "custom_attributes": { "name": "family_name", "name_format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic", "source": { "name": "last_name" } }, "created_at": "2014-01-01T05:20:00.12345Z", "updated_at": "2014-01-01T05:20:00.12345Z" } An object with the following properties: Show definition »

Optional parameters

Name /type	Description /example	Constraints
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"saas","name":"Admin Site","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true,"saas_app":{"consumer_service_url":"https://example.com","sp_entity_id":"example unique name","public_key":"example unique name","idp_entity_id":"https://example.cloudflareaccess.com","name_id_format":"id","sso_endpoint":"https://example.cloudflareaccess.com/cdn-cgi/access/sso/saml/b3f58a2b414e0b51d45c8c2af26fccca0e27c63763c426fa52f98dcf0b3b3bfd","custom_attributes":{"name":"family_name","name_format":"urn:oasis:names:tc:SAML:2.0:attrname-format:basic","source":{"name":"last_name"}},"created_at":"2014-01-01T05:20:00.12345Z","updated_at":"2014-01-01T05:20:00.12345Z"},"allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false}'

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",
    "type": "saas",
    "name": "Admin Site",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "saas_app": {
      "consumer_service_url": "https://example.com",
      "sp_entity_id": "example unique name",
      "public_key": "example unique name",
      "idp_entity_id": "https://example.cloudflareaccess.com",
      "name_id_format": "id",
      "sso_endpoint": "https://example.cloudflareaccess.com/cdn-cgi/access/sso/saml/b3f58a2b414e0b51d45c8c2af26fccca0e27c63763c426fa52f98dcf0b3b3bfd",
      "custom_attributes": {
        "name": "family_name",
        "name_format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
        "source": {
          "name": "last_name"
        }
      },
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z"
    },
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false
  }
}

access-applications-update-the-dashboard-sso-application

PUT Update the Dashboard SSO application

Updates the Cloudflare Dashboard SSO application.

PUT accounts/:identifier/access/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"dash_sso"`
saas_app object	`{ "name_id_format": "id" }` An object with the following properties: Show definition »

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the application. `"Admin Site"`
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"dash_sso","name":"Admin Site","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true,"allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false,"session_duration":"24h","saas_app":{"name_id_format":"id"}}'

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",
    "type": "dash_sso",
    "name": "Admin Site",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "session_duration": "24h",
    "saas_app": {
      "name_id_format": "id"
    }
  }
}

access-applications-update-the-access-app-launcher

PUT Update the Access App Launcher

Updates the App Launcher portal.

PUT accounts/:identifier/access/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"app_launcher"`	valid values: self_hosted, saas, ssh, vnc, app_launcher, warp, biso, bookmark, dash_sso

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the application. `"App Launcher"`	default value: App Launcher read only
domain string	The domain and path that Access will secure. `"authdomain.cloudflareaccess.com"`	read only
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"app_launcher","name":"App Launcher","domain":"authdomain.cloudflareaccess.com","session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "app_launcher",
    "name": "App Launcher",
    "domain": "authdomain.cloudflareaccess.com",
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

PUT Update the WARP login application

Updates the WARP device enrollment application.

PUT accounts/:identifier/access/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"warp"`	valid values: self_hosted, saas, ssh, vnc, app_launcher, warp, biso, bookmark, dash_sso

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the application. `"Warp Login App"`	default value: Warp Login App read only
domain string	The domain and path that Access will secure. `"authdomain.cloudflareaccess.com/warp"`	read only
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"warp","name":"Warp Login App","domain":"authdomain.cloudflareaccess.com/warp","session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "warp",
    "name": "Warp Login App",
    "domain": "authdomain.cloudflareaccess.com/warp",
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

access-applications-update-the-clientless-web-isolation-application

PUT Update the Clientless Web Isolation application

Updates the Clientless Web Isolation application.

PUT accounts/:identifier/access/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"biso"`	valid values: self_hosted, saas, ssh, vnc, app_launcher, warp, biso, bookmark, dash_sso

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the application. `"Clientless Web Isolation"`	default value: Clientless Web Isolation read only
domain string	The domain and path that Access will secure. `"authdomain.cloudflareaccess.com/browser"`	read only
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"biso","name":"Clientless Web Isolation","domain":"authdomain.cloudflareaccess.com/browser","session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "biso",
    "name": "Clientless Web Isolation",
    "domain": "authdomain.cloudflareaccess.com/browser",
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

access-applications-update-a-bookmark-application

PUT Update a Bookmark application

Updates a Bookmark application.

PUT accounts/:identifier/access/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"bookmark"`
name string	The name of the application. `"Admin Site"`
domain string	The URL or domain of the bookmark. `"https://mybookmark.com"`

Optional parameters

Name /type	Description /example	Constraints
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"bookmark","name":"Admin Site","domain":"https://mybookmark.com","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true}'

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",
    "type": "bookmark",
    "name": "Admin Site",
    "domain": "https://mybookmark.com",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true
  }
}

access-applications-delete-an-access-application

DELETE Delete an Access application

Deletes an application from Access.

DELETE accounts/:identifier/access/apps/:app_id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
  }
}

access-applications-revoke-service-tokens

POST Revoke service tokens

Revokes all service tokens used by an application.

POST accounts/:identifier/access/apps/:app_id/revoke_tokens

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252/revoke_tokens" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true
}

access-applications-test-access-policies

GET Test Access policies

Tests if a specific user has permission to access an application.

GET accounts/:identifier/access/apps/:app_id/user_policy_checks

Required parameters

Name /type	Description /example	Constraints
user_id string	The ID of the user that you want to test with. `"f174e90a-fafe-4643-bbbc-4a0ed4fc8415"`	max length: 36 read only

Optional parameters

Name /type	Description /example	Constraints
ray_id string	The unique identifier for a failed login attempt. The user identity attributes from the request will be added to the test. `"6d76a8a42ead4133"`	read only
user_email string	The email of the user that you want to test with. `"test@email.com"`	read only

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252/user_policy_checks?user_id=f174e90a-fafe-4643-bbbc-4a0ed4fc8415&ray_id=6d76a8a42ead4133&user_email=test@email.com" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "user_identity": {
      "id": "1164449231815010287495",
      "version": 0,
      "user_uuid": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "name": "Test User",
      "email": "testuser@gmail.com",
      "geo": {
        "country": "US"
      },
      "is_warp": false,
      "is_gateway": false,
      "account_id": "41ecfbb341f033e52b46742756aabb8b",
      "device_sessions": {}
    },
    "app_state": {
      "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe389",
      "app_uid": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "hostname": "test.com",
      "name": "Test App",
      "policies": [
        {
          "decision": "allow",
          "include": [
            {
              "_type": "email",
              "email": "testuser@gmail.com"
            }
          ],
          "exclude": [],
          "require": [],
          "precedence": 0,
          "status": "Success"
        }
      ],
      "status": "Success"
    }
  }
}

Access policies

Access policies define the users or groups who can reach an Access application.

https://developers.cloudflare.com/access/setting-up-access/configuring-access-policies/

access-policies

Object definition

View properties and constraints defined on the object

Show definition

access-policies-list-access-policies

GET List Access policies

Lists Access policies configured for an application.

GET accounts/:identifier/access/apps/:uuid/policies

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/policies" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "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": "test@example.com"
          }
        }
      ],
      "exclude": [
        {
          "email": {
            "email": "test@example.com"
          }
        }
      ],
      "require": [
        {
          "email": {
            "email": "test@example.com"
          }
        }
      ],
      "purpose_justification_required": true,
      "purpose_justification_prompt": "Please enter a justification for entering this protected domain.",
      "approval_required": true,
      "approval_groups": [
        {
          "email_addresses": [
            "test1@cloudflare.com",
            "test2@cloudflare.com"
          ],
          "approvals_needed": 1
        },
        {
          "email_list_uuid": "597147a1-976b-4ef2-9af0-81d5d007fc34",
          "approvals_needed": 3
        }
      ]
    }
  ]
}

access-policies-get-an-access-policy

GET Get an Access policy

Fetches a single Access policy.

GET accounts/:identifier/access/apps/:uuid/policies/:uuid

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/policies/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "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": "test@example.com"
        }
      }
    ],
    "exclude": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "require": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "purpose_justification_required": true,
    "purpose_justification_prompt": "Please enter a justification for entering this protected domain.",
    "approval_required": true,
    "approval_groups": [
      {
        "email_addresses": [
          "test1@cloudflare.com",
          "test2@cloudflare.com"
        ],
        "approvals_needed": 1
      },
      {
        "email_list_uuid": "597147a1-976b-4ef2-9af0-81d5d007fc34",
        "approvals_needed": 3
      }
    ]
  }
}

access-policies-create-an-access-policy

POST Create an Access policy

Create a new Access policy for an application.

POST accounts/:identifier/access/apps/:uuid/policies

Required parameters

Name /type	Description /example	Constraints
include array	Rules evaluated with an OR logical operator. A user needs to meet only one of the Include rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »
name string	The name of the Access policy. `"Allow devs"`
decision string	The action Access will take if a user matches this policy. `"allow"`	valid values: allow, deny, non_identity, bypass

Optional parameters

Name /type	Description /example	Constraints
require array	Rules evaluated with an AND logical operator. To match the policy, a user must meet all of the Require rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »
precedence integer	The order of execution for this policy. Must be unique for each policy. `1`
purpose_justification_required boolean	Require users to enter a justification when they log in to the application. `true`	default value: false valid values: (true,false)
approval_groups array	Administrators who can approve a temporary authentication request. `[ { "email_addresses": [ "test1@cloudflare.com", "test2@cloudflare.com" ], "approvals_needed": 1 }, { "email_list_uuid": "597147a1-976b-4ef2-9af0-81d5d007fc34", "approvals_needed": 3 } ]` An array with items in the following form: Show definition »
purpose_justification_prompt string	A custom message that will appear on the purpose justification screen. `"Please enter a justification for entering this protected domain."`
exclude array	Rules evaluated with a NOT logical operator. To match the policy, a user cannot meet any of the Exclude rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »
approval_required boolean	Requires the user to request access from an administrator at the start of each session. `true`	default value: false valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/policies" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"precedence":1,"decision":"allow","name":"Allow devs","include":[{"email":{"email":"test@example.com"}}],"exclude":[{"email":{"email":"test@example.com"}}],"require":[{"email":{"email":"test@example.com"}}],"purpose_justification_required":true,"purpose_justification_prompt":"Please enter a justification for entering this protected domain.","approval_required":true,"approval_groups":[{"email_addresses":["test1@cloudflare.com","test2@cloudflare.com"],"approvals_needed":1},{"email_list_uuid":"597147a1-976b-4ef2-9af0-81d5d007fc34","approvals_needed":3}]}'

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": "test@example.com"
        }
      }
    ],
    "exclude": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "require": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "purpose_justification_required": true,
    "purpose_justification_prompt": "Please enter a justification for entering this protected domain.",
    "approval_required": true,
    "approval_groups": [
      {
        "email_addresses": [
          "test1@cloudflare.com",
          "test2@cloudflare.com"
        ],
        "approvals_needed": 1
      },
      {
        "email_list_uuid": "597147a1-976b-4ef2-9af0-81d5d007fc34",
        "approvals_needed": 3
      }
    ]
  }
}

access-policies-update-an-access-policy

PUT Update an Access policy

Update a configured Access policy.

PUT accounts/:identifier/access/apps/:uuid/policies/:uuid

Required parameters

Name /type	Description /example	Constraints
include array	Rules evaluated with an OR logical operator. A user needs to meet only one of the Include rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »
name string	The name of the Access policy. `"Allow devs"`
decision string	The action Access will take if a user matches this policy. `"allow"`	valid values: allow, deny, non_identity, bypass

Optional parameters

Name /type	Description /example	Constraints
require array	Rules evaluated with an AND logical operator. To match the policy, a user must meet all of the Require rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »
precedence integer	The order of execution for this policy. Must be unique for each policy. `1`
purpose_justification_required boolean	Require users to enter a justification when they log in to the application. `true`	default value: false valid values: (true,false)
approval_groups array	Administrators who can approve a temporary authentication request. `[ { "email_addresses": [ "test1@cloudflare.com", "test2@cloudflare.com" ], "approvals_needed": 1 }, { "email_list_uuid": "597147a1-976b-4ef2-9af0-81d5d007fc34", "approvals_needed": 3 } ]` An array with items in the following form: Show definition »
purpose_justification_prompt string	A custom message that will appear on the purpose justification screen. `"Please enter a justification for entering this protected domain."`
exclude array	Rules evaluated with a NOT logical operator. To match the policy, a user cannot meet any of the Exclude rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »
approval_required boolean	Requires the user to request access from an administrator at the start of each session. `true`	default value: false valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/policies/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"precedence":1,"decision":"allow","name":"Allow devs","include":[{"email":{"email":"test@example.com"}}],"exclude":[{"email":{"email":"test@example.com"}}],"require":[{"email":{"email":"test@example.com"}}],"purpose_justification_required":true,"purpose_justification_prompt":"Please enter a justification for entering this protected domain.","approval_required":true,"approval_groups":[{"email_addresses":["test1@cloudflare.com","test2@cloudflare.com"],"approvals_needed":1},{"email_list_uuid":"597147a1-976b-4ef2-9af0-81d5d007fc34","approvals_needed":3}]}'

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": "test@example.com"
        }
      }
    ],
    "exclude": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "require": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "purpose_justification_required": true,
    "purpose_justification_prompt": "Please enter a justification for entering this protected domain.",
    "approval_required": true,
    "approval_groups": [
      {
        "email_addresses": [
          "test1@cloudflare.com",
          "test2@cloudflare.com"
        ],
        "approvals_needed": 1
      },
      {
        "email_list_uuid": "597147a1-976b-4ef2-9af0-81d5d007fc34",
        "approvals_needed": 3
      }
    ]
  }
}

access-policies-delete-an-access-policy

DELETE Delete an Access policy

Delete an Access policy.

DELETE accounts/:identifier/access/apps/:uuid/policies/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/policies/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
  }
}

Access key configuration

Access key configuration defines the rotation policy for the keys used to sign Access JWTs.

access-key-configuration

Object definition

View properties and constraints defined on the object

Show definition

access-key-configuration-get-the-access-key-configuration

GET Get the Access key configuration

Gets the Access key rotation settings for an account.

GET accounts/:identifier/access/keys

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/keys" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "key_rotation_interval_days": 30,
  "last_key_rotation_at": "2014-01-01T05:20:00.12345Z",
  "days_until_next_rotation": 1
}

access-key-configuration-update-the-access-key-configuration

PUT Update the Access key configuration

Updates the Access key rotation settings for an account.

PUT accounts/:identifier/access/keys

Required parameters

Name /type	Description /example	Constraints
key_rotation_interval_days number	The number of days between key rotations. `30`	min value:21 max value:365

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/keys" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"key_rotation_interval_days":30}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "key_rotation_interval_days": 30,
  "last_key_rotation_at": "2014-01-01T05:20:00.12345Z",
  "days_until_next_rotation": 1
}

access-key-configuration-rotate-access-keys

POST Rotate Access keys

Perfoms a key rotation for an account.

POST accounts/:identifier/access/keys/rotate

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/keys/rotate" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "key_rotation_interval_days": 30,
  "last_key_rotation_at": "2014-01-01T05:20:00.12345Z",
  "days_until_next_rotation": 1
}

Access authentication logs

Access authentication logs maintain a record of Access application login attempts.

access-authentication-logs

Object definition

View properties and constraints defined on the object

Show definition

access-authentication-logs-get-access-authentication-logs

GET Get Access authentication logs

Gets a list of Access authentication audit logs for an account.

GET accounts/:identifier/access/logs/access_requests

Optional parameters

Name /type	Description /example	Constraints
limit number	The maximum number of log entries to retrieve. `25`
direction string	The chronological sorting order for the logs. `"desc"`	default value: desc valid values: desc, asc
since string (date-time)	The earliest event timestamp to query. `"2020-07-01T05:20:00Z"`	read only
until string (date-time)	The latest event timestamp to query. `"2020-10-01T05:20:00Z"`	read only

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/logs/access_requests?limit=25&direction=desc&since=2020-07-01T05:20:00Z&until=2020-10-01T05:20:00Z" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "user_email": "user@example.com",
      "ip_address": "198.41.129.166",
      "app_uid": "df7e2w5f-02b7-4d9d-af26-8d1988fca630",
      "app_domain": "test.example.com/admin",
      "action": "login",
      "connection": "saml",
      "allowed": false,
      "created_at": "2014-01-01T05:20:00.12345Z",
      "ray_id": "187d944c61940c77"
    }
  ]
}

Zero Trust seats

User seat allocation for a Zero Trust organization.

zero-trust-seats

Object definition

View properties and constraints defined on the object

Show definition

zero-trust-seats-update-a-user-seat

PATCH Update a user seat

Removes a user from a Zero Trust seat when both access_seat and gateway_seat are set to false.

PATCH accounts/:identifier/access/seats

Required parameters

Name /type	Description /example	Constraints
seat_uid string	The unique API identifier for the Zero Trust seat. `"f174e90a-fafe-4643-bbbc-4a0ed4fc8415"`	max length: 36 read only
access_seat boolean	True if the seat is part of Access. `false`	valid values: (true,false)
gateway_seat boolean	True if the seat is part of Gateway. `false`	valid values: (true,false)

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/seats" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '[{"seat_uid":"f174e90a-fafe-4643-bbbc-4a0ed4fc8415","access_seat":false,"gateway_seat":false}]'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "seat_uid": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z",
      "access_seat": false,
      "gateway_seat": false
    }
  ]
}

Access Bookmark applications

Access Bookmark applications are applications displayed in the App Launcher, but are not secured behind Access.

We recommend using the equivalent Access applications API.

access-bookmark-applications

Object definition

View properties and constraints defined on the object

Show definition

Deprecation Warning

End of life Date: March 19, 2023

This endpoint is deprecated in favor of using a specialized Access Application App Type.

access-bookmark-applications-list-bookmark-applications

GET List Bookmark applications

Lists Bookmark applications.

GET accounts/:identifier/access/bookmarks

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/bookmarks" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "domain": "example.com",
      "name": "My Website",
      "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
      "app_launcher_visible": true,
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z"
    }
  ]
}

Deprecation Warning

End of life Date: March 19, 2023

This endpoint is deprecated in favor of using a specialized Access Application App Type.

access-bookmark-applications-get-a-bookmark-application

GET Get a Bookmark application

Fetches a single Bookmark application.

GET accounts/:identifier/access/bookmarks/:uuid

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/bookmarks/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "domain": "example.com",
    "name": "My Website",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z"
  }
}

Deprecation Warning

End of life Date: March 19, 2023

This endpoint is deprecated in favor of using a specialized Access Application App Type.

access-bookmark-applications-create-a-bookmark-application

POST Create a Bookmark application

Create a new Bookmark application.

POST accounts/:identifier/access/bookmarks/:uuid

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/bookmarks/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "domain": "example.com",
    "name": "My Website",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z"
  }
}

Deprecation Warning

End of life Date: March 19, 2023

This endpoint is deprecated in favor of using a specialized Access Application App Type.

access-bookmark-applications-update-a-bookmark-application

PUT Update a Bookmark application

Updates a configured Bookmark application.

PUT accounts/:identifier/access/bookmarks/:uuid

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/bookmarks/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "domain": "example.com",
    "name": "My Website",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z"
  }
}

Deprecation Warning

End of life Date: March 19, 2023

This endpoint is deprecated in favor of using a specialized Access Application App Type.

access-bookmark-applications-delete-a-bookmark-application

DELETE Delete a Bookmark application

Deletes a Bookmark application.

DELETE accounts/:identifier/access/bookmarks/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/bookmarks/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
  }
}

Zone-Level Zero Trust organization

A Zero Trust organization defines the user login experience. (Note: We recommend using the equivalent account-level endpoints at https://api.cloudflare.com/#zero-trust-organization-properties. Account APIs provide a broader range of features and are backwards-compatible to zone APIs.)

zone-level-zero-trust-organization

Object definition

View properties and constraints defined on the object

Show definition

zone-level-zero-trust-organization-get-your-zero-trust-organization

GET Get your Zero Trust organization

Returns the configuration for your Zero Trust organization.

GET zones/:identifier/access/organizations

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/organizations" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "name": "Widget Corps Internal Applications",
    "auth_domain": "test.cloudflareaccess.com",
    "login_design": {
      "background_color": "#c5ed1b",
      "text_color": "#c5ed1b",
      "logo_path": "https://example.com/logo.png",
      "header_text": "This is an example description.",
      "footer_text": "This is an example description."
    }
  }
}

zone-level-zero-trust-organization-create-your-zero-trust-organization

POST Create your Zero Trust organization

Sets up a Zero Trust organization for your account.

POST zones/:identifier/access/organizations

Required parameters

Name /type	Description /example	Constraints
name string	The name of your Zero Trust organization. `"Widget Corps Internal Applications"`
auth_domain string	The unique subdomain assigned to your Zero Trust organization. `"test.cloudflareaccess.com"`

Optional parameters

Name /type	Description /example	Constraints
login_design	`{ "background_color": "#c5ed1b", "text_color": "#c5ed1b", "logo_path": "https://example.com/logo.png", "header_text": "This is an example description.", "footer_text": "This is an example description." }` An object with the following properties: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/organizations" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Widget Corps Internal Applications","auth_domain":"test.cloudflareaccess.com","login_design":{"background_color":"#c5ed1b","text_color":"#c5ed1b","logo_path":"https://example.com/logo.png","header_text":"This is an example description.","footer_text":"This is an example description."}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "name": "Widget Corps Internal Applications",
    "auth_domain": "test.cloudflareaccess.com",
    "login_design": {
      "background_color": "#c5ed1b",
      "text_color": "#c5ed1b",
      "logo_path": "https://example.com/logo.png",
      "header_text": "This is an example description.",
      "footer_text": "This is an example description."
    }
  }
}

zone-level-zero-trust-organization-update-your-zero-trust-organization

PUT Update your Zero Trust organization

Updates the configuration for your Zero Trust organization.

PUT zones/:identifier/access/organizations

Optional parameters

Name /type	Description /example	Constraints
name string	The name of your Zero Trust organization. `"Widget Corps Internal Applications"`
auth_domain string	The unique subdomain assigned to your Zero Trust organization. `"test.cloudflareaccess.com"`
login_design	`{ "background_color": "#c5ed1b", "text_color": "#c5ed1b", "logo_path": "https://example.com/logo.png", "header_text": "This is an example description.", "footer_text": "This is an example description." }` An object with the following properties: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/organizations" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Widget Corps Internal Applications","auth_domain":"test.cloudflareaccess.com","login_design":{"background_color":"#c5ed1b","text_color":"#c5ed1b","logo_path":"https://example.com/logo.png","header_text":"This is an example description.","footer_text":"This is an example description."}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "name": "Widget Corps Internal Applications",
    "auth_domain": "test.cloudflareaccess.com",
    "login_design": {
      "background_color": "#c5ed1b",
      "text_color": "#c5ed1b",
      "logo_path": "https://example.com/logo.png",
      "header_text": "This is an example description.",
      "footer_text": "This is an example description."
    }
  }
}

zone-level-zero-trust-organization-revoke-all-access-tokens-for-a-user

POST Revoke all Access tokens for a user

Revokes a user's access across all applications.

POST zones/:identifier/access/organizations/revoke_user

Required parameters

Name /type	Description /example	Constraints
email string	The email of the user to revoke. `"test@example.com"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/organizations/revoke_user" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"email":"test@example.com"}'

Response (example)

{
  "success": true,
  "result": true
}

Zone-Level Access identity providers

Identity providers are services that authenticate users to Access applications. (Note: We recommend using the equivalent account-level endpoints at https://api.cloudflare.com/#access-identity-providers-properties. Account APIs provide a broader range of features and are backwards-compatible to zone APIs.)

https://developers.cloudflare.com/cloudflare-one/identity/idp-integration/

zone-level-access-identity-providers

Object definition

View properties and constraints defined on the object

Show definition

zone-level-access-identity-providers-list-access-identity-providers

GET List Access identity providers

Lists all configured identity providers.

GET zones/:identifier/access/identity_providers

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/identity_providers" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "name": "Widget Corps OTP",
      "type": "onetimepin",
      "config": {}
    }
  ]
}

zone-level-access-identity-providers-get-an-access-identity-provider

GET Get an Access identity provider

Fetches a configured identity provider.

GET zones/:identifier/access/identity_providers/:uuid

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/identity_providers/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "Widget Corps OTP",
    "type": "onetimepin",
    "config": {}
  }
}

zone-level-access-identity-providers-add-an-access-identity-provider

POST Add an Access identity provider

Adds a new identity provider to Access.

POST zones/:identifier/access/identity_providers

Required parameters

Name /type	Description /example	Constraints
name string	The name of the identity provider, shown to users on the login page. `"Widget Corps OTP"`
type string	The type of identity provider. To determine the value for a specific provider, refer to our developer documentation. `"onetimepin"`
config object	The configuration parameters for the identity provider. To view the required parameters for a specific provider, refer to our developer documentation. `{}` An object with the following properties: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/identity_providers" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Widget Corps OTP","type":"onetimepin","config":{}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "Widget Corps OTP",
    "type": "onetimepin",
    "config": {}
  }
}

zone-level-access-identity-providers-update-an-access-identity-provider

PUT Update an Access identity provider

Updates a configured identity provider.

PUT zones/:identifier/access/identity_providers/:uuid

Required parameters

Name /type	Description /example	Constraints
name string	The name of the identity provider, shown to users on the login page. `"Widget Corps OTP"`
type string	The type of identity provider. To determine the value for a specific provider, refer to our developer documentation. `"onetimepin"`
config object	The configuration parameters for the identity provider. To view the required parameters for a specific provider, refer to our developer documentation. `{}` An object with the following properties: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/identity_providers/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Widget Corps OTP","type":"onetimepin","config":{}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "Widget Corps OTP",
    "type": "onetimepin",
    "config": {}
  }
}

zone-level-access-identity-providers-delete-an-access-identity-provider

DELETE Delete an Access identity provider

Deletes an identity provider from Access.

DELETE zones/:identifier/access/identity_providers/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/identity_providers/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "Widget Corps OTP",
    "type": "onetimepin",
    "config": {}
  }
}

Zone-Level Access groups

An Access group is a set of reusable rules that can be quickly applied across many Access policies. (Note: We recommend using the equivalent account-level endpoints at https://api.cloudflare.com/#access-groups-properties. Account APIs provide a broader range of features and are backwards-compatible to zone APIs.)

https://developers.cloudflare.com/access/setting-up-access/access-groups/

zone-level-access-groups

Object definition

View properties and constraints defined on the object

Show definition

zone-level-access-groups-list-access-groups

GET List Access groups

Lists all Access groups.

GET zones/:identifier/access/groups

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/access/groups" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z",
      "name": "Allow devs",
      "include": [
        {
          "email": {
            "email": "test@example.com"
          }
        }
      ],
      "exclude": [
        {
          "email": {
            "email": "test@example.com"
          }
        }
      ],
      "require": [
        {
          "email": {
            "email": "test@example.com"
          }
        }
      ]
    }
  ]
}

zone-level-access-groups-get-an-access-group

GET Get an Access group

Fetches a single Access group.

GET zones/:identifier/access/groups/:uuid

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/access/groups/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "name": "Allow devs",
    "include": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "exclude": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "require": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ]
  }
}

zone-level-access-groups-create-an-access-group

POST Create an Access group

Creates a new Access group.

POST zones/:identifier/access/groups

Required parameters

Name /type	Description /example	Constraints
name string	The name of the Access group. `"Allow devs"`
include array	Rules evaluated with an OR logical operator. A user needs to meet only one of the Include rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
exclude array	Rules evaluated with a NOT logical operator. To match a policy, a user cannot meet any of the Exclude rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »
require array	Rules evaluated with an AND logical operator. To match a policy, a user must meet all of the Require rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/access/groups" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Allow devs","include":[{"email":{"email":"test@example.com"}}],"exclude":[{"email":{"email":"test@example.com"}}],"require":[{"email":{"email":"test@example.com"}}]}'

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",
    "name": "Allow devs",
    "include": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "exclude": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "require": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ]
  }
}

zone-level-access-groups-update-an-access-group

PUT Update an Access group

Updates a configured Access group.

PUT zones/:identifier/access/groups/:uuid

Required parameters

Name /type	Description /example	Constraints
name string	The name of the Access group. `"Allow devs"`
include array	Rules evaluated with an OR logical operator. A user needs to meet only one of the Include rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
exclude array	Rules evaluated with a NOT logical operator. To match a policy, a user cannot meet any of the Exclude rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »
require array	Rules evaluated with an AND logical operator. To match a policy, a user must meet all of the Require rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/access/groups/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Allow devs","include":[{"email":{"email":"test@example.com"}}],"exclude":[{"email":{"email":"test@example.com"}}],"require":[{"email":{"email":"test@example.com"}}]}'

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",
    "name": "Allow devs",
    "include": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "exclude": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "require": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ]
  }
}

zone-level-access-groups-delete-an-access-group

DELETE Delete an Access group

Deletes an Access group.

DELETE zones/:identifier/access/groups/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/access/groups/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
  }
}

Zone-Level Access service tokens

Service tokens allow automated requests to reach applications protected by Access. (Note: We recommend using the equivalent account-level endpoints at https://api.cloudflare.com/#access-service-tokens-properties. Account APIs provide a broader range of features and are backwards-compatible to zone APIs.)

https://developers.cloudflare.com/cloudflare-one/identity/service-tokens/

zone-level-access-service-tokens

Object definition

View properties and constraints defined on the object

Show definition

zone-level-access-service-tokens-list-service-tokens

GET List service tokens

Lists all service tokens.

GET zones/:identifier/access/service_tokens

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/access/service_tokens" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z",
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "name": "CI/CD token",
      "client_id": "88bf3b6d86161464f6509f7219099e57.access.example.com"
    }
  ]
}

zone-level-access-service-tokens-create-a-service-token

POST Create a service token

Generates a new service token. Note: This is the only time you can get the Client Secret. If you lose the Client Secret, you will have to create a new service token.

POST zones/:identifier/access/service_tokens

Required parameters

Name /type	Description /example	Constraints
name string	The name of the service token. `"CI/CD token"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/access/service_tokens" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"CI/CD token"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "CI/CD token",
    "client_id": "88bf3b6d86161464f6509f7219099e57.access.example.com",
    "client_secret": "bdd31cbc4dec990953e39163fbbb194c93313ca9f0a6e420346af9d326b1d2a5"
  }
}

zone-level-access-service-tokens-update-a-service-token

PUT Update a service token

Updates a configured service token.

PUT zones/:identifier/access/service_tokens/:uuid

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the service token. `"CI/CD token"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/access/service_tokens/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"CI/CD token"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "CI/CD token",
    "client_id": "88bf3b6d86161464f6509f7219099e57.access.example.com"
  }
}

zone-level-access-service-tokens-delete-a-service-token

DELETE Delete a service token

Deletes a service token.

DELETE zones/:identifier/access/service_tokens/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/access/service_tokens/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "CI/CD token",
    "client_id": "88bf3b6d86161464f6509f7219099e57.access.example.com"
  }
}

Zone-Level Access short-lived certificate CAs

The certificate authority (CA) issues short-lived certificates during an SSH session. Clients authenticate to the SSH server with ephemeral certificates instead of traditional SSH keys. (Note: We recommend using the equivalent account-level endpoints at https://api.cloudflare.com/#access-short-lived-certificate-cas-properties. Account APIs provide a broader range of features and are backwards-compatible to zone APIs.)

https://developers.cloudflare.com/cloudflare-one/identity/users/short-lived-certificates/

zone-level-access-short-lived-certificate-cas

Object definition

View properties and constraints defined on the object

Show definition

zone-level-access-short-lived-certificate-cas-list-short-lived-certificate-cas

GET List short-lived certificate CAs

Lists short-lived certificate CAs and their public keys.

GET zones/:identifier/access/apps/ca

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/access/apps/ca" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "7eddae4619b50ab1361ba8ae9bd72269a432fea041529ed9",
      "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893",
      "public_key": "ecdsa-sha2-nistp256 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx= open-ssh-ca@cloudflareaccess.org"
    }
  ]
}

zone-level-access-short-lived-certificate-cas-get-a-short-lived-certificate-ca

GET Get a short-lived certificate CA

Fetches a short-lived certificate CA and its public key.

GET zones/:identifier/access/apps/:uuid/ca

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/ca" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

zone-level-access-short-lived-certificate-cas-create-a-short-lived-certificate-ca

POST Create a short-lived certificate CA

Generates a new short-lived certificate CA and public key.

POST zones/:identifier/access/apps/:uuid/ca

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/ca" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

zone-level-access-short-lived-certificate-cas-delete-a-short-lived-certificate-ca

DELETE Delete a short-lived certificate CA

Deletes a short-lived certificate CA.

DELETE zones/:identifier/access/apps/:uuid/ca

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/access/apps/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/ca" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Zone-Level Access mTLS authentication

Mutual TLS (mTLS) authentication establishes trust between a client and server via a shared certificate. (Note: We recommend using the equivalent account-level endpoints at https://api.cloudflare.com/#access-mutual-tls-authentication-properties. Account APIs provide a broader range of features and are backwards-compatible to zone APIs.)

https://developers.cloudflare.com/access/service-auth/mtls/

zone-level-access-mtls-authentication

Object definition

View properties and constraints defined on the object

Show definition

zone-level-access-mtls-authentication-list-mtls-certificates

GET List mTLS certificates

Lists all mTLS certificates.

GET zones/:identifier/access/certificates

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/access/certificates" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z",
      "expires_on": "2014-01-01T05:20:00.12345Z",
      "name": "Allow devs",
      "fingerprint": "MD5 Fingerprint=1E:80:0F:7A:FD:31:55:96:DE:D5:CB:E2:F0:91:F6:91",
      "associated_hostnames": [
        "admin.example.com"
      ]
    }
  ]
}

zone-level-access-mtls-authentication-get-an-mtls-certificate

GET Get an mTLS certificate

Fetches a single mTLS certificate.

GET zones/:identifier/access/certificates/:uuid

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/access/certificates/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "expires_on": "2014-01-01T05:20:00.12345Z",
    "name": "Allow devs",
    "fingerprint": "MD5 Fingerprint=1E:80:0F:7A:FD:31:55:96:DE:D5:CB:E2:F0:91:F6:91",
    "associated_hostnames": [
      "admin.example.com"
    ]
  }
}

zone-level-access-mtls-authentication-add-an-mtls-certificate

POST Add an mTLS certificate

Adds a new mTLS root certificate to Access.

POST zones/:identifier/access/certificates

Required parameters

Name /type	Description /example	Constraints
name string	The name of the certificate. `"Allow devs"`
certificate string	The certificate content. `"-----BEGIN CERTIFICATE-----\nMIIGAjCCA+qgAwIBAgIJAI7kymlF7CWT...N4RI7KKB7nikiuUf8vhULKy5IX10\nDrUtmu/B\n-----END CERTIFICATE-----"`

Optional parameters

Name /type	Description /example	Constraints
associated_hostnames array	The hostnames of the applications that will use this certificate. `[ "admin.example.com" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/access/certificates" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Allow devs","certificate":"-----BEGIN CERTIFICATE-----\nMIIGAjCCA+qgAwIBAgIJAI7kymlF7CWT...N4RI7KKB7nikiuUf8vhULKy5IX10\nDrUtmu/B\n-----END CERTIFICATE-----","associated_hostnames":["admin.example.com"]}'

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",
    "expires_on": "2014-01-01T05:20:00.12345Z",
    "name": "Allow devs",
    "fingerprint": "MD5 Fingerprint=1E:80:0F:7A:FD:31:55:96:DE:D5:CB:E2:F0:91:F6:91",
    "associated_hostnames": [
      "admin.example.com"
    ]
  }
}

zone-level-access-mtls-authentication-update-an-mtls-certificate

PUT Update an mTLS certificate

Updates a configured mTLS certificate.

PUT zones/:identifier/access/certificates/:uuid

Required parameters

Name /type	Description /example	Constraints
name string	The name of the certificate. `"Allow devs"`
associated_hostnames array	The hostnames of the applications that will use this certificate. `[ "admin.example.com" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/access/certificates/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Allow devs","associated_hostnames":["admin.example.com"]}'

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",
    "expires_on": "2014-01-01T05:20:00.12345Z",
    "name": "Allow devs",
    "fingerprint": "MD5 Fingerprint=1E:80:0F:7A:FD:31:55:96:DE:D5:CB:E2:F0:91:F6:91",
    "associated_hostnames": [
      "admin.example.com"
    ]
  }
}

zone-level-access-mtls-authentication-delete-an-mtls-certificate

DELETE Delete an mTLS certificate

Deletes an mTLS certificate.

DELETE zones/:identifier/access/certificates/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/access/certificates/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
  }
}

Zone-Level Access applications

Applications secured behind Cloudflare Access for a specific zone. (Note: We recommend using the equivalent account-level endpoints at https://api.cloudflare.com/#access-applications-properties. Account APIs provide a broader range of features and are backwards-compatible to zone APIs.)

zone-level-access-applications

Object definitions

View properties and constraints defined on the object

Show definitions

zone-level-access-applications-list-access-applications

GET List Access Applications

List all Access Applications in 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: user@example.com" \
     -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",
      "type": "self_hosted",
      "name": "Admin Site",
      "domain": "test.example.com/admin",
      "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
      "app_launcher_visible": true,
      "session_duration": "24h",
      "allowed_idps": [
        "699d98642c564d2e855e9661899b7252"
      ],
      "auto_redirect_to_identity": false,
      "enable_binding_cookie": false,
      "http_only_cookie_attribute": true,
      "same_site_cookie_attribute": "strict",
      "cors_headers": {
        "allowed_methods": [
          "GET"
        ],
        "allowed_origins": [
          "https://example.com"
        ],
        "allow_all_headers": true,
        "max_age": -1
      },
      "skip_interstitial": true,
      "service_auth_401_redirect": true
    }
  ]
}

zone-level-access-applications-get-an-access-application

GET Get an Access application

Fetches information about an Access application.

GET zones/:identifier/access/apps/:app_id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893",
    "type": "self_hosted",
    "name": "Admin Site",
    "domain": "test.example.com/admin",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "enable_binding_cookie": false,
    "http_only_cookie_attribute": true,
    "same_site_cookie_attribute": "strict",
    "cors_headers": {
      "allowed_methods": [
        "GET"
      ],
      "allowed_origins": [
        "https://example.com"
      ],
      "allow_all_headers": true,
      "max_age": -1
    },
    "skip_interstitial": true,
    "service_auth_401_redirect": true
  }
}

zone-level-access-applications-add-a-self-hosted-application

POST Add a self-hosted application

Adds a self-hosted application to Access.

POST zones/:identifier/access/apps

Required parameters

Name /type	Description /example	Constraints
domain string	The domain and path that Access will secure. `"test.example.com/admin"`
name string	The name of the application. `"Admin Site"`
type string	The application type. `"self_hosted"`

Optional parameters

Name /type	Description /example	Constraints
same_site_cookie_attribute string	Sets the SameSite cookie setting, which provides increased security against CSRF attacks. `"strict"`
custom_deny_message string	The custom error message shown to a user when they are denied access to the application.
custom_deny_url string	The custom URL a user is redirected to when they are denied access to the application.
skip_interstitial boolean	Enables automatic authentication through cloudflared. `true`	valid values: (true,false)
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)
service_auth_401_redirect boolean	Returns a 401 status code when the request is blocked by a Service Auth policy. `true`	valid values: (true,false)
cors_headers object	`{ "allowed_methods": [ "GET" ], "allowed_origins": [ "https://example.com" ], "allow_all_headers": true, "max_age": -1 }` An object with the following properties: Show definition »
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
enable_binding_cookie boolean	Enables the binding cookie, which increases security against compromised authorization tokens and CSRF attacks. `false`	default value: false valid values: (true,false)
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
http_only_cookie_attribute boolean	Enables the HttpOnly cookie attribute, which increases security against XSS attacks. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"self_hosted","name":"Admin Site","domain":"test.example.com/admin","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true,"session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false,"enable_binding_cookie":false,"http_only_cookie_attribute":true,"same_site_cookie_attribute":"strict","cors_headers":{"allowed_methods":["GET"],"allowed_origins":["https://example.com"],"allow_all_headers":true,"max_age":-1},"skip_interstitial":true,"service_auth_401_redirect":true}'

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",
    "type": "self_hosted",
    "name": "Admin Site",
    "domain": "test.example.com/admin",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "enable_binding_cookie": false,
    "http_only_cookie_attribute": true,
    "same_site_cookie_attribute": "strict",
    "cors_headers": {
      "allowed_methods": [
        "GET"
      ],
      "allowed_origins": [
        "https://example.com"
      ],
      "allow_all_headers": true,
      "max_age": -1
    },
    "skip_interstitial": true,
    "service_auth_401_redirect": true
  }
}

zone-level-access-applications-add-an-ssh-application

POST Add an SSH application

Adds a new SSH application to Access. The SSH terminal will render in the user's browser.

POST zones/:identifier/access/apps

Required parameters

Name /type	Description /example	Constraints
domain string	The domain and path that Access will secure. `"test.example.com/admin"`
name string	The name of the application. `"Admin Site"`
type string	The application type `"ssh"`

Optional parameters

Name /type	Description /example	Constraints
same_site_cookie_attribute string	Sets the SameSite cookie setting, which provides increased security against CSRF attacks. `"strict"`
custom_deny_message string	The custom error message shown to a user when they are denied access to the application.
custom_deny_url string	The custom URL a user is redirected to when they are denied access to the application.
skip_interstitial boolean	Enables automatic authentication through cloudflared. `true`	valid values: (true,false)
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)
service_auth_401_redirect boolean	Returns a 401 status code when the request is blocked by a Service Auth policy. `true`	valid values: (true,false)
cors_headers object	`{ "allowed_methods": [ "GET" ], "allowed_origins": [ "https://example.com" ], "allow_all_headers": true, "max_age": -1 }` An object with the following properties: Show definition »
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
enable_binding_cookie boolean	Enables the binding cookie, which increases security against compromised authorization tokens and CSRF attacks. `false`	default value: false valid values: (true,false)
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
http_only_cookie_attribute boolean	Enables the HttpOnly cookie attribute, which increases security against XSS attacks. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"ssh","name":"Admin Site","domain":"test.example.com/admin","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true,"session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false,"enable_binding_cookie":false,"http_only_cookie_attribute":true,"same_site_cookie_attribute":"strict","cors_headers":{"allowed_methods":["GET"],"allowed_origins":["https://example.com"],"allow_all_headers":true,"max_age":-1},"skip_interstitial":true,"service_auth_401_redirect":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "ssh",
    "name": "Admin Site",
    "domain": "test.example.com/admin",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "enable_binding_cookie": false,
    "http_only_cookie_attribute": true,
    "same_site_cookie_attribute": "strict",
    "cors_headers": {
      "allowed_methods": [
        "GET"
      ],
      "allowed_origins": [
        "https://example.com"
      ],
      "allow_all_headers": true,
      "max_age": -1
    },
    "skip_interstitial": true,
    "service_auth_401_redirect": true,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

zone-level-access-applications-add-a-vnc-application

POST Add a VNC application

Adds a new VNC application to Access. The VNC terminal will render in the user's browser.

POST zones/:identifier/access/apps

Required parameters

Name /type	Description /example	Constraints
domain string	The domain and path that Access will secure. `"test.example.com/admin"`
name string	The name of the application. `"Admin Site"`
type string	The application type `"vnc"`

Optional parameters

Name /type	Description /example	Constraints
same_site_cookie_attribute string	Sets the SameSite cookie setting, which provides increased security against CSRF attacks. `"strict"`
custom_deny_message string	The custom error message shown to a user when they are denied access to the application.
custom_deny_url string	The custom URL a user is redirected to when they are denied access to the application.
skip_interstitial boolean	Enables automatic authentication through cloudflared. `true`	valid values: (true,false)
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)
service_auth_401_redirect boolean	Returns a 401 status code when the request is blocked by a Service Auth policy. `true`	valid values: (true,false)
cors_headers object	`{ "allowed_methods": [ "GET" ], "allowed_origins": [ "https://example.com" ], "allow_all_headers": true, "max_age": -1 }` An object with the following properties: Show definition »
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
enable_binding_cookie boolean	Enables the binding cookie, which increases security against compromised authorization tokens and CSRF attacks. `false`	default value: false valid values: (true,false)
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
http_only_cookie_attribute boolean	Enables the HttpOnly cookie attribute, which increases security against XSS attacks. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"vnc","name":"Admin Site","domain":"test.example.com/admin","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true,"session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false,"enable_binding_cookie":false,"http_only_cookie_attribute":true,"same_site_cookie_attribute":"strict","cors_headers":{"allowed_methods":["GET"],"allowed_origins":["https://example.com"],"allow_all_headers":true,"max_age":-1},"skip_interstitial":true,"service_auth_401_redirect":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "vnc",
    "name": "Admin Site",
    "domain": "test.example.com/admin",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "enable_binding_cookie": false,
    "http_only_cookie_attribute": true,
    "same_site_cookie_attribute": "strict",
    "cors_headers": {
      "allowed_methods": [
        "GET"
      ],
      "allowed_origins": [
        "https://example.com"
      ],
      "allow_all_headers": true,
      "max_age": -1
    },
    "skip_interstitial": true,
    "service_auth_401_redirect": true,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

zone-level-access-applications-add-a-saas-application

POST Add a SaaS application

Adds a new SaaS application to Access.

POST zones/:identifier/access/apps

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"saas"`
name string	The name of the application. `"Admin Site"`
saas_app object	{ "consumer_service_url": "https://example.com", "sp_entity_id": "example unique name", "public_key": "example unique name", "idp_entity_id": "https://example.cloudflareaccess.com", "name_id_format": "id", "sso_endpoint": "https://example.cloudflareaccess.com/cdn-cgi/access/sso/saml/b3f58a2b414e0b51d45c8c2af26fccca0e27c63763c426fa52f98dcf0b3b3bfd", "custom_attributes": { "name": "family_name", "name_format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic", "source": { "name": "last_name" } }, "created_at": "2014-01-01T05:20:00.12345Z", "updated_at": "2014-01-01T05:20:00.12345Z" } An object with the following properties: Show definition »

Optional parameters

Name /type	Description /example	Constraints
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"saas","name":"Admin Site","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true,"saas_app":{"consumer_service_url":"https://example.com","sp_entity_id":"example unique name","public_key":"example unique name","idp_entity_id":"https://example.cloudflareaccess.com","name_id_format":"id","sso_endpoint":"https://example.cloudflareaccess.com/cdn-cgi/access/sso/saml/b3f58a2b414e0b51d45c8c2af26fccca0e27c63763c426fa52f98dcf0b3b3bfd","custom_attributes":{"name":"family_name","name_format":"urn:oasis:names:tc:SAML:2.0:attrname-format:basic","source":{"name":"last_name"}},"created_at":"2014-01-01T05:20:00.12345Z","updated_at":"2014-01-01T05:20:00.12345Z"},"allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false}'

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",
    "type": "saas",
    "name": "Admin Site",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "saas_app": {
      "consumer_service_url": "https://example.com",
      "sp_entity_id": "example unique name",
      "public_key": "example unique name",
      "idp_entity_id": "https://example.cloudflareaccess.com",
      "name_id_format": "id",
      "sso_endpoint": "https://example.cloudflareaccess.com/cdn-cgi/access/sso/saml/b3f58a2b414e0b51d45c8c2af26fccca0e27c63763c426fa52f98dcf0b3b3bfd",
      "custom_attributes": {
        "name": "family_name",
        "name_format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
        "source": {
          "name": "last_name"
        }
      },
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z"
    },
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false
  }
}

zone-level-access-applications-add-the-access-app-launcher

POST Add the Access App Launcher

Adds the App Launcher application to Access, allowing you to define which users can access the App Launcher portal.

POST zones/:identifier/access/apps

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"app_launcher"`	valid values: self_hosted, saas, ssh, vnc, app_launcher, warp, biso, bookmark, dash_sso

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the application. `"App Launcher"`	default value: App Launcher read only
domain string	The domain and path that Access will secure. `"authdomain.cloudflareaccess.com"`	read only
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"app_launcher","name":"App Launcher","domain":"authdomain.cloudflareaccess.com","session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "app_launcher",
    "name": "App Launcher",
    "domain": "authdomain.cloudflareaccess.com",
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

POST Add the WARP login application

Adds the WARP login application to Access, allowing you to define which users can enroll devices.

POST zones/:identifier/access/apps

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"warp"`	valid values: self_hosted, saas, ssh, vnc, app_launcher, warp, biso, bookmark, dash_sso

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the application. `"Warp Login App"`	default value: Warp Login App read only
domain string	The domain and path that Access will secure. `"authdomain.cloudflareaccess.com/warp"`	read only
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"warp","name":"Warp Login App","domain":"authdomain.cloudflareaccess.com/warp","session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "warp",
    "name": "Warp Login App",
    "domain": "authdomain.cloudflareaccess.com/warp",
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

zone-level-access-applications-add-the-clientless-web-isolation-application

POST Add the Clientless Web Isolation application

Adds the Clientless Web Isolation application to Access, allowing you to define which users can access the clientless remote browser.

POST zones/:identifier/access/apps

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"biso"`	valid values: self_hosted, saas, ssh, vnc, app_launcher, warp, biso, bookmark, dash_sso

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the application. `"Clientless Web Isolation"`	default value: Clientless Web Isolation read only
domain string	The domain and path that Access will secure. `"authdomain.cloudflareaccess.com/browser"`	read only
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"biso","name":"Clientless Web Isolation","domain":"authdomain.cloudflareaccess.com/browser","session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "biso",
    "name": "Clientless Web Isolation",
    "domain": "authdomain.cloudflareaccess.com/browser",
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

zone-level-access-applications-add-a-bookmark-application

POST Add a Bookmark application

Adds a custom link to the App Launcher. Bookmark applications are not protected by Access.

POST zones/:identifier/access/apps

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"bookmark"`
name string	The name of the application. `"Admin Site"`
domain string	The URL or domain of the bookmark. `"https://mybookmark.com"`

Optional parameters

Name /type	Description /example	Constraints
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"bookmark","name":"Admin Site","domain":"https://mybookmark.com","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true}'

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",
    "type": "bookmark",
    "name": "Admin Site",
    "domain": "https://mybookmark.com",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true
  }
}

zone-level-access-applications-update-a-self-hosted-application

PUT Update a self-hosted application

Updates the configuration for a self-hosted Access application.

PUT zones/:identifier/access/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
domain string	The domain and path that Access will secure. `"test.example.com/admin"`
name string	The name of the application. `"Admin Site"`
type string	The application type. `"self_hosted"`

Optional parameters

Name /type	Description /example	Constraints
same_site_cookie_attribute string	Sets the SameSite cookie setting, which provides increased security against CSRF attacks. `"strict"`
custom_deny_message string	The custom error message shown to a user when they are denied access to the application.
custom_deny_url string	The custom URL a user is redirected to when they are denied access to the application.
skip_interstitial boolean	Enables automatic authentication through cloudflared. `true`	valid values: (true,false)
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)
service_auth_401_redirect boolean	Returns a 401 status code when the request is blocked by a Service Auth policy. `true`	valid values: (true,false)
cors_headers object	`{ "allowed_methods": [ "GET" ], "allowed_origins": [ "https://example.com" ], "allow_all_headers": true, "max_age": -1 }` An object with the following properties: Show definition »
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
enable_binding_cookie boolean	Enables the binding cookie, which increases security against compromised authorization tokens and CSRF attacks. `false`	default value: false valid values: (true,false)
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
http_only_cookie_attribute boolean	Enables the HttpOnly cookie attribute, which increases security against XSS attacks. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"self_hosted","name":"Admin Site","domain":"test.example.com/admin","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true,"session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false,"enable_binding_cookie":false,"http_only_cookie_attribute":true,"same_site_cookie_attribute":"strict","cors_headers":{"allowed_methods":["GET"],"allowed_origins":["https://example.com"],"allow_all_headers":true,"max_age":-1},"skip_interstitial":true,"service_auth_401_redirect":true}'

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",
    "type": "self_hosted",
    "name": "Admin Site",
    "domain": "test.example.com/admin",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "enable_binding_cookie": false,
    "http_only_cookie_attribute": true,
    "same_site_cookie_attribute": "strict",
    "cors_headers": {
      "allowed_methods": [
        "GET"
      ],
      "allowed_origins": [
        "https://example.com"
      ],
      "allow_all_headers": true,
      "max_age": -1
    },
    "skip_interstitial": true,
    "service_auth_401_redirect": true
  }
}

zone-level-access-applications-update-an-ssh-application

PUT Update an SSH application

Updates the configuration for an SSH Access application.

PUT zones/:identifier/access/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
domain string	The domain and path that Access will secure. `"test.example.com/admin"`
name string	The name of the application. `"Admin Site"`
type string	The application type `"ssh"`

Optional parameters

Name /type	Description /example	Constraints
same_site_cookie_attribute string	Sets the SameSite cookie setting, which provides increased security against CSRF attacks. `"strict"`
custom_deny_message string	The custom error message shown to a user when they are denied access to the application.
custom_deny_url string	The custom URL a user is redirected to when they are denied access to the application.
skip_interstitial boolean	Enables automatic authentication through cloudflared. `true`	valid values: (true,false)
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)
service_auth_401_redirect boolean	Returns a 401 status code when the request is blocked by a Service Auth policy. `true`	valid values: (true,false)
cors_headers object	`{ "allowed_methods": [ "GET" ], "allowed_origins": [ "https://example.com" ], "allow_all_headers": true, "max_age": -1 }` An object with the following properties: Show definition »
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
enable_binding_cookie boolean	Enables the binding cookie, which increases security against compromised authorization tokens and CSRF attacks. `false`	default value: false valid values: (true,false)
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
http_only_cookie_attribute boolean	Enables the HttpOnly cookie attribute, which increases security against XSS attacks. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"ssh","name":"Admin Site","domain":"test.example.com/admin","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true,"session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false,"enable_binding_cookie":false,"http_only_cookie_attribute":true,"same_site_cookie_attribute":"strict","cors_headers":{"allowed_methods":["GET"],"allowed_origins":["https://example.com"],"allow_all_headers":true,"max_age":-1},"skip_interstitial":true,"service_auth_401_redirect":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "ssh",
    "name": "Admin Site",
    "domain": "test.example.com/admin",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "enable_binding_cookie": false,
    "http_only_cookie_attribute": true,
    "same_site_cookie_attribute": "strict",
    "cors_headers": {
      "allowed_methods": [
        "GET"
      ],
      "allowed_origins": [
        "https://example.com"
      ],
      "allow_all_headers": true,
      "max_age": -1
    },
    "skip_interstitial": true,
    "service_auth_401_redirect": true,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

zone-level-access-applications-update-a-vnc-application

PUT Update a VNC application

Updates the configuration for a VNC Access application.

PUT zones/:identifier/access/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
domain string	The domain and path that Access will secure. `"test.example.com/admin"`
name string	The name of the application. `"Admin Site"`
type string	The application type `"vnc"`

Optional parameters

Name /type	Description /example	Constraints
same_site_cookie_attribute string	Sets the SameSite cookie setting, which provides increased security against CSRF attacks. `"strict"`
custom_deny_message string	The custom error message shown to a user when they are denied access to the application.
custom_deny_url string	The custom URL a user is redirected to when they are denied access to the application.
skip_interstitial boolean	Enables automatic authentication through cloudflared. `true`	valid values: (true,false)
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)
service_auth_401_redirect boolean	Returns a 401 status code when the request is blocked by a Service Auth policy. `true`	valid values: (true,false)
cors_headers object	`{ "allowed_methods": [ "GET" ], "allowed_origins": [ "https://example.com" ], "allow_all_headers": true, "max_age": -1 }` An object with the following properties: Show definition »
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
enable_binding_cookie boolean	Enables the binding cookie, which increases security against compromised authorization tokens and CSRF attacks. `false`	default value: false valid values: (true,false)
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
http_only_cookie_attribute boolean	Enables the HttpOnly cookie attribute, which increases security against XSS attacks. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"vnc","name":"Admin Site","domain":"test.example.com/admin","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true,"session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false,"enable_binding_cookie":false,"http_only_cookie_attribute":true,"same_site_cookie_attribute":"strict","cors_headers":{"allowed_methods":["GET"],"allowed_origins":["https://example.com"],"allow_all_headers":true,"max_age":-1},"skip_interstitial":true,"service_auth_401_redirect":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "vnc",
    "name": "Admin Site",
    "domain": "test.example.com/admin",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "enable_binding_cookie": false,
    "http_only_cookie_attribute": true,
    "same_site_cookie_attribute": "strict",
    "cors_headers": {
      "allowed_methods": [
        "GET"
      ],
      "allowed_origins": [
        "https://example.com"
      ],
      "allow_all_headers": true,
      "max_age": -1
    },
    "skip_interstitial": true,
    "service_auth_401_redirect": true,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

zone-level-access-applications-update-a-saas-application

PUT Update a SaaS application

Updates the configuration for a SaaS Access application.

PUT zones/:identifier/access/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"saas"`
name string	The name of the application. `"Admin Site"`
saas_app object	{ "consumer_service_url": "https://example.com", "sp_entity_id": "example unique name", "public_key": "example unique name", "idp_entity_id": "https://example.cloudflareaccess.com", "name_id_format": "id", "sso_endpoint": "https://example.cloudflareaccess.com/cdn-cgi/access/sso/saml/b3f58a2b414e0b51d45c8c2af26fccca0e27c63763c426fa52f98dcf0b3b3bfd", "custom_attributes": { "name": "family_name", "name_format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic", "source": { "name": "last_name" } }, "created_at": "2014-01-01T05:20:00.12345Z", "updated_at": "2014-01-01T05:20:00.12345Z" } An object with the following properties: Show definition »

Optional parameters

Name /type	Description /example	Constraints
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"saas","name":"Admin Site","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true,"saas_app":{"consumer_service_url":"https://example.com","sp_entity_id":"example unique name","public_key":"example unique name","idp_entity_id":"https://example.cloudflareaccess.com","name_id_format":"id","sso_endpoint":"https://example.cloudflareaccess.com/cdn-cgi/access/sso/saml/b3f58a2b414e0b51d45c8c2af26fccca0e27c63763c426fa52f98dcf0b3b3bfd","custom_attributes":{"name":"family_name","name_format":"urn:oasis:names:tc:SAML:2.0:attrname-format:basic","source":{"name":"last_name"}},"created_at":"2014-01-01T05:20:00.12345Z","updated_at":"2014-01-01T05:20:00.12345Z"},"allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false}'

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",
    "type": "saas",
    "name": "Admin Site",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true,
    "saas_app": {
      "consumer_service_url": "https://example.com",
      "sp_entity_id": "example unique name",
      "public_key": "example unique name",
      "idp_entity_id": "https://example.cloudflareaccess.com",
      "name_id_format": "id",
      "sso_endpoint": "https://example.cloudflareaccess.com/cdn-cgi/access/sso/saml/b3f58a2b414e0b51d45c8c2af26fccca0e27c63763c426fa52f98dcf0b3b3bfd",
      "custom_attributes": {
        "name": "family_name",
        "name_format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
        "source": {
          "name": "last_name"
        }
      },
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z"
    },
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false
  }
}

zone-level-access-applications-update-the-access-app-launcher

PUT Update the Access App Launcher

Updates the App Launcher portal.

PUT zones/:identifier/access/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"app_launcher"`	valid values: self_hosted, saas, ssh, vnc, app_launcher, warp, biso, bookmark, dash_sso

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the application. `"App Launcher"`	default value: App Launcher read only
domain string	The domain and path that Access will secure. `"authdomain.cloudflareaccess.com"`	read only
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"app_launcher","name":"App Launcher","domain":"authdomain.cloudflareaccess.com","session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "app_launcher",
    "name": "App Launcher",
    "domain": "authdomain.cloudflareaccess.com",
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

PUT Update the WARP login application

Updates the WARP device enrollment application.

PUT zones/:identifier/access/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"warp"`	valid values: self_hosted, saas, ssh, vnc, app_launcher, warp, biso, bookmark, dash_sso

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the application. `"Warp Login App"`	default value: Warp Login App read only
domain string	The domain and path that Access will secure. `"authdomain.cloudflareaccess.com/warp"`	read only
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"warp","name":"Warp Login App","domain":"authdomain.cloudflareaccess.com/warp","session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "warp",
    "name": "Warp Login App",
    "domain": "authdomain.cloudflareaccess.com/warp",
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

zone-level-access-applications-update-the-clientless-web-isolation-application

PUT Update the Clientless Web Isolation application

Updates the Clientless Web Isolation application.

PUT zones/:identifier/access/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"biso"`	valid values: self_hosted, saas, ssh, vnc, app_launcher, warp, biso, bookmark, dash_sso

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the application. `"Clientless Web Isolation"`	default value: Clientless Web Isolation read only
domain string	The domain and path that Access will secure. `"authdomain.cloudflareaccess.com/browser"`	read only
session_duration string	The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. `"24h"`	default value: 24h
allowed_idps array	The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account. `[ "699d98642c564d2e855e9661899b7252" ]` An array with items in the following form: Show definition »
auto_redirect_to_identity boolean	When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps. `false`	default value: false valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"biso","name":"Clientless Web Isolation","domain":"authdomain.cloudflareaccess.com/browser","session_duration":"24h","allowed_idps":["699d98642c564d2e855e9661899b7252"],"auto_redirect_to_identity":false}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "type": "biso",
    "name": "Clientless Web Isolation",
    "domain": "authdomain.cloudflareaccess.com/browser",
    "session_duration": "24h",
    "allowed_idps": [
      "699d98642c564d2e855e9661899b7252"
    ],
    "auto_redirect_to_identity": false,
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893"
  }
}

zone-level-access-applications-update-a-bookmark-application

PUT Update a Bookmark application

Updates a Bookmark application.

PUT zones/:identifier/access/apps/:app_id

Required parameters

Name /type	Description /example	Constraints
type string	The application type `"bookmark"`
name string	The name of the application. `"Admin Site"`
domain string	The URL or domain of the bookmark. `"https://mybookmark.com"`

Optional parameters

Name /type	Description /example	Constraints
logo_url string	The image URL for the logo shown in the App Launcher dashboard. `"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg"`
app_launcher_visible boolean	Displays the application in the App Launcher. `true`	default value: true valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"bookmark","name":"Admin Site","domain":"https://mybookmark.com","logo_url":"https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg","app_launcher_visible":true}'

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",
    "type": "bookmark",
    "name": "Admin Site",
    "domain": "https://mybookmark.com",
    "logo_url": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg",
    "app_launcher_visible": true
  }
}

zone-level-access-applications-delete-an-access-application

DELETE Delete an Access application

Deletes an application from Access.

DELETE zones/:identifier/access/apps/:app_id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
  }
}

zone-level-access-applications-revoke-service-tokens

POST Revoke service tokens

Revokes all service tokens used by an application.

POST zones/:identifier/access/apps/:app_id/revoke_tokens

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252/revoke_tokens" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true
}

zone-level-access-applications-test-access-policies

GET Test Access policies

Tests if a specific user has permission to access an application.

GET zones/:identifier/access/apps/:app_id/user_policy_checks

Required parameters

Name /type	Description /example	Constraints
user_id string	The ID of the user that you want to test with. `"f174e90a-fafe-4643-bbbc-4a0ed4fc8415"`	max length: 36 read only

Optional parameters

Name /type	Description /example	Constraints
ray_id string	The unique identifier for a failed login attempt. The user identity attributes from the request will be added to the test. `"6d76a8a42ead4133"`	read only
user_email string	The email of the user that you want to test with. `"test@email.com"`	read only

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/699d98642c564d2e855e9661899b7252/access/apps/699d98642c564d2e855e9661899b7252/user_policy_checks?user_id=f174e90a-fafe-4643-bbbc-4a0ed4fc8415&ray_id=6d76a8a42ead4133&user_email=test@email.com" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "user_identity": {
      "id": "1164449231815010287495",
      "version": 0,
      "user_uuid": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "name": "Test User",
      "email": "testuser@gmail.com",
      "geo": {
        "country": "US"
      },
      "is_warp": false,
      "is_gateway": false,
      "account_id": "41ecfbb341f033e52b46742756aabb8b",
      "device_sessions": {}
    },
    "app_state": {
      "aud": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe389",
      "app_uid": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "hostname": "test.com",
      "name": "Test App",
      "policies": [
        {
          "decision": "allow",
          "include": [
            {
              "_type": "email",
              "email": "testuser@gmail.com"
            }
          ],
          "exclude": [],
          "require": [],
          "precedence": 0,
          "status": "Success"
        }
      ],
      "status": "Success"
    }
  }
}

Zone-Level Access policies

Access policies define the users or groups who can reach an Access application. (Note: We recommend using the equivalent account-level endpoints at https://api.cloudflare.com/#access-policies-properties. Account APIs provide a broader range of features and are backwards-compatible to zone APIs.)

https://developers.cloudflare.com/access/setting-up-access/configuring-access-policies/

zone-level-access-policies

Object definition

View properties and constraints defined on the object

Show definition

zone-level-access-policies-list-access-policies

GET List Access policies

Lists Access policies configured for an 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: user@example.com" \
     -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": "test@example.com"
          }
        }
      ],
      "exclude": [
        {
          "email": {
            "email": "test@example.com"
          }
        }
      ],
      "require": [
        {
          "email": {
            "email": "test@example.com"
          }
        }
      ],
      "purpose_justification_required": true,
      "purpose_justification_prompt": "Please enter a justification for entering this protected domain.",
      "approval_required": true,
      "approval_groups": [
        {
          "email_addresses": [
            "test1@cloudflare.com",
            "test2@cloudflare.com"
          ],
          "approvals_needed": 1
        },
        {
          "email_list_uuid": "597147a1-976b-4ef2-9af0-81d5d007fc34",
          "approvals_needed": 3
        }
      ]
    }
  ]
}

zone-level-access-policies-get-an-access-policy

GET Get an Access policy

Fetches 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: user@example.com" \
     -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": "test@example.com"
        }
      }
    ],
    "exclude": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "require": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "purpose_justification_required": true,
    "purpose_justification_prompt": "Please enter a justification for entering this protected domain.",
    "approval_required": true,
    "approval_groups": [
      {
        "email_addresses": [
          "test1@cloudflare.com",
          "test2@cloudflare.com"
        ],
        "approvals_needed": 1
      },
      {
        "email_list_uuid": "597147a1-976b-4ef2-9af0-81d5d007fc34",
        "approvals_needed": 3
      }
    ]
  }
}

zone-level-access-policies-create-an-access-policy

POST Create an Access policy

Create a new Access policy for an application.

POST zones/:identifier/access/apps/:uuid/policies

Required parameters

Name /type	Description /example	Constraints
include array	Rules evaluated with an OR logical operator. A user needs to meet only one of the Include rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »
name string	The name of the Access policy. `"Allow devs"`
decision string	The action Access will take if a user matches this policy. `"allow"`	valid values: allow, deny, non_identity, bypass

Optional parameters

Name /type	Description /example	Constraints
require array	Rules evaluated with an AND logical operator. To match the policy, a user must meet all of the Require rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »
precedence integer	The order of execution for this policy. Must be unique for each policy. `1`
purpose_justification_required boolean	Require users to enter a justification when they log in to the application. `true`	default value: false valid values: (true,false)
approval_groups array	Administrators who can approve a temporary authentication request. `[ { "email_addresses": [ "test1@cloudflare.com", "test2@cloudflare.com" ], "approvals_needed": 1 }, { "email_list_uuid": "597147a1-976b-4ef2-9af0-81d5d007fc34", "approvals_needed": 3 } ]` An array with items in the following form: Show definition »
purpose_justification_prompt string	A custom message that will appear on the purpose justification screen. `"Please enter a justification for entering this protected domain."`
exclude array	Rules evaluated with a NOT logical operator. To match the policy, a user cannot meet any of the Exclude rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »
approval_required boolean	Requires the user to request access from an administrator at the start of each session. `true`	default value: false valid values: (true,false)

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"precedence":1,"decision":"allow","name":"Allow devs","include":[{"email":{"email":"test@example.com"}}],"exclude":[{"email":{"email":"test@example.com"}}],"require":[{"email":{"email":"test@example.com"}}],"purpose_justification_required":true,"purpose_justification_prompt":"Please enter a justification for entering this protected domain.","approval_required":true,"approval_groups":[{"email_addresses":["test1@cloudflare.com","test2@cloudflare.com"],"approvals_needed":1},{"email_list_uuid":"597147a1-976b-4ef2-9af0-81d5d007fc34","approvals_needed":3}]}'

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": "test@example.com"
        }
      }
    ],
    "exclude": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "require": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "purpose_justification_required": true,
    "purpose_justification_prompt": "Please enter a justification for entering this protected domain.",
    "approval_required": true,
    "approval_groups": [
      {
        "email_addresses": [
          "test1@cloudflare.com",
          "test2@cloudflare.com"
        ],
        "approvals_needed": 1
      },
      {
        "email_list_uuid": "597147a1-976b-4ef2-9af0-81d5d007fc34",
        "approvals_needed": 3
      }
    ]
  }
}

zone-level-access-policies-update-an-access-policy

PUT Update an Access policy

Update a configured Access policy.

PUT zones/:identifier/access/apps/:uuid/policies/:uuid

Required parameters

Name /type	Description /example	Constraints
include array	Rules evaluated with an OR logical operator. A user needs to meet only one of the Include rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »
name string	The name of the Access policy. `"Allow devs"`
decision string	The action Access will take if a user matches this policy. `"allow"`	valid values: allow, deny, non_identity, bypass

Optional parameters

Name /type	Description /example	Constraints
require array	Rules evaluated with an AND logical operator. To match the policy, a user must meet all of the Require rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »
precedence integer	The order of execution for this policy. Must be unique for each policy. `1`
purpose_justification_required boolean	Require users to enter a justification when they log in to the application. `true`	default value: false valid values: (true,false)
approval_groups array	Administrators who can approve a temporary authentication request. `[ { "email_addresses": [ "test1@cloudflare.com", "test2@cloudflare.com" ], "approvals_needed": 1 }, { "email_list_uuid": "597147a1-976b-4ef2-9af0-81d5d007fc34", "approvals_needed": 3 } ]` An array with items in the following form: Show definition »
purpose_justification_prompt string	A custom message that will appear on the purpose justification screen. `"Please enter a justification for entering this protected domain."`
exclude array	Rules evaluated with a NOT logical operator. To match the policy, a user cannot meet any of the Exclude rules. `[ { "email": { "email": "test@example.com" } } ]` An array with items in the following form: Show definition »
approval_required boolean	Requires the user to request access from an administrator at the start of each session. `true`	default value: false valid values: (true,false)

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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"precedence":1,"decision":"allow","name":"Allow devs","include":[{"email":{"email":"test@example.com"}}],"exclude":[{"email":{"email":"test@example.com"}}],"require":[{"email":{"email":"test@example.com"}}],"purpose_justification_required":true,"purpose_justification_prompt":"Please enter a justification for entering this protected domain.","approval_required":true,"approval_groups":[{"email_addresses":["test1@cloudflare.com","test2@cloudflare.com"],"approvals_needed":1},{"email_list_uuid":"597147a1-976b-4ef2-9af0-81d5d007fc34","approvals_needed":3}]}'

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": "test@example.com"
        }
      }
    ],
    "exclude": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "require": [
      {
        "email": {
          "email": "test@example.com"
        }
      }
    ],
    "purpose_justification_required": true,
    "purpose_justification_prompt": "Please enter a justification for entering this protected domain.",
    "approval_required": true,
    "approval_groups": [
      {
        "email_addresses": [
          "test1@cloudflare.com",
          "test2@cloudflare.com"
        ],
        "approvals_needed": 1
      },
      {
        "email_list_uuid": "597147a1-976b-4ef2-9af0-81d5d007fc34",
        "approvals_needed": 3
      }
    ]
  }
}

zone-level-access-policies-delete-an-access-policy

DELETE Delete an 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: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
  }
}

Zero Trust users

Users enrolled in a Zero Trust organization.

zero-trust-users

Object definition

View properties and constraints defined on the object

Show definition

zero-trust-users-get-users

GET Get users

Gets a list of users for an account.

GET accounts/:identifier/access/users

Optional parameters

Name /type	Description /example	Constraints
seat_type	Whether the user has logged into Access and/or Gateway. `"any"`	valid values: access, gateway, any, all, none
since string (date-time)	The login time on which to begin the query. `"2020-07-01T05:20:00Z"`	read only
until string (date-time)	The login time on which to end the query `"2020-10-01T05:20:00Z"`	read only
offset number	The number of users to skip when displaying results. Must be a multiple of `per_page`. `0`	default value: 0 min value:0
per_page number	The number of users to display. `20`	default value: 20 min value:5 max value:50
direction	The chronological sorting order for the list. `"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/accounts/699d98642c564d2e855e9661899b7252/access/users?seat_type=any&since=2020-07-01T05:20:00Z&until=2020-10-01T05:20:00Z&offset=0&per_page=20&direction=desc&match=all" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f3b12456-80dd-4e89-9f5f-ba3dfff12365",
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z",
      "uid": "9a7806061c88ada191ed06f989cc3dac",
      "name": "Jane Doe",
      "email": "jdoe@example.com",
      "last_successful_login": "2020-07-01T05:20:00Z",
      "access_seat": false,
      "gateway_seat": false,
      "seat_uid": "9a7806061c88ada191ed06f989cc3dac",
      "active_device_count": 2
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 100,
    "count": 1,
    "total_count": 1
  }
}

zero-trust-users-get-failed-logins

GET Get failed logins

Get all failed login attempts for a single user.

GET accounts/:identifier/access/users/:id/failed_logins

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/access/users/f3b12456-80dd-4e89-9f5f-ba3dfff12365/failed_logins" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "expiration": 1644507248,
      "metadata": {
        "app_name": "Test App",
        "aud": "39691c1480a2352a18ece567debc2b32552686cbd38eec0887aa18d5d3f00c04",
        "datetime": "2022-02-02T21:54:34.914Z",
        "ray_id": "6d76a8a42ead4133",
        "user_email": "test@cloudflare.com",
        "user_uuid": "57171132-e453-4ee8-b2a5-8cbaad333207"
      }
    }
  ]
}

Zero Trust accounts

Account for managing Secure Web Gateway policies.

zero-trust-accounts

Object definition

View properties and constraints defined on the object

Show definition

zero-trust-accounts-create-zero-trust-account

POST Create Zero Trust account

Create Zero Trust account with existing cloudflare account

POST accounts/:identifier/gateway

Required parameters

Name /type	Description /example	Constraints
account_id string	Cloudflare account tag `"699d98642c564d2e855e9661899b7252"`	max length: 32

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"account_id":"699d98642c564d2e855e9661899b7252"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "699d98642c564d2e855e9661899b7252",
    "gateway_tag": "f174e90afafe4643bbbc4a0ed4fc8415",
    "provider_name": "Cloudflare"
  }
}

zero-trust-accounts-get-zero-trust-account-information

GET Get Zero Trust account information

Get Zero Trust account information

GET accounts/:identifier/gateway

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "699d98642c564d2e855e9661899b7252",
    "gateway_tag": "f174e90afafe4643bbbc4a0ed4fc8415",
    "provider_name": "Cloudflare"
  }
}

zero-trust-accounts-update-zero-trust-account-configuration

PUT Update Zero Trust account configuration

Updates the current Zero Trust account configuration

PUT accounts/:identifier/gateway/configuration

Optional parameters

Name /type	Description /example	Constraints
settings object	account settings { "antivirus": { "enabled_download_phase": false, "enabled_upload_phase": false, "fail_closed": false }, "tls_decrypt": { "enabled": true }, "activity_log": { "enabled": true }, "block_page": { "enabled": true, "name": "Cloudflare", "footer_text": "--footer--", "header_text": "--header--", "mailto_address": "admin@example.com", "mailto_subject": "Blocked User Inquiry", "logo_path": "https://logos.com/a.png", "background_color": true, "suppress_footer": false }, "browser_isolation": { "url_browser_isolation_enabled": true }, "fips": { "tls": true } } An object with the following properties: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/configuration" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"settings":{"antivirus":{"enabled_download_phase":false,"enabled_upload_phase":false,"fail_closed":false},"tls_decrypt":{"enabled":true},"activity_log":{"enabled":true},"block_page":{"enabled":true,"name":"Cloudflare","footer_text":"--footer--","header_text":"--header--","mailto_address":"admin@example.com","mailto_subject":"Blocked User Inquiry","logo_path":"https://logos.com/a.png","background_color":true,"suppress_footer":false},"browser_isolation":{"url_browser_isolation_enabled":true},"fips":{"tls":true}}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "settings": {
      "antivirus": {
        "enabled_download_phase": false,
        "enabled_upload_phase": false,
        "fail_closed": false
      },
      "tls_decrypt": {
        "enabled": true
      },
      "activity_log": {
        "enabled": true
      },
      "block_page": {
        "enabled": true,
        "name": "Cloudflare",
        "footer_text": "--footer--",
        "header_text": "--header--",
        "mailto_address": "admin@example.com",
        "mailto_subject": "Blocked User Inquiry",
        "logo_path": "https://logos.com/a.png",
        "background_color": true,
        "suppress_footer": false
      },
      "browser_isolation": {
        "url_browser_isolation_enabled": true
      },
      "fips": {
        "tls": true
      }
    },
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z"
  }
}

zero-trust-accounts-get-zero-trust-account-configuration

GET Get Zero Trust account configuration

Describes current Zero Trust account configuration

GET accounts/:identifier/gateway/configuration

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/configuration" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "settings": {
      "antivirus": {
        "enabled_download_phase": false,
        "enabled_upload_phase": false,
        "fail_closed": false
      },
      "tls_decrypt": {
        "enabled": true
      },
      "activity_log": {
        "enabled": true
      },
      "block_page": {
        "enabled": true,
        "name": "Cloudflare",
        "footer_text": "--footer--",
        "header_text": "--header--",
        "mailto_address": "admin@example.com",
        "mailto_subject": "Blocked User Inquiry",
        "logo_path": "https://logos.com/a.png",
        "background_color": true,
        "suppress_footer": false
      },
      "browser_isolation": {
        "url_browser_isolation_enabled": true
      },
      "fips": {
        "tls": true
      }
    },
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z"
  }
}

zero-trust-accounts-update-device-settings-for-the-zero-trust-account

PUT Update device settings for the Zero Trust account

Updates the current device settings for Zero Trust account

PUT accounts/:identifier/devices/settings

Optional parameters

Name /type	Description /example	Constraints
gateway_proxy_enabled boolean	Enable gateway proxy filtering on TCP `true`	valid values: (true,false)
gateway_udp_proxy_enabled boolean	Enable gateway proxy filtering on UDP `true`	valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/settings" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"gateway_proxy_enabled":true,"gateway_udp_proxy_enabled":true}'

Response (example)

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

zero-trust-accounts-get-device-settings-for-zero-trust-account

GET Get device settings for Zero Trust account

Describes the current device settings Zero Trust account

GET accounts/:identifier/devices/settings

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/settings" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

zero-trust-accounts-update-logging-settings-for-the-zero-trust-account

PUT Update logging settings for the Zero Trust account

Updates the current logging settings for the Zero Trust accounty

PUT accounts/:identifier/gateway/logging

Optional parameters

Name /type	Description /example	Constraints
settings_by_rule_type object	Logging settings by rule type `{ "dns": { "log_all": false, "log_blocks": true }, "l4": { "log_all": false, "log_blocks": true }, "http": { "log_all": false, "log_blocks": true } }` An object with the following properties: Show definition »
redact_pii boolean	Redact personally identifiable information from activity logging (PII fields are: source IP, user email, user ID, device ID, URL, referrer, user agent) `true`	valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/logging" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"settings_by_rule_type":{"dns":{"log_all":false,"log_blocks":true},"l4":{"log_all":false,"log_blocks":true},"http":{"log_all":false,"log_blocks":true}},"redact_pii":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "settings_by_rule_type": {
      "dns": {
        "log_all": false,
        "log_blocks": true
      },
      "l4": {
        "log_all": false,
        "log_blocks": true
      },
      "http": {
        "log_all": false,
        "log_blocks": true
      }
    },
    "redact_pii": true
  }
}

zero-trust-accounts-get-logging-settings-for-the-zero-trust-account

GET Get logging settings for the Zero Trust account

Describes the current logging settings for Zero Trust account

GET accounts/:identifier/gateway/logging

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/logging" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "settings_by_rule_type": {
      "dns": {
        "log_all": false,
        "log_blocks": true
      },
      "l4": {
        "log_all": false,
        "log_blocks": true
      },
      "http": {
        "log_all": false,
        "log_blocks": true
      }
    },
    "redact_pii": true
  }
}

Zero Trust Lists

Lists are referenced when creating Secure Web Gateway policies.

zero-trust-lists

Object definition

View properties and constraints defined on the object

Show definition

zero-trust-lists-list-zero-trust-lists

GET List Zero Trust Lists

List Zero Trust Lists for an account

GET accounts/:identifier/gateway/lists

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/lists" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "name": "Admin Serial Numbers",
      "description": "The serial numbers for administrators",
      "type": "SERIAL",
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z",
      "count": 20
    }
  ]
}

zero-trust-lists-zero-trust-list-details

GET Zero Trust List Details

Fetch a single Zero Trust List

GET accounts/:identifier/gateway/lists/:uuid

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/lists/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "Admin Serial Numbers",
    "description": "The serial numbers for administrators",
    "type": "SERIAL",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "count": 20
  }
}

zero-trust-lists-zero-trust-list-items

GET Zero Trust List Items

Fetch all items of a single Zero Trust List

GET accounts/:identifier/gateway/lists/:uuid/items

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 `50`	default value: 50 min value:5 max value:1000

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/lists/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/items?page=1&per_page=50" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    [
      {
        "value": "8GE8721REF",
        "created_at": "2014-01-01T05:20:00.12345Z"
      }
    ]
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 2000
  }
}

zero-trust-lists-create-zero-trust-list

POST Create Zero Trust List

Create a new Zero Trust List

POST accounts/:identifier/gateway/lists

Required parameters

Name /type	Description /example	Constraints
name string	The name of the List. `"Admin Serial Numbers"`
type string	The type of List. `"SERIAL"`	valid values: SERIAL, URL, DOMAIN, EMAIL, IP

Optional parameters

Name /type	Description /example	Constraints
description string	The description of the List `"The serial numbers for administrators"`
items array	The items in the List. `[ { "value": "8GE8721REF", "created_at": "2014-01-01T05:20:00.12345Z" } ]` An array with items in the following form: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/lists" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Admin Serial Numbers","description":"The serial numbers for administrators","type":"SERIAL","items":[{"value":"8GE8721REF","created_at":"2014-01-01T05:20:00.12345Z"}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "Admin Serial Numbers",
    "description": "The serial numbers for administrators",
    "type": "SERIAL",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "items": [
      {
        "value": "8GE8721REF",
        "created_at": "2014-01-01T05:20:00.12345Z"
      }
    ]
  }
}

zero-trust-lists-update-zero-trust-list

PUT Update Zero Trust List

Update a configured Zero Trust List

PUT accounts/:identifier/gateway/lists/:uuid

Required parameters

Name /type	Description /example	Constraints
name string	The name of the List. `"Admin Serial Numbers"`

Optional parameters

Name /type	Description /example	Constraints
description string	The description of the List `"The serial numbers for administrators"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/lists/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Admin Serial Numbers","description":"The serial numbers for administrators"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "Admin Serial Numbers",
    "description": "The serial numbers for administrators",
    "type": "SERIAL",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "count": 20
  }
}

zero-trust-lists-patch-zero-trust-list

PATCH Patch Zero Trust List

Append or remove an item from a configured Zero Trust List

PATCH accounts/:identifier/gateway/lists/:uuid

Optional parameters

Name /type	Description /example	Constraints
append array	The items in the List. `[ { "value": "8GE8721REF", "created_at": "2014-01-01T05:20:00.12345Z" } ]` An array with items in the following form: Show definition »
remove array	A list of the item values you want to remove. `[ "8GE8721REF" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/lists/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"append":[{"value":"8GE8721REF","created_at":"2014-01-01T05:20:00.12345Z"}],"remove":["8GE8721REF"]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "Admin Serial Numbers",
    "description": "The serial numbers for administrators",
    "type": "SERIAL",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "count": 20
  }
}

zero-trust-lists-delete-zero-trust-list

DELETE Delete Zero Trust List

Delete a Zero Trust List

DELETE accounts/:identifier/gateway/lists/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/lists/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Zero Trust Gateway Locations

Locations are a collection of resources like network ranges or destination IPs that can map to a physical location like an office and are used when creating Zero Trust Gateway Resolver DNS policies

zero-trust-gateway-locations

Object definition

View properties and constraints defined on the object

Show definition

zero-trust-gateway-locations-list-zero-trust-gateway-locations

GET List Zero Trust Gateway Locations

List Zero Trust Gateway Locations for an account

GET accounts/:identifier/gateway/locations

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/locations" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "ed35569b41ce4d1facfe683550f54086",
      "name": "Austin Office Location",
      "ip": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
      "networks": [
        "192.0.2.1"
      ],
      "doh_subdomain": "oli3n9zkz5",
      "client_default": false,
      "ecs_support": false,
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z"
    }
  ]
}

zero-trust-gateway-locations-zero-trust-gateway-location-details

GET Zero Trust Gateway Location Details

Fetch a single Zero Trust Gateway Location

GET accounts/:identifier/gateway/locations/:uuid

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/locations/ed35569b41ce4d1facfe683550f54086" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "ed35569b41ce4d1facfe683550f54086",
    "name": "Austin Office Location",
    "ip": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
    "networks": [
      "192.0.2.1"
    ],
    "doh_subdomain": "oli3n9zkz5",
    "client_default": false,
    "ecs_support": false,
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z"
  }
}

zero-trust-gateway-locations-create-zero-trust-gateway-location

POST Create Zero Trust Gateway Location

Create a new Zero Trust Gateway Location

POST accounts/:identifier/gateway/locations

Required parameters

Name /type	Description /example	Constraints
name string	The name of the Location `"Austin Office Location"`

Optional parameters

Name /type	Description /example	Constraints
networks array	A list of network ranges that requests from this location would originate from `[ "192.0.2.1" ]` An array with items in the following form: Show definition »
client_default boolean	Set if the location is the default one `false`	valid values: (true,false)
ecs_support boolean	Set if the location needs to resolve EDNS queries `false`	valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/locations" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Austin Office Location","networks":["192.0.2.1"],"client_default":false,"ecs_support":false}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "ed35569b41ce4d1facfe683550f54086",
    "name": "Austin Office Location",
    "ip": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
    "networks": [
      "192.0.2.1"
    ],
    "doh_subdomain": "oli3n9zkz5",
    "client_default": false,
    "ecs_support": false,
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z"
  }
}

zero-trust-gateway-locations-update-zero-trust-gateway-location

PUT Update Zero Trust Gateway Location

Update a configured Zero Trust Gateway Location

PUT accounts/:identifier/gateway/locations/:uuid

Required parameters

Name /type	Description /example	Constraints
name string	The name of the Location `"Austin Office Location"`

Optional parameters

Name /type	Description /example	Constraints
networks array	A list of network ranges that requests from this location would originate from `[ "192.0.2.1" ]` An array with items in the following form: Show definition »
client_default boolean	Set if the location is the default one `false`	valid values: (true,false)
ecs_support boolean	Set if the location needs to resolve EDNS queries `false`	valid values: (true,false)

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/locations/ed35569b41ce4d1facfe683550f54086" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Austin Office Location","networks":["192.0.2.1"],"client_default":false,"ecs_support":false}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "ed35569b41ce4d1facfe683550f54086",
    "name": "Austin Office Location",
    "ip": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
    "networks": [
      "192.0.2.1"
    ],
    "doh_subdomain": "oli3n9zkz5",
    "client_default": false,
    "ecs_support": false,
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z"
  }
}

zero-trust-gateway-locations-delete-zero-trust-gateway-location

DELETE Delete Zero Trust Gateway Location

Delete a Zero Trust Gateway Location

DELETE accounts/:identifier/gateway/locations/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/locations/ed35569b41ce4d1facfe683550f54086" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Zero Trust Gateway Rules

Secure Web Gateway rules are a set of expressions(conditions) that evaluate at various phases of your internet traffic, to determine if a specific action has to be performed. These expressions can be evaluated to a true/false value and based on the evaluation result, an associated action, like whether to reject the request, or allow it, or override it, or browser isolate it is applied.

zero-trust-gateway-rules

Object definition

View properties and constraints defined on the object

Show definition

zero-trust-gateway-rules-list-zero-trust-gateway-rules

GET List Zero Trust Gateway Rules

List Zero Trust Gateway Rules for an account

GET accounts/:identifier/gateway/rules

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/rules" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "name": "block bad websites",
      "description": "Block the bad websites based on host name",
      "precedence": 1,
      "enabled": true,
      "action": "allow",
      "filters": [
        "http"
      ],
      "traffic": "http.request.uri matches \".*a/partial/uri.*\" and http.request.host in $01302951-49f9-47c9-a400-0297e60b6a10",
      "identity": "any(identity.groups.name[*] in {\"finance\"})",
      "device_posture": "any(device_posture.checks.passed[*] in {\"1308749e-fcfb-4ebc-b051-fe022b632644\"})",
      "rule_settings": {
        "block_page_enabled": true,
        "block_reason": "This website is a security risk",
        "override_host": "example.com",
        "override_ips": [
          "1.1.1.1",
          "2.2.2.2"
        ],
        "l4override": {
          "ip": "1.1.1.1",
          "port": 80
        },
        "add_headers": {
          "X-Custom-Header-Name": [
            "somecustomvalue"
          ],
          "My-Next-Header": [
            "foo",
            "bar"
          ]
        },
        "ip_categories": true,
        "biso_admin_controls": {
          "dp": false,
          "dcp": false,
          "dd": false,
          "du": false,
          "dk": false
        },
        "check_session": {
          "enforce": true,
          "duration": "300s"
        },
        "insecure_disable_dnssec_validation": false
      },
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z",
      "deleted_at": null
    }
  ]
}

zero-trust-gateway-rules-zero-trust-gateway-rule-details

GET Zero Trust Gateway Rule Details

Fetch a single Zero Trust Gateway Rule

GET accounts/:identifier/gateway/rules/:uuid

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/rules/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "block bad websites",
    "description": "Block the bad websites based on host name",
    "precedence": 1,
    "enabled": true,
    "action": "allow",
    "filters": [
      "http"
    ],
    "traffic": "http.request.uri matches \".*a/partial/uri.*\" and http.request.host in $01302951-49f9-47c9-a400-0297e60b6a10",
    "identity": "any(identity.groups.name[*] in {\"finance\"})",
    "device_posture": "any(device_posture.checks.passed[*] in {\"1308749e-fcfb-4ebc-b051-fe022b632644\"})",
    "rule_settings": {
      "block_page_enabled": true,
      "block_reason": "This website is a security risk",
      "override_host": "example.com",
      "override_ips": [
        "1.1.1.1",
        "2.2.2.2"
      ],
      "l4override": {
        "ip": "1.1.1.1",
        "port": 80
      },
      "add_headers": {
        "X-Custom-Header-Name": [
          "somecustomvalue"
        ],
        "My-Next-Header": [
          "foo",
          "bar"
        ]
      },
      "ip_categories": true,
      "biso_admin_controls": {
        "dp": false,
        "dcp": false,
        "dd": false,
        "du": false,
        "dk": false
      },
      "check_session": {
        "enforce": true,
        "duration": "300s"
      },
      "insecure_disable_dnssec_validation": false
    },
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "deleted_at": null
  }
}

zero-trust-gateway-rules-create-zero-trust-gateway-rule

POST Create Zero Trust Gateway Rule

Create a new Zero Trust Gateway Rule

POST accounts/:identifier/gateway/rules

Required parameters

Name /type	Description /example	Constraints
name string	The name of the Rule. `"block bad websites"`
action string	The action to preform when the associated traffic, identity, and device posture expressions are either absent or evaluate to 'true' `"allow"`	valid values: on, off, allow, block, scan, noscan, safesearch, ytrestricted, isolate, noisolate, override, l4_override

Optional parameters

Name /type	Description /example	Constraints
enabled boolean	Set if the rule is enabled `true`	valid values: (true,false)
rule_settings object	Additional settings that modify the rule's action { "block_page_enabled": true, "block_reason": "This website is a security risk", "override_host": "example.com", "override_ips": [ "1.1.1.1", "2.2.2.2" ], "l4override": { "ip": "1.1.1.1", "port": 80 }, "add_headers": { "X-Custom-Header-Name": [ "somecustomvalue" ], "My-Next-Header": [ "foo", "bar" ] }, "ip_categories": true, "biso_admin_controls": { "dp": false, "dcp": false, "dd": false, "du": false, "dk": false }, "check_session": { "enforce": true, "duration": "300s" }, "insecure_disable_dnssec_validation": false } An object with the following properties: Show definition »
precedence integer	Precedence sets the ordering of the rules. Lower values indicate higher precedence. At each processing phase, applicable rules are evaluated in ascending order of this value. `1`
filters array	The protocol or layer to evaluate the traffic, identity, and device posture expressions `[ "http" ]` An array with items in the following form: Show definition »
description string	The description of the Rule `"Block the bad websites based on host name"`
traffic string	The wirefilter expression to be used for traffic matching `"http.request.uri matches \".a/partial/uri.\" and http.request.host in $01302951-49f9-47c9-a400-0297e60b6a10"`
identity string	The wirefilter expression to be used for identity matching `"any(identity.groups.name[*] in {\"finance\"})"`
device_posture string	The wirefilter expression to be used for device posture check matching `"any(device_posture.checks.passed[*] in {\"1308749e-fcfb-4ebc-b051-fe022b632644\"})"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/rules" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"block bad websites","description":"Block the bad websites based on host name","action":"allow","filters":["http"],"enabled":true,"precedence":1,"traffic":"http.request.uri matches \".*a/partial/uri.*\" and http.request.host in $01302951-49f9-47c9-a400-0297e60b6a10","identity":"any(identity.groups.name[*] in {\"finance\"})","device_posture":"any(device_posture.checks.passed[*] in {\"1308749e-fcfb-4ebc-b051-fe022b632644\"})","rule_settings":{"block_page_enabled":true,"block_reason":"This website is a security risk","override_host":"example.com","override_ips":["1.1.1.1","2.2.2.2"],"l4override":{"ip":"1.1.1.1","port":80},"add_headers":{"X-Custom-Header-Name":["somecustomvalue"],"My-Next-Header":["foo","bar"]},"ip_categories":true,"biso_admin_controls":{"dp":false,"dcp":false,"dd":false,"du":false,"dk":false},"check_session":{"enforce":true,"duration":"300s"},"insecure_disable_dnssec_validation":false}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "block bad websites",
    "description": "Block the bad websites based on host name",
    "precedence": 1,
    "enabled": true,
    "action": "allow",
    "filters": [
      "http"
    ],
    "traffic": "http.request.uri matches \".*a/partial/uri.*\" and http.request.host in $01302951-49f9-47c9-a400-0297e60b6a10",
    "identity": "any(identity.groups.name[*] in {\"finance\"})",
    "device_posture": "any(device_posture.checks.passed[*] in {\"1308749e-fcfb-4ebc-b051-fe022b632644\"})",
    "rule_settings": {
      "block_page_enabled": true,
      "block_reason": "This website is a security risk",
      "override_host": "example.com",
      "override_ips": [
        "1.1.1.1",
        "2.2.2.2"
      ],
      "l4override": {
        "ip": "1.1.1.1",
        "port": 80
      },
      "add_headers": {
        "X-Custom-Header-Name": [
          "somecustomvalue"
        ],
        "My-Next-Header": [
          "foo",
          "bar"
        ]
      },
      "ip_categories": true,
      "biso_admin_controls": {
        "dp": false,
        "dcp": false,
        "dd": false,
        "du": false,
        "dk": false
      },
      "check_session": {
        "enforce": true,
        "duration": "300s"
      },
      "insecure_disable_dnssec_validation": false
    },
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "deleted_at": null
  }
}

zero-trust-gateway-rules-update-zero-trust-gateway-rule

PUT Update Zero Trust Gateway Rule

Update a configured Zero Trust Gateway Rule

PUT accounts/:identifier/gateway/rules/:uuid

Required parameters

Name /type	Description /example	Constraints
name string	The name of the Rule. `"block bad websites"`
action string	The action to preform when the associated traffic, identity, and device posture expressions are either absent or evaluate to 'true' `"allow"`	valid values: on, off, allow, block, scan, noscan, safesearch, ytrestricted, isolate, noisolate, override, l4_override

Optional parameters

Name /type	Description /example	Constraints
enabled boolean	Set if the rule is enabled `true`	valid values: (true,false)
rule_settings object	Additional settings that modify the rule's action { "block_page_enabled": true, "block_reason": "This website is a security risk", "override_host": "example.com", "override_ips": [ "1.1.1.1", "2.2.2.2" ], "l4override": { "ip": "1.1.1.1", "port": 80 }, "add_headers": { "X-Custom-Header-Name": [ "somecustomvalue" ], "My-Next-Header": [ "foo", "bar" ] }, "ip_categories": true, "biso_admin_controls": { "dp": false, "dcp": false, "dd": false, "du": false, "dk": false }, "check_session": { "enforce": true, "duration": "300s" }, "insecure_disable_dnssec_validation": false } An object with the following properties: Show definition »
precedence integer	Precedence sets the ordering of the rules. Lower values indicate higher precedence. At each processing phase, applicable rules are evaluated in ascending order of this value. `1`
filters array	The protocol or layer to evaluate the traffic, identity, and device posture expressions `[ "http" ]` An array with items in the following form: Show definition »
description string	The description of the Rule `"Block the bad websites based on host name"`
traffic string	The wirefilter expression to be used for traffic matching `"http.request.uri matches \".a/partial/uri.\" and http.request.host in $01302951-49f9-47c9-a400-0297e60b6a10"`
identity string	The wirefilter expression to be used for identity matching `"any(identity.groups.name[*] in {\"finance\"})"`
device_posture string	The wirefilter expression to be used for device posture check matching `"any(device_posture.checks.passed[*] in {\"1308749e-fcfb-4ebc-b051-fe022b632644\"})"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/rules/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"block bad websites","description":"Block the bad websites based on host name","action":"allow","filters":["http"],"enabled":true,"precedence":1,"traffic":"http.request.uri matches \".*a/partial/uri.*\" and http.request.host in $01302951-49f9-47c9-a400-0297e60b6a10","identity":"any(identity.groups.name[*] in {\"finance\"})","device_posture":"any(device_posture.checks.passed[*] in {\"1308749e-fcfb-4ebc-b051-fe022b632644\"})","rule_settings":{"block_page_enabled":true,"block_reason":"This website is a security risk","override_host":"example.com","override_ips":["1.1.1.1","2.2.2.2"],"l4override":{"ip":"1.1.1.1","port":80},"add_headers":{"X-Custom-Header-Name":["somecustomvalue"],"My-Next-Header":["foo","bar"]},"ip_categories":true,"biso_admin_controls":{"dp":false,"dcp":false,"dd":false,"du":false,"dk":false},"check_session":{"enforce":true,"duration":"300s"},"insecure_disable_dnssec_validation":false}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "block bad websites",
    "description": "Block the bad websites based on host name",
    "precedence": 1,
    "enabled": true,
    "action": "allow",
    "filters": [
      "http"
    ],
    "traffic": "http.request.uri matches \".*a/partial/uri.*\" and http.request.host in $01302951-49f9-47c9-a400-0297e60b6a10",
    "identity": "any(identity.groups.name[*] in {\"finance\"})",
    "device_posture": "any(device_posture.checks.passed[*] in {\"1308749e-fcfb-4ebc-b051-fe022b632644\"})",
    "rule_settings": {
      "block_page_enabled": true,
      "block_reason": "This website is a security risk",
      "override_host": "example.com",
      "override_ips": [
        "1.1.1.1",
        "2.2.2.2"
      ],
      "l4override": {
        "ip": "1.1.1.1",
        "port": 80
      },
      "add_headers": {
        "X-Custom-Header-Name": [
          "somecustomvalue"
        ],
        "My-Next-Header": [
          "foo",
          "bar"
        ]
      },
      "ip_categories": true,
      "biso_admin_controls": {
        "dp": false,
        "dcp": false,
        "dd": false,
        "du": false,
        "dk": false
      },
      "check_session": {
        "enforce": true,
        "duration": "300s"
      },
      "insecure_disable_dnssec_validation": false
    },
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z",
    "deleted_at": null
  }
}

zero-trust-gateway-rules-delete-zero-trust-gateway-rule

DELETE Delete Zero Trust Gateway Rule

Delete a Zero Trust Gateway Rule

DELETE accounts/:identifier/gateway/rules/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/rules/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Zero Trust Gateway Application and Application Type mappings

Applications are a way to group domains, IP CIDRs, and port numbers under a single identifier. This applies operations performed on network traffic to all application members. Application Types are a way to group different Applications together. Application IDs and Application Type IDs can be provided as part of the 'traffic' wirefilter expression in Secure Web Gateway rules.

zero-trust-gateway-application-and-application-type-mappings

Object definitions

View properties and constraints defined on the object

Show definitions

zero-trust-gateway-application-and-application-type-mappings-list-application-and-application-type-mappings

GET List Application and Application Type mappings

List all Application and Application Type mappings

GET accounts/:identifier/gateway/app_types

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/gateway/app_types" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": 554,
      "name": "Facebook",
      "created_at": "2014-01-01T05:20:00.12345Z",
      "application_type_id": 11
    }
  ]
}

Zero Trust Gateway Categories

Categories are a way of classifying domains and IP addresses into semantic groups. Category IDs can be matched on as part of the 'traffic' wirefilter expression in Secure Web Gateway Rules.

zero-trust-gateway-categories

Object definition

View properties and constraints defined on the object

Show definition

GET List Categories

List all Categories

GET accounts/:account_id/gateway/categories

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/gateway/categories" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "name": "Education",
      "id": 90,
      "description": "Sites related to educational content that are not included in other categories like Science, Technology or Educational institutions.",
      "class": "premium",
      "beta": false,
      "subcategories": [
        {
          "name": "Education",
          "id": 90,
          "description": "Sites related to educational content that are not included in other categories like Science, Technology or Educational institutions.",
          "class": "premium",
          "beta": false
        }
      ]
    }
  ]
}

Zero Trust Gateway Proxy Endpoints

Proxy Endpoints are domains that HTTPS proxy clients can be pointed at to secure traffic.

zero-trust-gateway-proxy-endpoints

Object definition

View properties and constraints defined on the object

Show definition

zero-trust-gateway-proxy-endpoints-proxy-endpoint-details

GET Proxy Endpoint Details

List Zero Trust Gateway Proxy Endpoints for an account

GET accounts/:identifier/gateway/proxy_endpoints/:uuid

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/proxy_endpoints/ed35569b41ce4d1facfe683550f54086" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "ed35569b41ce4d1facfe683550f54086",
    "name": "Devops team",
    "ips": [
      "192.0.2.1/32"
    ],
    "subdomain": "oli3n9zkz5.proxy.cloudflare-gateway.com",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z"
  }
}

zero-trust-gateway-proxy-endpoints-list-proxy-endpoints

GET List Proxy Endpoints

Fetch a single Zero Trust Gateway Proxy Endpoint

GET accounts/:identifier/gateway/proxy_endpoints

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/proxy_endpoints" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "ed35569b41ce4d1facfe683550f54086",
      "name": "Devops team",
      "ips": [
        "192.0.2.1/32"
      ],
      "subdomain": "oli3n9zkz5.proxy.cloudflare-gateway.com",
      "created_at": "2014-01-01T05:20:00.12345Z",
      "updated_at": "2014-01-01T05:20:00.12345Z"
    }
  ]
}

zero-trust-gateway-proxy-endpoints-create-proxy-endpoint

POST Create Proxy Endpoint

Create a new Zero Trust Gateway Proxy Endpoint

POST accounts/:identifier/gateway/proxy_endpoints

Required parameters

Name /type	Description /example	Constraints
name string	The name of the Proxy Endpoint `"Devops team"`
ips array	A list of CIDRs to restrict ingress connections `[ "192.0.2.1/32" ]` An array with items in the following form: Show definition »

Optional parameters

Name /type	Description /example	Constraints
subdomain string	The subdomain to be used as the destination in the proxy client. `"oli3n9zkz5.proxy.cloudflare-gateway.com"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/proxy_endpoints" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Devops team","ips":["192.0.2.1/32"],"subdomain":"oli3n9zkz5.proxy.cloudflare-gateway.com"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "ed35569b41ce4d1facfe683550f54086",
    "name": "Devops team",
    "ips": [
      "192.0.2.1/32"
    ],
    "subdomain": "oli3n9zkz5.proxy.cloudflare-gateway.com",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z"
  }
}

zero-trust-gateway-proxy-endpoints-update-proxy-endpoint

PATCH Update Proxy Endpoint

Update a new Zero Trust Gateway Proxy Endpoint

PATCH accounts/:identifier/gateway/proxy_endpoints/:uuid

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the Proxy Endpoint `"Devops team"`
ips array	A list of CIDRs to restrict ingress connections `[ "192.0.2.1/32" ]` An array with items in the following form: Show definition »
subdomain string	The subdomain to be used as the destination in the proxy client. `"oli3n9zkz5.proxy.cloudflare-gateway.com"`

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/proxy_endpoints/ed35569b41ce4d1facfe683550f54086" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Devops team","ips":["192.0.2.1/32"],"subdomain":"oli3n9zkz5.proxy.cloudflare-gateway.com"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "ed35569b41ce4d1facfe683550f54086",
    "name": "Devops team",
    "ips": [
      "192.0.2.1/32"
    ],
    "subdomain": "oli3n9zkz5.proxy.cloudflare-gateway.com",
    "created_at": "2014-01-01T05:20:00.12345Z",
    "updated_at": "2014-01-01T05:20:00.12345Z"
  }
}

zero-trust-gateway-proxy-endpoints-delete-proxy-endpoint

DELETE Delete Proxy Endpoint

Delete a Zero Trust Gateway Proxy Endpoint

DELETE accounts/:identifier/gateway/proxy_endpoints/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/gateway/proxy_endpoints/ed35569b41ce4d1facfe683550f54086" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Device Posture Rules

Device posture rules configure security policies for device posture checks.

device-posture-rules

Object definition

View properties and constraints defined on the object

Show definition

device-posture-rules-list-device-posture-rules

GET List Device Posture Rules

List Device Posture Rules for an account

GET accounts/:identifier/devices/posture

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/posture" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "type": "file",
      "name": "Admin Serial Numbers",
      "description": "The rule for admin serial numbers",
      "schedule": "1h",
      "match": [
        {
          "platform": "windows"
        }
      ],
      "input": {
        "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
      },
      "expiration": "1h"
    }
  ]
}

device-posture-rules-device-posture-rules-details

GET Device Posture Rules Details

Fetch a single Device Posture Rule

GET accounts/:identifier/devices/posture/:uuid

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/posture/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "type": "file",
    "name": "Admin Serial Numbers",
    "description": "The rule for admin serial numbers",
    "schedule": "1h",
    "match": [
      {
        "platform": "windows"
      }
    ],
    "input": {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
    },
    "expiration": "1h"
  }
}

device-posture-rules-create-device-posture-rule

POST Create Device Posture Rule

Create a new Device Posture Rule

POST accounts/:identifier/devices/posture

Required parameters

Name /type	Description /example	Constraints
type string	The type of Device Posture Rule. `"file"`	valid values: file, application, serial_number, tanium, gateway, warp
name string	The name of the Device Posture Rule. `"Admin Serial Numbers"`

Optional parameters

Name /type	Description /example	Constraints
description string	The description of the Device Posture Rule `"The rule for admin serial numbers"`
schedule string	Tells the client when to run the device posture check. `"1h"`
match array	The conditions that the client must match to run the rule. `[ { "platform": "windows" } ]` An array with items in the following form: Show definition »
input object	The value to be checked against. `{ "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415" }` An object with the following properties: Show definition »
expiration string	Expire posture results after the specified amount of time. `"1h"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/posture" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"file","name":"Admin Serial Numbers","description":"The rule for admin serial numbers","schedule":"1h","match":[{"platform":"windows"}],"input":{"id":"f174e90a-fafe-4643-bbbc-4a0ed4fc8415"},"expiration":"1h"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "type": "file",
    "name": "Admin Serial Numbers",
    "description": "The rule for admin serial numbers",
    "schedule": "1h",
    "match": [
      {
        "platform": "windows"
      }
    ],
    "input": {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
    },
    "expiration": "1h"
  }
}

device-posture-rules-update-device-posture-rule

PUT Update Device Posture Rule

Update a Device Posture Rule

PUT accounts/:identifier/devices/posture/:uuid

Required parameters

Name /type	Description /example	Constraints
type string	The type of Device Posture Rule. `"file"`	valid values: file, application, serial_number, tanium, gateway, warp
name string	The name of the Device Posture Rule. `"Admin Serial Numbers"`

Optional parameters

Name /type	Description /example	Constraints
description string	The description of the Device Posture Rule `"The rule for admin serial numbers"`
schedule string	Tells the client when to run the device posture check. `"1h"`
match array	The conditions that the client must match to run the rule. `[ { "platform": "windows" } ]` An array with items in the following form: Show definition »
input object	The value to be checked against. `{ "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415" }` An object with the following properties: Show definition »
expiration string	Expire posture results after the specified amount of time. `"1h"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/posture/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"file","name":"Admin Serial Numbers","description":"The rule for admin serial numbers","schedule":"1h","match":[{"platform":"windows"}],"input":{"id":"f174e90a-fafe-4643-bbbc-4a0ed4fc8415"},"expiration":"1h"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "type": "file",
    "name": "Admin Serial Numbers",
    "description": "The rule for admin serial numbers",
    "schedule": "1h",
    "match": [
      {
        "platform": "windows"
      }
    ],
    "input": {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
    },
    "expiration": "1h"
  }
}

device-posture-rules-delete-device-posture-rule

DELETE Delete Device Posture Rule

Delete a Device Posture Rule

DELETE accounts/:identifier/devices/posture/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/posture/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
  }
}

Devices

Manage devices enrolled in Cloudflare for Teams.

devices

Object definition

View properties and constraints defined on the object

Show definition

devices-list-devices

GET List Devices

List Enrolled Devices

GET accounts/:identifier/devices

Optional parameters

Name /type	Description /example	Constraints
deviceName string	The device name. `"MyPhone"`
match	Return results matching any or all of the provided search parameters. `"any"`	default value: any valid values: any, all
order_by	The device field to order by. `"created"`	default value: created valid values: id, userName, deviceName, email, type, version, updated, created, last_seen
start_date string (date-time)	The earliest date used to find devices whose last_seen field falls within that date range. `"2017-06-14T00:00:00Z"`
end_date string (date-time)	The latest date used to find devices whose last_seen field falls within that date range. `"2017-06-14T00:00:00Z"`
userName string	The device user's name as defined by the configured Access IDP. `"John"`
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. `"MjAyMS0xMC0xOVQyMDo1MDoyNS41NDU5NDda.L2KKczEeEeynSvpH_4kcCQ"`
version string	The WARP client version. `"1.0.0"`
type string	`"windows"`	valid values: windows, mac, linux, android, ios
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. `20`	default value: 20 max value:100
email string	The contact email address of the user. `"user@example.com"`	max length: 90
direction	The direction to sort device results. `"desc"`	default value: desc valid values: asc, desc

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices?limit=20&cursor=MjAyMS0xMC0xOVQyMDo1MDoyNS41NDU5NDda.L2KKczEeEeynSvpH_4kcCQ&start_date=2017-06-14T00:00:00Z&end_date=2017-06-14T00:00:00Z&order_by=created&direction=desc&deviceName=MyPhone&userName=John&email=user@example.com&type=windows&version=1.0.0&match=any" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "user": {
        "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
        "name": "John Appleseed",
        "email": "user@example.com"
      },
      "key": "yek0SUYoOQ10vMGsIYAevozXUQpQtNFJFfFGqER/BGc=",
      "device_type": "windows",
      "name": "My mobile device",
      "model": "MyPhone(pro-X)",
      "manufacturer": "My phone corp",
      "deleted": true,
      "version": "1.0.0",
      "serial_number": "EXAMPLEHMD6R",
      "os_version": "10.0.0",
      "os_distro_name": "ubuntu",
      "os_distro_revision": "1.0.0",
      "mac_address": "00-00-5E-00-53-00",
      "ip": "1.1.1.1",
      "created": "2017-06-14T00:00:00Z",
      "updated": "2017-06-14T00:00:00Z",
      "last_seen": "2017-06-14T00:00:00Z",
      "revoked_at": "2017-06-14T00:00:00Z"
    }
  ]
}

devices-device-details

GET Device Details

Fetch a single Device

GET accounts/:identifier/devices/:uuid

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "user": {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "name": "John Appleseed",
      "email": "user@example.com"
    },
    "key": "yek0SUYoOQ10vMGsIYAevozXUQpQtNFJFfFGqER/BGc=",
    "device_type": "windows",
    "name": "My mobile device",
    "model": "MyPhone(pro-X)",
    "manufacturer": "My phone corp",
    "deleted": true,
    "version": "1.0.0",
    "serial_number": "EXAMPLEHMD6R",
    "os_version": "10.0.0",
    "os_distro_name": "ubuntu",
    "os_distro_revision": "1.0.0",
    "mac_address": "00-00-5E-00-53-00",
    "ip": "1.1.1.1",
    "created": "2017-06-14T00:00:00Z",
    "updated": "2017-06-14T00:00:00Z",
    "last_seen": "2017-06-14T00:00:00Z",
    "revoked_at": "2017-06-14T00:00:00Z"
  }
}

devices-revoke-devices

POST Revoke Devices

Revoke a list of devices

POST accounts/:identifier/devices/revoke

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/revoke" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '["f174e90a-fafe-4643-bbbc-4a0ed4fc8415"]'

Response (example)

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

devices-unrevoke-devices

POST Unrevoke Devices

Unrevoke a list of devices

POST accounts/:identifier/devices/unrevoke

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/unrevoke" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '["f174e90a-fafe-4643-bbbc-4a0ed4fc8415"]'

Response (example)

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

devices-list-admin-override-code-for-device

GET List Admin Override code for device

Fetch one-time use admin override code for a device. This relies on the Admin Override setting being enabled in your device configuration.

GET accounts/:identifier/devices/:uuid/override_codes

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/f174e90a-fafe-4643-bbbc-4a0ed4fc8415/override_codes" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "disable_for_time": {
      "1": "9106681",
      "3": "5356247",
      "6": "9478972",
      "12": "3424359",
      "24": "2887634"
    }
  }
}

devices-set-local-domain-fallback-list

PUT Set Local Domain Fallback List

Set the list of domains resolved locally by WARP clients

PUT accounts/:identifier/devices/policy/fallback_domains

Optional parameters

Name /type	Description /example	Constraints
suffix string	The domain suffix to match when resolving locally. `"example.com"`
description string	A description of the fallback domain, displayed in the client UI `"Domain bypass for local development"`	max length: 100
dns_server array	A list of IP addresses to handle domain resolution. `"['192.168.0.1', '10.1.1.1']"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/policy/fallback_domains" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '[{"suffix":"example.com","description":"Domain bypass for local development","dns_server":"['192.168.0.1', '10.1.1.1']"}]'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "suffix": "example.com",
      "description": "Domain bypass for local development",
      "dns_server": "['192.168.0.1', '10.1.1.1']"
    }
  ]
}

devices-get-local-domain-fallback-list

GET Get Local Domain Fallback List

Get the list of domains resolved locally by WARP clients

GET accounts/:identifier/devices/policy/fallback_domains

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/policy/fallback_domains" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "suffix": "example.com",
      "description": "Domain bypass for local development",
      "dns_server": "['192.168.0.1', '10.1.1.1']"
    }
  ]
}

devices-set-split-tunnel-exclude-list

PUT Set Split Tunnel Exclude List

Set the list of routes excluded from the WARP client's tunnel

PUT accounts/:identifier/devices/policy/exclude

Optional parameters

Name /type	Description /example	Constraints
address string	The address in CIDR format to exclude from the tunnel. If address is present, host must not be present. `"192.0.2.0/24"`
description string	A description of the split tunnel item, displayed in the client UI. `"Exclude testing domains from the tunnel"`	max length: 100
host string	The domain name to exclude from the tunnel. If host is present, address must not be present. `"*.example.com"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/policy/exclude" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '[{"address":"192.0.2.0/24","description":"Exclude testing domains from the tunnel"}]'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "address": "192.0.2.0/24",
      "description": "Exclude testing domains from the tunnel"
    }
  ]
}

devices-get-split-tunnel-exclude-list

GET Get Split Tunnel Exclude List

Get the list of routes excluded from the WARP client's tunnel

GET accounts/:identifier/devices/policy/exclude

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/policy/exclude" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "address": "192.0.2.0/24",
      "description": "Exclude testing domains from the tunnel"
    }
  ]
}

devices-set-split-tunnel-include-list

PUT Set Split Tunnel Include List

Set the list of routes included in the WARP client's tunnel

PUT accounts/:identifier/devices/policy/include

Optional parameters

Name /type	Description /example	Constraints
address string	The address in CIDR format to include in the tunnel. If address is present, host must not be present. `"192.0.2.0/24"`
description string	A description of the split tunnel item, displayed in the client UI `"Include testing domains from the tunnel"`	max length: 100
host string	The domain name to include in the tunnel. If host is present, address must not be present. `"*.example.com"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/policy/include" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '[{"address":"192.0.2.0/24","description":"Include testing domains from the tunnel"}]'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "address": "192.0.2.0/24",
      "description": "Include testing domains from the tunnel"
    }
  ]
}

devices-get-split-tunnel-include-list

GET Get Split Tunnel Include List

Get the list of routes included in the WARP client's tunnel

GET accounts/:identifier/devices/policy/include

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/policy/include" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "address": "192.0.2.0/24",
      "description": "Include testing domains from the tunnel"
    }
  ]
}

Device Posture Integrations

Device posture integrations allow third party APIs to act as device posture providers

device-posture-integrations

Object definition

View properties and constraints defined on the object

Show definition

device-posture-integrations-list-device-posture-integrations

GET List Device Posture Integrations

List Device Posture Integrations for an account

GET accounts/:identifier/devices/posture/integration

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/posture/integration" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "type": "workspace_one",
      "name": "My Workspace One Integration",
      "interval": "10m",
      "config": {
        "api_url": "https://as123.awmdm.com/API",
        "auth_url": "https://na.uemauth.vmwservices.com/connect/token",
        "client_id": "example client id"
      }
    }
  ]
}

device-posture-integrations-device-posture-integration-details

GET Device Posture Integration Details

Fetch a single Device Posture Integration

GET accounts/:identifier/devices/posture/integration/:uuid

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/posture/integration/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "type": "workspace_one",
    "name": "My Workspace One Integration",
    "interval": "10m",
    "config": {
      "api_url": "https://as123.awmdm.com/API",
      "auth_url": "https://na.uemauth.vmwservices.com/connect/token",
      "client_id": "example client id"
    }
  }
}

device-posture-integrations-create-device-posture-integration

POST Create Device Posture Integration

Create a new Device Posture Integration

POST accounts/:identifier/devices/posture/integration

Required parameters

Name /type	Description /example	Constraints
type string	The type of Device Posture Integration. `"workspace_one"`	valid values: workspace_one, crowdstrike_s2s, uptycs, intune
name string	The name of the Device Posture Integration. `"My Workspace One Integration"`
interval string	The interval between each posture check with the third party API. Use "m" for minutes (e.g. "5m") and "h" for hours (e.g. "12h") `"10m"`
config object	The configuration object containing third party integration information `{ "api_url": "https://as123.awmdm.com/API", "auth_url": "https://na.uemauth.vmwservices.com/connect/token", "client_id": "example client id", "client_secret": "example client secret" }` One of the following: Show definition » Show definition » Show definition » Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/posture/integration" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"workspace_one","name":"My Workspace One Integration","interval":"10m","config":{"api_url":"https://as123.awmdm.com/API","auth_url":"https://na.uemauth.vmwservices.com/connect/token","client_id":"example client id","client_secret":"example client secret"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "type": "workspace_one",
    "name": "My Workspace One Integration",
    "interval": "10m",
    "config": {
      "api_url": "https://as123.awmdm.com/API",
      "auth_url": "https://na.uemauth.vmwservices.com/connect/token",
      "client_id": "example client id"
    }
  }
}

device-posture-integrations-update-device-posture-integration

PATCH Update Device Posture Integration

Update a Device Posture Integration

PATCH accounts/:identifier/devices/posture/integration/:uuid

Optional parameters

Name /type	Description /example	Constraints
type string	The type of Device Posture Integration. `"workspace_one"`	valid values: workspace_one, crowdstrike_s2s, uptycs, intune
name string	The name of the Device Posture Integration. `"My Workspace One Integration"`
interval string	The interval between each posture check with the third party API. Use "m" for minutes (e.g. "5m") and "h" for hours (e.g. "12h") `"10m"`
config object	The configuration object containing third party integration information `{ "api_url": "https://as123.awmdm.com/API", "auth_url": "https://na.uemauth.vmwservices.com/connect/token", "client_id": "example client id", "client_secret": "example client secret" }` One of the following: Show definition » Show definition » Show definition » Show definition »

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/posture/integration/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"workspace_one","name":"My Workspace One Integration","interval":"10m","config":{"api_url":"https://as123.awmdm.com/API","auth_url":"https://na.uemauth.vmwservices.com/connect/token","client_id":"example client id","client_secret":"example client secret"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "type": "workspace_one",
    "name": "My Workspace One Integration",
    "interval": "10m",
    "config": {
      "api_url": "https://as123.awmdm.com/API",
      "auth_url": "https://na.uemauth.vmwservices.com/connect/token",
      "client_id": "example client id"
    }
  }
}

device-posture-integrations-delete-device-posture-integration

DELETE Delete Device Posture Integration

Delete a Device Posture Integration

DELETE accounts/:identifier/devices/posture/integration/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/699d98642c564d2e855e9661899b7252/devices/posture/integration/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Health Checks

Zone-level stand-alone health checks

health-checks

Object definition

View properties and constraints defined on the object

Show definition

health-checks-list-health-checks

GET List Health Checks
free
pro
business
enterprise

List configured health checks

GET zones/:zone_identifier/healthchecks

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 `25`	default value: 25 min value:5 max value:1000
name string	Filter health checks with name partially matching this string `"server-1"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/healthchecks?page=1&per_page=25&name=server-1" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "699d98642c564d2e855e9661899b7252",
      "created_on": "2014-01-01T05:20:00.12345Z",
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "name": "server-1",
      "description": "Health check for www.example.com",
      "suspended": false,
      "check_regions": [
        "WEU",
        "ENAM"
      ],
      "type": "HTTPS",
      "consecutive_successes": 1,
      "consecutive_fails": 1,
      "http_config": {
        "method": "GET",
        "port": 80,
        "path": "/health",
        "expected_codes": [
          "2xx",
          "302"
        ],
        "expected_body": "success",
        "follow_redirects": false,
        "allow_insecure": false,
        "header": {
          "Host": [
            "example.com"
          ],
          "X-App-ID": [
            "abc123"
          ]
        }
      },
      "tcp_config": {
        "method": "connection_established",
        "port": 80
      },
      "timeout": 5,
      "retries": 2,
      "interval": 60,
      "address": "www.example.com",
      "status": "healthy",
      "failure_reason": ""
    }
  ]
}

health-checks-create-health-check

POST Create Health Check
free
pro
business
enterprise

Create a new health check

POST zones/:zone_identifier/healthchecks

Required parameters

Name /type	Description /example	Constraints
name string	A short name to identify the health check. Only alphanumeric characters, hyphens and underscores are allowed. `"server-1"`
address string	The hostname or IP address of the origin server to run health checks on. `"www.example.com"`

Optional parameters

Name /type	Description /example	Constraints
consecutive_fails integer	The number of consecutive fails required from a health check before changing the health to unhealthy `1`	default value: 1
tcp_config objectnull	Parameters specific to TCP health check `{ "method": "connection_established", "port": 80 }` An object with the following properties: Show definition »
timeout integer	The timeout (in seconds) before marking the health check as failed. `5`	default value: 5
interval integer	The interval between each health check. Shorter intervals may give quicker notifications if the origin status changes, but will increase load on the origin as we check from multiple locations. `60`	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. `2`	default value: 2
check_regions arraynull	A list of regions from which to run health checks. Null means Cloudflare will pick a default region. `[ "WEU", "ENAM" ]` An array with items in the following form: Show definition »
http_config objectnull	Parameters specific to an HTTP or HTTPS health check `{ "method": "GET", "port": 80, "path": "/health", "expected_codes": [ "2xx", "302" ], "expected_body": "success", "follow_redirects": false, "allow_insecure": false, "header": { "Host": [ "example.com" ], "X-App-ID": [ "abc123" ] } }` An object with the following properties: Show definition »
type string	The protocol to use for the health check. Currently supported protocols are 'HTTP', 'HTTPS' and 'TCP'. `"HTTPS"`	default value: HTTP
suspended boolean	If suspended, no health checks are sent to the origin. `false`	default value: false valid values: (true,false)
consecutive_successes integer	The number of consecutive successes required from a health check before changing the health to healthy `1`	default value: 1
description string	A human-readable description of the health check. `"Health check for www.example.com"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/healthchecks" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"server-1","description":"Health check for www.example.com","suspended":false,"check_regions":["WEU","ENAM"],"type":"HTTPS","consecutive_successes":1,"consecutive_fails":1,"http_config":{"method":"GET","port":80,"path":"/health","expected_codes":["2xx","302"],"expected_body":"success","follow_redirects":false,"allow_insecure":false,"header":{"Host":["example.com"],"X-App-ID":["abc123"]}},"tcp_config":{"method":"connection_established","port":80},"timeout":5,"retries":2,"interval":60,"address":"www.example.com"}'

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",
    "name": "server-1",
    "description": "Health check for www.example.com",
    "suspended": false,
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "type": "HTTPS",
    "consecutive_successes": 1,
    "consecutive_fails": 1,
    "http_config": {
      "method": "GET",
      "port": 80,
      "path": "/health",
      "expected_codes": [
        "2xx",
        "302"
      ],
      "expected_body": "success",
      "follow_redirects": false,
      "allow_insecure": false,
      "header": {
        "Host": [
          "example.com"
        ],
        "X-App-ID": [
          "abc123"
        ]
      }
    },
    "tcp_config": {
      "method": "connection_established",
      "port": 80
    },
    "timeout": 5,
    "retries": 2,
    "interval": 60,
    "address": "www.example.com",
    "status": "healthy",
    "failure_reason": ""
  }
}

health-checks-health-check-details

GET Health Check Details
free
pro
business
enterprise

Fetch a single configured health check

GET zones/:zone_identifier/healthchecks/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/healthchecks/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "699d98642c564d2e855e9661899b7252",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "name": "server-1",
    "description": "Health check for www.example.com",
    "suspended": false,
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "type": "HTTPS",
    "consecutive_successes": 1,
    "consecutive_fails": 1,
    "http_config": {
      "method": "GET",
      "port": 80,
      "path": "/health",
      "expected_codes": [
        "2xx",
        "302"
      ],
      "expected_body": "success",
      "follow_redirects": false,
      "allow_insecure": false,
      "header": {
        "Host": [
          "example.com"
        ],
        "X-App-ID": [
          "abc123"
        ]
      }
    },
    "tcp_config": {
      "method": "connection_established",
      "port": 80
    },
    "timeout": 5,
    "retries": 2,
    "interval": 60,
    "address": "www.example.com",
    "status": "healthy",
    "failure_reason": ""
  }
}

health-checks-update-health-check

PUT Update Health Check
free
pro
business
enterprise

Update a configured health check

PUT zones/:zone_identifier/healthchecks/:identifier

Required parameters

Name /type	Description /example	Constraints
name string	A short name to identify the health check. Only alphanumeric characters, hyphens and underscores are allowed. `"server-1"`
address string	The hostname or IP address of the origin server to run health checks on. `"www.example.com"`

Optional parameters

Name /type	Description /example	Constraints
consecutive_fails integer	The number of consecutive fails required from a health check before changing the health to unhealthy `1`	default value: 1
tcp_config objectnull	Parameters specific to TCP health check `{ "method": "connection_established", "port": 80 }` An object with the following properties: Show definition »
timeout integer	The timeout (in seconds) before marking the health check as failed. `5`	default value: 5
interval integer	The interval between each health check. Shorter intervals may give quicker notifications if the origin status changes, but will increase load on the origin as we check from multiple locations. `60`	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. `2`	default value: 2
check_regions arraynull	A list of regions from which to run health checks. Null means Cloudflare will pick a default region. `[ "WEU", "ENAM" ]` An array with items in the following form: Show definition »
http_config objectnull	Parameters specific to an HTTP or HTTPS health check `{ "method": "GET", "port": 80, "path": "/health", "expected_codes": [ "2xx", "302" ], "expected_body": "success", "follow_redirects": false, "allow_insecure": false, "header": { "Host": [ "example.com" ], "X-App-ID": [ "abc123" ] } }` An object with the following properties: Show definition »
type string	The protocol to use for the health check. Currently supported protocols are 'HTTP', 'HTTPS' and 'TCP'. `"HTTPS"`	default value: HTTP
suspended boolean	If suspended, no health checks are sent to the origin. `false`	default value: false valid values: (true,false)
consecutive_successes integer	The number of consecutive successes required from a health check before changing the health to healthy `1`	default value: 1
description string	A human-readable description of the health check. `"Health check for www.example.com"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/healthchecks/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"server-1","description":"Health check for www.example.com","suspended":false,"check_regions":["WEU","ENAM"],"type":"HTTPS","consecutive_successes":1,"consecutive_fails":1,"http_config":{"method":"GET","port":80,"path":"/health","expected_codes":["2xx","302"],"expected_body":"success","follow_redirects":false,"allow_insecure":false,"header":{"Host":["example.com"],"X-App-ID":["abc123"]}},"tcp_config":{"method":"connection_established","port":80},"timeout":5,"retries":2,"interval":60,"address":"www.example.com"}'

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",
    "name": "server-1",
    "description": "Health check for www.example.com",
    "suspended": false,
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "type": "HTTPS",
    "consecutive_successes": 1,
    "consecutive_fails": 1,
    "http_config": {
      "method": "GET",
      "port": 80,
      "path": "/health",
      "expected_codes": [
        "2xx",
        "302"
      ],
      "expected_body": "success",
      "follow_redirects": false,
      "allow_insecure": false,
      "header": {
        "Host": [
          "example.com"
        ],
        "X-App-ID": [
          "abc123"
        ]
      }
    },
    "tcp_config": {
      "method": "connection_established",
      "port": 80
    },
    "timeout": 5,
    "retries": 2,
    "interval": 60,
    "address": "www.example.com",
    "status": "healthy",
    "failure_reason": ""
  }
}

health-checks-patch-health-check

PATCH Patch Health Check
free
pro
business
enterprise

Patch a configured health check

PATCH zones/:zone_identifier/healthchecks/:identifier

Required parameters

Name /type	Description /example	Constraints
name string	A short name to identify the health check. Only alphanumeric characters, hyphens and underscores are allowed. `"server-1"`
address string	The hostname or IP address of the origin server to run health checks on. `"www.example.com"`

Optional parameters

Name /type	Description /example	Constraints
consecutive_fails integer	The number of consecutive fails required from a health check before changing the health to unhealthy `1`	default value: 1
tcp_config objectnull	Parameters specific to TCP health check `{ "method": "connection_established", "port": 80 }` An object with the following properties: Show definition »
timeout integer	The timeout (in seconds) before marking the health check as failed. `5`	default value: 5
interval integer	The interval between each health check. Shorter intervals may give quicker notifications if the origin status changes, but will increase load on the origin as we check from multiple locations. `60`	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. `2`	default value: 2
check_regions arraynull	A list of regions from which to run health checks. Null means Cloudflare will pick a default region. `[ "WEU", "ENAM" ]` An array with items in the following form: Show definition »
http_config objectnull	Parameters specific to an HTTP or HTTPS health check `{ "method": "GET", "port": 80, "path": "/health", "expected_codes": [ "2xx", "302" ], "expected_body": "success", "follow_redirects": false, "allow_insecure": false, "header": { "Host": [ "example.com" ], "X-App-ID": [ "abc123" ] } }` An object with the following properties: Show definition »
type string	The protocol to use for the health check. Currently supported protocols are 'HTTP', 'HTTPS' and 'TCP'. `"HTTPS"`	default value: HTTP
suspended boolean	If suspended, no health checks are sent to the origin. `false`	default value: false valid values: (true,false)
consecutive_successes integer	The number of consecutive successes required from a health check before changing the health to healthy `1`	default value: 1
description string	A human-readable description of the health check. `"Health check for www.example.com"`

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/healthchecks/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"server-1","description":"Health check for www.example.com","suspended":false,"check_regions":["WEU","ENAM"],"type":"HTTPS","consecutive_successes":1,"consecutive_fails":1,"http_config":{"method":"GET","port":80,"path":"/health","expected_codes":["2xx","302"],"expected_body":"success","follow_redirects":false,"allow_insecure":false,"header":{"Host":["example.com"],"X-App-ID":["abc123"]}},"tcp_config":{"method":"connection_established","port":80},"timeout":5,"retries":2,"interval":60,"address":"www.example.com"}'

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",
    "name": "server-1",
    "description": "Health check for www.example.com",
    "suspended": false,
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "type": "HTTPS",
    "consecutive_successes": 1,
    "consecutive_fails": 1,
    "http_config": {
      "method": "GET",
      "port": 80,
      "path": "/health",
      "expected_codes": [
        "2xx",
        "302"
      ],
      "expected_body": "success",
      "follow_redirects": false,
      "allow_insecure": false,
      "header": {
        "Host": [
          "example.com"
        ],
        "X-App-ID": [
          "abc123"
        ]
      }
    },
    "tcp_config": {
      "method": "connection_established",
      "port": 80
    },
    "timeout": 5,
    "retries": 2,
    "interval": 60,
    "address": "www.example.com",
    "status": "healthy",
    "failure_reason": ""
  }
}

health-checks-delete-health-check

DELETE Delete Health Check
free
pro
business
enterprise

Delete a health check

DELETE zones/:zone_identifier/healthchecks/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/healthchecks/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

health-checks-create-preview-health-check

POST Create Preview Health Check
free
pro
business
enterprise

Create a new preview health check

POST zones/:zone_identifier/healthchecks/preview

Required parameters

Name /type	Description /example	Constraints
name string	A short name to identify the health check. Only alphanumeric characters, hyphens and underscores are allowed. `"server-1"`
address string	The hostname or IP address of the origin server to run health checks on. `"www.example.com"`

Optional parameters

Name /type	Description /example	Constraints
consecutive_fails integer	The number of consecutive fails required from a health check before changing the health to unhealthy `1`	default value: 1
tcp_config objectnull	Parameters specific to TCP health check `{ "method": "connection_established", "port": 80 }` An object with the following properties: Show definition »
timeout integer	The timeout (in seconds) before marking the health check as failed. `5`	default value: 5
interval integer	The interval between each health check. Shorter intervals may give quicker notifications if the origin status changes, but will increase load on the origin as we check from multiple locations. `60`	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. `2`	default value: 2
check_regions arraynull	A list of regions from which to run health checks. Null means Cloudflare will pick a default region. `[ "WEU", "ENAM" ]` An array with items in the following form: Show definition »
http_config objectnull	Parameters specific to an HTTP or HTTPS health check `{ "method": "GET", "port": 80, "path": "/health", "expected_codes": [ "2xx", "302" ], "expected_body": "success", "follow_redirects": false, "allow_insecure": false, "header": { "Host": [ "example.com" ], "X-App-ID": [ "abc123" ] } }` An object with the following properties: Show definition »
type string	The protocol to use for the health check. Currently supported protocols are 'HTTP', 'HTTPS' and 'TCP'. `"HTTPS"`	default value: HTTP
suspended boolean	If suspended, no health checks are sent to the origin. `false`	default value: false valid values: (true,false)
consecutive_successes integer	The number of consecutive successes required from a health check before changing the health to healthy `1`	default value: 1
description string	A human-readable description of the health check. `"Health check for www.example.com"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/healthchecks/preview" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"server-1","description":"Health check for www.example.com","suspended":false,"check_regions":["WEU","ENAM"],"type":"HTTPS","consecutive_successes":1,"consecutive_fails":1,"http_config":{"method":"GET","port":80,"path":"/health","expected_codes":["2xx","302"],"expected_body":"success","follow_redirects":false,"allow_insecure":false,"header":{"Host":["example.com"],"X-App-ID":["abc123"]}},"tcp_config":{"method":"connection_established","port":80},"timeout":5,"retries":2,"interval":60,"address":"www.example.com"}'

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",
    "name": "server-1",
    "description": "Health check for www.example.com",
    "suspended": false,
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "type": "HTTPS",
    "consecutive_successes": 1,
    "consecutive_fails": 1,
    "http_config": {
      "method": "GET",
      "port": 80,
      "path": "/health",
      "expected_codes": [
        "2xx",
        "302"
      ],
      "expected_body": "success",
      "follow_redirects": false,
      "allow_insecure": false,
      "header": {
        "Host": [
          "example.com"
        ],
        "X-App-ID": [
          "abc123"
        ]
      }
    },
    "tcp_config": {
      "method": "connection_established",
      "port": 80
    },
    "timeout": 5,
    "retries": 2,
    "interval": 60,
    "address": "www.example.com",
    "status": "healthy",
    "failure_reason": ""
  }
}

health-checks-health-check-preview-details

GET Health Check Preview Details
free
pro
business
enterprise

Fetch a single configured health check preview

GET zones/:zone_identifier/healthchecks/preview/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/healthchecks/preview/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "699d98642c564d2e855e9661899b7252",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "name": "server-1",
    "description": "Health check for www.example.com",
    "suspended": false,
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "type": "HTTPS",
    "consecutive_successes": 1,
    "consecutive_fails": 1,
    "http_config": {
      "method": "GET",
      "port": 80,
      "path": "/health",
      "expected_codes": [
        "2xx",
        "302"
      ],
      "expected_body": "success",
      "follow_redirects": false,
      "allow_insecure": false,
      "header": {
        "Host": [
          "example.com"
        ],
        "X-App-ID": [
          "abc123"
        ]
      }
    },
    "tcp_config": {
      "method": "connection_established",
      "port": 80
    },
    "timeout": 5,
    "retries": 2,
    "interval": 60,
    "address": "www.example.com",
    "status": "healthy",
    "failure_reason": ""
  }
}

health-checks-delete-preview-health-check

DELETE Delete Preview Health Check
free
pro
business
enterprise

Delete a health check

DELETE zones/:zone_identifier/healthchecks/preview/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/healthchecks/preview/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Diagnostics

Run diagnostics tools from Cloudflare's colos.

diagnostics

Object definition

View properties and constraints defined on the object

Show definition

diagnostics-traceroute

POST Traceroute
free
pro
business
enterprise

Run traceroutes from Cloudflare colos.

POST accounts/:account_identifier/diagnostics/traceroute

Required parameters

Name /type	Description /example	Constraints
targets array	`[ "203.0.113.1", "cloudflare.com" ]` An array with items in the following form: Show definition »	max length: 10

Optional parameters

Name /type	Description /example	Constraints
colos array	If no source colo names specified, all colos will be used. China colos are unavailable for traceroutes `[ "den", "sin" ]` An array with items in the following form: Show definition »
options	`{ "packets_per_ttl": 10, "packet_type": "icmp", "max_ttl": 5, "wait_time": 1, "port": 0 }` An object with the following properties: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/diagnostics/traceroute" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"targets":["203.0.113.1","cloudflare.com"],"colos":["den","sin"],"options":{"packets_per_ttl":10,"packet_type":"icmp","max_ttl":5,"wait_time":1,"port":0}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "target": "1.1.1.1",
      "colos": [
        {
          "error": "",
          "colo": {
            "name": "den01",
            "city": "Denver, CO, US"
          },
          "traceroute_time_ms": 969,
          "target_summary": {
            "asn": "",
            "ip": "1.1.1.1",
            "name": "1.1.1.1",
            "packet_count": 3,
            "mean_latency_ms": 0.021,
            "std_dev_latency_ms": 0.011269427669584647,
            "min_latency_ms": 0.014,
            "max_latency_ms": 0.034
          },
          "hops": [
            {
              "packets_ttl": 1,
              "packets_sent": 3,
              "packets_lost": 0,
              "nodes": [
                {
                  "asn": "AS13335",
                  "ip": "1.1.1.1",
                  "name": "one.one.one.one",
                  "packet_count": 3,
                  "mean_latency_ms": 0.021,
                  "std_dev_latency_ms": 0.011269427669584647,
                  "min_latency_ms": 0.014,
                  "max_latency_ms": 0.034
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Diagnostics error codes

Code	Description
1000	Empty request body
1001	Invalid request
1002	No targets were specified
1003	Could not gather all colos
1004	Target is not a valid address
1005	Colo is not a valid colo
1006	Invalid packet_type
1007	Invalid ttl_end
1008	Invalid num_packets
1009	Invalid wait_time
1010	Account does not have permission
1011	Too many targets specified
1012	Invalid port

Waiting Room

Zone-level waiting rooms

waiting-room

Object definition

View properties and constraints defined on the object

Show definition

waiting-room-list-waiting-rooms

GET List waiting rooms
free
pro
business
enterprise

Lists waiting rooms.

GET zones/:zone_identifier/waiting_rooms

Optional parameters

Name /type	Description /example	Constraints
page number	Page number of paginated results. `1`	default value: 1 min value:1
per_page number	Sets the number of items per page. `25`	default value: 25 min value:5 max value:1000

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/waiting_rooms?page=1&per_page=25" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "699d98642c564d2e855e9661899b7252",
      "created_on": "2014-01-01T05:20:00.12345Z",
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "name": "production_webinar",
      "description": "Production - DO NOT MODIFY",
      "suspended": false,
      "host": "shop.example.com",
      "path": "/shop/checkout",
      "queue_all": true,
      "new_users_per_minute": 1000,
      "total_active_users": 1000,
      "session_duration": 10,
      "disable_session_renewal": false,
      "json_response_enabled": false,
      "queueing_method": "fifo",
      "cookie_attributes": {
        "samesite": "auto",
        "secure": "auto"
      },
      "custom_page_html": "{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Queue all enabled {{/waitTimeKnown}}",
      "default_template_language": "es-ES",
      "next_event_prequeue_start_time": "2021-09-28T15:00:00.000Z",
      "next_event_start_time": "2021-09-28T15:00:00.000Z"
    }
  ]
}

waiting-room-create-waiting-room

POST Create waiting room
free
pro
business
enterprise

Creates a new waiting room.

POST zones/:zone_identifier/waiting_rooms

Required parameters

Name /type	Description /example	Constraints
host string	The host name to which the waiting room will be applied (no wildcards). Please do not include the scheme (http:// or https://). The host and path combination must be unique. `"shop.example.com"`
total_active_users integer	Sets the total number of active user sessions on the route at a point in time. A route is a combination of host and path on which a waiting room is available. This value is used as a baseline for the total number of active user sessions on the route. It is possible to have a situation where there are more or less active users sessions on the route based on the traffic patterns at that time around the world. `1000`	min value:200 max value:2147483647
name string	A unique name to identify the waiting room. Only alphanumeric characters, hyphens and underscores are allowed. `"production_webinar"`
new_users_per_minute integer	Sets the number of new users that will be let into the route every minute. This value is used as baseline for the number of users that are let in per minute. So it is possible that there is a little more or little less traffic coming to the route based on the traffic patterns at that time around the world. `1000`	min value:200 max value:2147483647

Optional parameters

Name /type	Description /example	Constraints
path string	Sets the path within the host to enable the waiting room on. The waiting room will be enabled for all subpaths as well. If there are two waiting rooms on the same subpath, the waiting room for the most specific path will be chosen. Wildcards and query parameters are not supported. `"/shop/checkout"`	default value: /
custom_page_html string	Only available for the Waiting Room Advanced subscription. This is a template html file that will be rendered at the edge. If no custom_page_html is provided, the default waiting room will be used. The template is based on mustache ( https://mustache.github.io/ ). There are several variables that are evaluated by the Cloudflare edge: {{`waitTimeKnown`}} Acts like a boolean value that indicates the behavior to take when wait time is not available, for instance when queue_all is true. {{`waitTimeFormatted`}} Estimated wait time for the user. For example, five minutes. Alternatively, you can use: {{`waitTime`}} Number of minutes of estimated wait for a user. {{`waitTimeHours`}} Number of hours of estimated wait for a user (`Math.floor(waitTime/60)`). {{`waitTimeHourMinutes`}} Number of minutes above the `waitTimeHours` value (`waitTime%60`). {{`queueIsFull`}} Changes to true when no more people can be added to the queue. To view the full list of variables, look at the `cfWaitingRoom` object described under the `json_response_enabled` property in other Waiting Room API calls. `"{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Queue all enabled {{/waitTimeKnown}}"`	default value:
queueing_method string	Sets the queueing method used by the waiting room. Changing this parameter from the default queueing method is only available for the Waiting Room Advanced subscription. Regardless of the queueing method, if `queue_all` is enabled or an event is prequeueing, users in the waiting room will not be accepted to the origin. These users will always see a waiting room page that refreshes automatically. The valid queueing methods are: `fifo` (default): First-In-First-Out queue where customers gain access in the order they arrived. `random`: Random queue where customers gain access randomly, regardless of arrival time. `passthrough`: Users will pass directly through the waiting room and into the origin website. As a result, any configured limits will not be respected while this is enabled. This method can be used as an alternative to disabling a waiting room (with `suspended`) so that analytics are still reported. This can be used if you wish to allow all traffic normally, but want to restrict traffic during a waiting room event, or vice versa. `reject`: Users will be immediately rejected from the waiting room. As a result, no users will reach the origin website while this is enabled. This can be used if you wish to reject all traffic while performing maintenance, block traffic during a specified period of time (an event), or block traffic while events are not occurring. Consider a waiting room used for vaccine distribution that only allows traffic during sign-up events, and otherwise blocks all traffic. For this case, the waiting room uses `reject`, and its events override this with `fifo`, `random`, or `passthrough`. When this queueing method is enabled and neither `queueAll` is enabled nor an event is prequeueing, the waiting room page will not refresh automatically. `"fifo"`	default value: fifo valid values: fifo, random, passthrough, reject
cookie_attributes object	Configures cookie attributes for the waiting room cookie. This encrypted cookie stores a user's status in the waiting room, such as queue position. `{ "samesite": "auto", "secure": "auto" }` An object with the following properties: Show definition »
queue_all boolean	If queue_all is `true`, all the traffic that is coming to a route will be sent to the waiting room. No new traffic can get to the route once this field is set and estimated time will become unavailable. `true`	default value: false valid values: (true,false)
disable_session_renewal boolean	Only available for the Waiting Room Advanced subscription. Disables automatic renewal of session cookies. If `true`, an accepted user will have session_duration minutes to browse the site. After that, they will have to go through the waiting room again. If `false`, a user's session cookie will be automatically renewed on every request. `false`	default value: false valid values: (true,false)
json_response_enabled boolean	Only available for the Waiting Room Advanced subscription. If `true`, requests to the waiting room with the header `Accept: application/json` will receive a JSON response object with information on the user's status in the waiting room as opposed to the configured static HTML page. This JSON response object has one property `cfWaitingRoom` which is an object containing the following fields: `inWaitingRoom`: Boolean indicating if the user is in the waiting room (always true). `waitTimeKnown`: Boolean indicating if the current estimated wait times are accurate. If false, they are not available. `waitTime`: Valid only when `waitTimeKnown` is true. Integer indicating the current estimated time in minutes the user will wait in the waiting room. When `queueingMethod` is random, this is set to `waitTime50Percentile`. `waitTime25Percentile`: Valid only when `queueingMethod` is random and `waitTimeKnown` is true. Integer indicating the current estimated maximum wait time for the 25% of users that gain entry the fastest (25th percentile). `waitTime50Percentile`: Valid only when `queueingMethod` is random and `waitTimeKnown` is true. Integer indicating the current estimated maximum wait time for the 50% of users that gain entry the fastest (50th percentile). In other words, half of the queued users are expected to let into the origin website before `waitTime50Percentile` and half are expected to be let in after it. `waitTime75Percentile`: Valid only when `queueingMethod` is random and `waitTimeKnown` is true. Integer indicating the current estimated maximum wait time for the 75% of users that gain entry the fastest (75th percentile). `waitTimeFormatted`: String displaying the `waitTime` formatted in English for users. If `waitTimeKnown` is false, `waitTimeFormatted` will display unavailable. `queueIsFull`: Boolean indicating if the waiting room's queue is currently full and not accepting new users at the moment. `queueAll`: Boolean indicating if all users will be queued in the waiting room and no one will be let into the origin website. `lastUpdated`: String displaying the timestamp as an ISO 8601 string of the user's last attempt to leave the waiting room and be let into the origin website. The user is able to make another attempt after `refreshIntervalSeconds` past this time. If the user makes a request too soon, it will be ignored and `lastUpdated` will not change. `refreshIntervalSeconds`: Integer indicating the number of seconds after `lastUpdated` until the user is able to make another attempt to leave the waiting room and be let into the origin website. When the `queueingMethod` is `reject`, there is no specified refresh time — it will always be zero. `queueingMethod`: The queueing method currently used by the waiting room. It is either fifo, random, passthrough, or reject. `isFIFOQueue`: Boolean indicating if the waiting room uses a FIFO (First-In-First-Out) queue. `isRandomQueue`: Boolean indicating if the waiting room uses a Random queue where users gain access randomly. `isPassthroughQueue`: Boolean indicating if the waiting room uses a passthrough queue. Keep in mind that when passthrough is enabled, this JSON response will only exist when `queueAll` is true or `isEventPrequeueing` is true because in all other cases requests will go directly to the origin. `isRejectQueue`: Boolean indicating if the waiting room uses a reject queue. `isEventActive`: Boolean indicating if an event is currently occurring. Events are able to change a waiting room's behavior during a specified period of time. For additional information, look at the event properties `prequeue_start_time`, `event_start_time`, and `event_end_time` in the documentation for creating waiting room events. Events are considered active between these start and end times, as well as during the prequeueing period if it exists. `isEventPrequeueing`: Valid only when `isEventActive` is true. Boolean indicating if an event is currently prequeueing users before it starts. `timeUntilEventStart`: Valid only when `isEventPrequeueing` is true. Integer indicating the number of minutes until the event starts. `timeUntilEventStartFormatted`: String displaying the `timeUntilEventStart` formatted in English for users. If `isEventPrequeueing` is false, `timeUntilEventStartFormatted` will display unavailable. `timeUntilEventEnd`: Valid only when `isEventActive` is true. Integer indicating the number of minutes until the event ends. `timeUntilEventEndFormatted`: String displaying the `timeUntilEventEnd` formatted in English for users. If `isEventActive` is false, `timeUntilEventEndFormatted` will display unavailable. `shuffleAtEventStart`: Valid only when `isEventActive` is true. Boolean indicating if the users in the prequeue are shuffled randomly when the event starts. An example cURL to a waiting room could be: `curl -X GET "https://example.com/waitingroom" \ -H "Accept: application/json"` If `json_response_enabled` is true and the request hits the waiting room, an example JSON response when `queueingMethod` is fifo and no event is active could be: { "cfWaitingRoom": { "inWaitingRoom": true, "waitTimeKnown": true, "waitTime": 10, "waitTime25Percentile": 0, "waitTime50Percentile": 0, "waitTime75Percentile": 0, "waitTimeFormatted": "10 minutes", "queueIsFull": false, "queueAll": false, "lastUpdated": "2020-08-03T23:46:00.000Z", "refreshIntervalSeconds": 20, "queueingMethod": "fifo", "isFIFOQueue": true, "isRandomQueue": false, "isPassthroughQueue": false, "isRejectQueue": false, "isEventActive": false, "isEventPrequeueing": false, "timeUntilEventStart": 0, "timeUntilEventStartFormatted": "unavailable", "timeUntilEventEnd": 0, "timeUntilEventEndFormatted": "unavailable", "shuffleAtEventStart": false } } If `json_response_enabled` is true and the request hits the waiting room, an example JSON response when `queueingMethod` is random and an event is active could be: { "cfWaitingRoom": { "inWaitingRoom": true, "waitTimeKnown": true, "waitTime": 10, "waitTime25Percentile": 5, "waitTime50Percentile": 10, "waitTime75Percentile": 15, "waitTimeFormatted": "5 minutes to 15 minutes", "queueIsFull": false, "queueAll": false, "lastUpdated": "2020-08-03T23:46:00.000Z", "refreshIntervalSeconds": 20, "queueingMethod": "random", "isFIFOQueue": false, "isRandomQueue": true, "isPassthroughQueue": false, "isRejectQueue": false, "isEventActive": true, "isEventPrequeueing": false, "timeUntilEventStart": 0, "timeUntilEventStartFormatted": "unavailable", "timeUntilEventEnd": 15, "timeUntilEventEndFormatted": "15 minutes", "shuffleAtEventStart": true } } `false`	default value: false valid values: (true,false)
suspended boolean	Suspends or allows traffic going to the waiting room. If set to `true`, the traffic will not go to the waiting room. `false`	default value: false valid values: (true,false)
description string	A note that you can use to add more details about the waiting room. `"Production - DO NOT MODIFY"`	default value:
session_duration integer	Lifetime of a cookie (in minutes) set by Cloudflare for users who get access to the route. If a user is not seen by Cloudflare again in that time period, they will be treated as a new user that visits the route. `10`	default value: 5 min value:1 max value:30
default_template_language string	The language of the default page template. If no default_template_language is provided, then `en-US` (English) will be used. `"es-ES"`	default value: en-US valid values: en-US, es-ES, de-DE, fr-FR, it-IT, ja-JP, ko-KR, pt-BR, zh-CN, zh-TW, nl-NL, pl-PL, id-ID, tr-TR, ar-EG

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/waiting_rooms" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"production_webinar","description":"Production - DO NOT MODIFY","suspended":false,"host":"shop.example.com","path":"/shop/checkout","queue_all":true,"new_users_per_minute":1000,"total_active_users":1000,"session_duration":10,"disable_session_renewal":false,"json_response_enabled":false,"queueing_method":"fifo","cookie_attributes":{"samesite":"auto","secure":"auto"},"custom_page_html":"{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Queue all enabled {{/waitTimeKnown}}","default_template_language":"es-ES"}'

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",
    "name": "production_webinar",
    "description": "Production - DO NOT MODIFY",
    "suspended": false,
    "host": "shop.example.com",
    "path": "/shop/checkout",
    "queue_all": true,
    "new_users_per_minute": 1000,
    "total_active_users": 1000,
    "session_duration": 10,
    "disable_session_renewal": false,
    "json_response_enabled": false,
    "queueing_method": "fifo",
    "cookie_attributes": {
      "samesite": "auto",
      "secure": "auto"
    },
    "custom_page_html": "{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Queue all enabled {{/waitTimeKnown}}",
    "default_template_language": "es-ES",
    "next_event_prequeue_start_time": "2021-09-28T15:00:00.000Z",
    "next_event_start_time": "2021-09-28T15:00:00.000Z"
  }
}

waiting-room-waiting-room-details

GET Waiting room details
free
pro
business
enterprise

Fetches a single configured waiting room.

GET zones/:zone_identifier/waiting_rooms/:waiting_room_id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/waiting_rooms/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "699d98642c564d2e855e9661899b7252",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "name": "production_webinar",
    "description": "Production - DO NOT MODIFY",
    "suspended": false,
    "host": "shop.example.com",
    "path": "/shop/checkout",
    "queue_all": true,
    "new_users_per_minute": 1000,
    "total_active_users": 1000,
    "session_duration": 10,
    "disable_session_renewal": false,
    "json_response_enabled": false,
    "queueing_method": "fifo",
    "cookie_attributes": {
      "samesite": "auto",
      "secure": "auto"
    },
    "custom_page_html": "{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Queue all enabled {{/waitTimeKnown}}",
    "default_template_language": "es-ES",
    "next_event_prequeue_start_time": "2021-09-28T15:00:00.000Z",
    "next_event_start_time": "2021-09-28T15:00:00.000Z"
  }
}

waiting-room-update-waiting-room

PUT Update waiting room
free
pro
business
enterprise

Updates a configured waiting room.

PUT zones/:zone_identifier/waiting_rooms/:waiting_room_id

Required parameters

Name /type	Description /example	Constraints
host string	The host name to which the waiting room will be applied (no wildcards). Please do not include the scheme (http:// or https://). The host and path combination must be unique. `"shop.example.com"`
total_active_users integer	Sets the total number of active user sessions on the route at a point in time. A route is a combination of host and path on which a waiting room is available. This value is used as a baseline for the total number of active user sessions on the route. It is possible to have a situation where there are more or less active users sessions on the route based on the traffic patterns at that time around the world. `1000`	min value:200 max value:2147483647
name string	A unique name to identify the waiting room. Only alphanumeric characters, hyphens and underscores are allowed. `"production_webinar"`
new_users_per_minute integer	Sets the number of new users that will be let into the route every minute. This value is used as baseline for the number of users that are let in per minute. So it is possible that there is a little more or little less traffic coming to the route based on the traffic patterns at that time around the world. `1000`	min value:200 max value:2147483647

Optional parameters

Name /type	Description /example	Constraints
path string	Sets the path within the host to enable the waiting room on. The waiting room will be enabled for all subpaths as well. If there are two waiting rooms on the same subpath, the waiting room for the most specific path will be chosen. Wildcards and query parameters are not supported. `"/shop/checkout"`	default value: /
custom_page_html string	Only available for the Waiting Room Advanced subscription. This is a template html file that will be rendered at the edge. If no custom_page_html is provided, the default waiting room will be used. The template is based on mustache ( https://mustache.github.io/ ). There are several variables that are evaluated by the Cloudflare edge: {{`waitTimeKnown`}} Acts like a boolean value that indicates the behavior to take when wait time is not available, for instance when queue_all is true. {{`waitTimeFormatted`}} Estimated wait time for the user. For example, five minutes. Alternatively, you can use: {{`waitTime`}} Number of minutes of estimated wait for a user. {{`waitTimeHours`}} Number of hours of estimated wait for a user (`Math.floor(waitTime/60)`). {{`waitTimeHourMinutes`}} Number of minutes above the `waitTimeHours` value (`waitTime%60`). {{`queueIsFull`}} Changes to true when no more people can be added to the queue. To view the full list of variables, look at the `cfWaitingRoom` object described under the `json_response_enabled` property in other Waiting Room API calls. `"{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Queue all enabled {{/waitTimeKnown}}"`	default value:
queueing_method string	Sets the queueing method used by the waiting room. Changing this parameter from the default queueing method is only available for the Waiting Room Advanced subscription. Regardless of the queueing method, if `queue_all` is enabled or an event is prequeueing, users in the waiting room will not be accepted to the origin. These users will always see a waiting room page that refreshes automatically. The valid queueing methods are: `fifo` (default): First-In-First-Out queue where customers gain access in the order they arrived. `random`: Random queue where customers gain access randomly, regardless of arrival time. `passthrough`: Users will pass directly through the waiting room and into the origin website. As a result, any configured limits will not be respected while this is enabled. This method can be used as an alternative to disabling a waiting room (with `suspended`) so that analytics are still reported. This can be used if you wish to allow all traffic normally, but want to restrict traffic during a waiting room event, or vice versa. `reject`: Users will be immediately rejected from the waiting room. As a result, no users will reach the origin website while this is enabled. This can be used if you wish to reject all traffic while performing maintenance, block traffic during a specified period of time (an event), or block traffic while events are not occurring. Consider a waiting room used for vaccine distribution that only allows traffic during sign-up events, and otherwise blocks all traffic. For this case, the waiting room uses `reject`, and its events override this with `fifo`, `random`, or `passthrough`. When this queueing method is enabled and neither `queueAll` is enabled nor an event is prequeueing, the waiting room page will not refresh automatically. `"fifo"`	default value: fifo valid values: fifo, random, passthrough, reject
cookie_attributes object	Configures cookie attributes for the waiting room cookie. This encrypted cookie stores a user's status in the waiting room, such as queue position. `{ "samesite": "auto", "secure": "auto" }` An object with the following properties: Show definition »
queue_all boolean	If queue_all is `true`, all the traffic that is coming to a route will be sent to the waiting room. No new traffic can get to the route once this field is set and estimated time will become unavailable. `true`	default value: false valid values: (true,false)
disable_session_renewal boolean	Only available for the Waiting Room Advanced subscription. Disables automatic renewal of session cookies. If `true`, an accepted user will have session_duration minutes to browse the site. After that, they will have to go through the waiting room again. If `false`, a user's session cookie will be automatically renewed on every request. `false`	default value: false valid values: (true,false)
json_response_enabled boolean	Only available for the Waiting Room Advanced subscription. If `true`, requests to the waiting room with the header `Accept: application/json` will receive a JSON response object with information on the user's status in the waiting room as opposed to the configured static HTML page. This JSON response object has one property `cfWaitingRoom` which is an object containing the following fields: `inWaitingRoom`: Boolean indicating if the user is in the waiting room (always true). `waitTimeKnown`: Boolean indicating if the current estimated wait times are accurate. If false, they are not available. `waitTime`: Valid only when `waitTimeKnown` is true. Integer indicating the current estimated time in minutes the user will wait in the waiting room. When `queueingMethod` is random, this is set to `waitTime50Percentile`. `waitTime25Percentile`: Valid only when `queueingMethod` is random and `waitTimeKnown` is true. Integer indicating the current estimated maximum wait time for the 25% of users that gain entry the fastest (25th percentile). `waitTime50Percentile`: Valid only when `queueingMethod` is random and `waitTimeKnown` is true. Integer indicating the current estimated maximum wait time for the 50% of users that gain entry the fastest (50th percentile). In other words, half of the queued users are expected to let into the origin website before `waitTime50Percentile` and half are expected to be let in after it. `waitTime75Percentile`: Valid only when `queueingMethod` is random and `waitTimeKnown` is true. Integer indicating the current estimated maximum wait time for the 75% of users that gain entry the fastest (75th percentile). `waitTimeFormatted`: String displaying the `waitTime` formatted in English for users. If `waitTimeKnown` is false, `waitTimeFormatted` will display unavailable. `queueIsFull`: Boolean indicating if the waiting room's queue is currently full and not accepting new users at the moment. `queueAll`: Boolean indicating if all users will be queued in the waiting room and no one will be let into the origin website. `lastUpdated`: String displaying the timestamp as an ISO 8601 string of the user's last attempt to leave the waiting room and be let into the origin website. The user is able to make another attempt after `refreshIntervalSeconds` past this time. If the user makes a request too soon, it will be ignored and `lastUpdated` will not change. `refreshIntervalSeconds`: Integer indicating the number of seconds after `lastUpdated` until the user is able to make another attempt to leave the waiting room and be let into the origin website. When the `queueingMethod` is `reject`, there is no specified refresh time — it will always be zero. `queueingMethod`: The queueing method currently used by the waiting room. It is either fifo, random, passthrough, or reject. `isFIFOQueue`: Boolean indicating if the waiting room uses a FIFO (First-In-First-Out) queue. `isRandomQueue`: Boolean indicating if the waiting room uses a Random queue where users gain access randomly. `isPassthroughQueue`: Boolean indicating if the waiting room uses a passthrough queue. Keep in mind that when passthrough is enabled, this JSON response will only exist when `queueAll` is true or `isEventPrequeueing` is true because in all other cases requests will go directly to the origin. `isRejectQueue`: Boolean indicating if the waiting room uses a reject queue. `isEventActive`: Boolean indicating if an event is currently occurring. Events are able to change a waiting room's behavior during a specified period of time. For additional information, look at the event properties `prequeue_start_time`, `event_start_time`, and `event_end_time` in the documentation for creating waiting room events. Events are considered active between these start and end times, as well as during the prequeueing period if it exists. `isEventPrequeueing`: Valid only when `isEventActive` is true. Boolean indicating if an event is currently prequeueing users before it starts. `timeUntilEventStart`: Valid only when `isEventPrequeueing` is true. Integer indicating the number of minutes until the event starts. `timeUntilEventStartFormatted`: String displaying the `timeUntilEventStart` formatted in English for users. If `isEventPrequeueing` is false, `timeUntilEventStartFormatted` will display unavailable. `timeUntilEventEnd`: Valid only when `isEventActive` is true. Integer indicating the number of minutes until the event ends. `timeUntilEventEndFormatted`: String displaying the `timeUntilEventEnd` formatted in English for users. If `isEventActive` is false, `timeUntilEventEndFormatted` will display unavailable. `shuffleAtEventStart`: Valid only when `isEventActive` is true. Boolean indicating if the users in the prequeue are shuffled randomly when the event starts. An example cURL to a waiting room could be: `curl -X GET "https://example.com/waitingroom" \ -H "Accept: application/json"` If `json_response_enabled` is true and the request hits the waiting room, an example JSON response when `queueingMethod` is fifo and no event is active could be: { "cfWaitingRoom": { "inWaitingRoom": true, "waitTimeKnown": true, "waitTime": 10, "waitTime25Percentile": 0, "waitTime50Percentile": 0, "waitTime75Percentile": 0, "waitTimeFormatted": "10 minutes", "queueIsFull": false, "queueAll": false, "lastUpdated": "2020-08-03T23:46:00.000Z", "refreshIntervalSeconds": 20, "queueingMethod": "fifo", "isFIFOQueue": true, "isRandomQueue": false, "isPassthroughQueue": false, "isRejectQueue": false, "isEventActive": false, "isEventPrequeueing": false, "timeUntilEventStart": 0, "timeUntilEventStartFormatted": "unavailable", "timeUntilEventEnd": 0, "timeUntilEventEndFormatted": "unavailable", "shuffleAtEventStart": false } } If `json_response_enabled` is true and the request hits the waiting room, an example JSON response when `queueingMethod` is random and an event is active could be: { "cfWaitingRoom": { "inWaitingRoom": true, "waitTimeKnown": true, "waitTime": 10, "waitTime25Percentile": 5, "waitTime50Percentile": 10, "waitTime75Percentile": 15, "waitTimeFormatted": "5 minutes to 15 minutes", "queueIsFull": false, "queueAll": false, "lastUpdated": "2020-08-03T23:46:00.000Z", "refreshIntervalSeconds": 20, "queueingMethod": "random", "isFIFOQueue": false, "isRandomQueue": true, "isPassthroughQueue": false, "isRejectQueue": false, "isEventActive": true, "isEventPrequeueing": false, "timeUntilEventStart": 0, "timeUntilEventStartFormatted": "unavailable", "timeUntilEventEnd": 15, "timeUntilEventEndFormatted": "15 minutes", "shuffleAtEventStart": true } } `false`	default value: false valid values: (true,false)
suspended boolean	Suspends or allows traffic going to the waiting room. If set to `true`, the traffic will not go to the waiting room. `false`	default value: false valid values: (true,false)
description string	A note that you can use to add more details about the waiting room. `"Production - DO NOT MODIFY"`	default value:
session_duration integer	Lifetime of a cookie (in minutes) set by Cloudflare for users who get access to the route. If a user is not seen by Cloudflare again in that time period, they will be treated as a new user that visits the route. `10`	default value: 5 min value:1 max value:30
default_template_language string	The language of the default page template. If no default_template_language is provided, then `en-US` (English) will be used. `"es-ES"`	default value: en-US valid values: en-US, es-ES, de-DE, fr-FR, it-IT, ja-JP, ko-KR, pt-BR, zh-CN, zh-TW, nl-NL, pl-PL, id-ID, tr-TR, ar-EG

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/waiting_rooms/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"production_webinar","description":"Production - DO NOT MODIFY","suspended":false,"host":"shop.example.com","path":"/shop/checkout","queue_all":true,"new_users_per_minute":1000,"total_active_users":1000,"session_duration":10,"disable_session_renewal":false,"json_response_enabled":false,"queueing_method":"fifo","cookie_attributes":{"samesite":"auto","secure":"auto"},"custom_page_html":"{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Queue all enabled {{/waitTimeKnown}}","default_template_language":"es-ES"}'

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",
    "name": "production_webinar",
    "description": "Production - DO NOT MODIFY",
    "suspended": false,
    "host": "shop.example.com",
    "path": "/shop/checkout",
    "queue_all": true,
    "new_users_per_minute": 1000,
    "total_active_users": 1000,
    "session_duration": 10,
    "disable_session_renewal": false,
    "json_response_enabled": false,
    "queueing_method": "fifo",
    "cookie_attributes": {
      "samesite": "auto",
      "secure": "auto"
    },
    "custom_page_html": "{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Queue all enabled {{/waitTimeKnown}}",
    "default_template_language": "es-ES",
    "next_event_prequeue_start_time": "2021-09-28T15:00:00.000Z",
    "next_event_start_time": "2021-09-28T15:00:00.000Z"
  }
}

waiting-room-patch-waiting-room

PATCH Patch waiting room
free
pro
business
enterprise

Patches a configured waiting room.

PATCH zones/:zone_identifier/waiting_rooms/:waiting_room_id

Required parameters

Name /type	Description /example	Constraints
host string	The host name to which the waiting room will be applied (no wildcards). Please do not include the scheme (http:// or https://). The host and path combination must be unique. `"shop.example.com"`
total_active_users integer	Sets the total number of active user sessions on the route at a point in time. A route is a combination of host and path on which a waiting room is available. This value is used as a baseline for the total number of active user sessions on the route. It is possible to have a situation where there are more or less active users sessions on the route based on the traffic patterns at that time around the world. `1000`	min value:200 max value:2147483647
name string	A unique name to identify the waiting room. Only alphanumeric characters, hyphens and underscores are allowed. `"production_webinar"`
new_users_per_minute integer	Sets the number of new users that will be let into the route every minute. This value is used as baseline for the number of users that are let in per minute. So it is possible that there is a little more or little less traffic coming to the route based on the traffic patterns at that time around the world. `1000`	min value:200 max value:2147483647

Optional parameters

Name /type	Description /example	Constraints
path string	Sets the path within the host to enable the waiting room on. The waiting room will be enabled for all subpaths as well. If there are two waiting rooms on the same subpath, the waiting room for the most specific path will be chosen. Wildcards and query parameters are not supported. `"/shop/checkout"`	default value: /
custom_page_html string	Only available for the Waiting Room Advanced subscription. This is a template html file that will be rendered at the edge. If no custom_page_html is provided, the default waiting room will be used. The template is based on mustache ( https://mustache.github.io/ ). There are several variables that are evaluated by the Cloudflare edge: {{`waitTimeKnown`}} Acts like a boolean value that indicates the behavior to take when wait time is not available, for instance when queue_all is true. {{`waitTimeFormatted`}} Estimated wait time for the user. For example, five minutes. Alternatively, you can use: {{`waitTime`}} Number of minutes of estimated wait for a user. {{`waitTimeHours`}} Number of hours of estimated wait for a user (`Math.floor(waitTime/60)`). {{`waitTimeHourMinutes`}} Number of minutes above the `waitTimeHours` value (`waitTime%60`). {{`queueIsFull`}} Changes to true when no more people can be added to the queue. To view the full list of variables, look at the `cfWaitingRoom` object described under the `json_response_enabled` property in other Waiting Room API calls. `"{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Queue all enabled {{/waitTimeKnown}}"`	default value:
queueing_method string	Sets the queueing method used by the waiting room. Changing this parameter from the default queueing method is only available for the Waiting Room Advanced subscription. Regardless of the queueing method, if `queue_all` is enabled or an event is prequeueing, users in the waiting room will not be accepted to the origin. These users will always see a waiting room page that refreshes automatically. The valid queueing methods are: `fifo` (default): First-In-First-Out queue where customers gain access in the order they arrived. `random`: Random queue where customers gain access randomly, regardless of arrival time. `passthrough`: Users will pass directly through the waiting room and into the origin website. As a result, any configured limits will not be respected while this is enabled. This method can be used as an alternative to disabling a waiting room (with `suspended`) so that analytics are still reported. This can be used if you wish to allow all traffic normally, but want to restrict traffic during a waiting room event, or vice versa. `reject`: Users will be immediately rejected from the waiting room. As a result, no users will reach the origin website while this is enabled. This can be used if you wish to reject all traffic while performing maintenance, block traffic during a specified period of time (an event), or block traffic while events are not occurring. Consider a waiting room used for vaccine distribution that only allows traffic during sign-up events, and otherwise blocks all traffic. For this case, the waiting room uses `reject`, and its events override this with `fifo`, `random`, or `passthrough`. When this queueing method is enabled and neither `queueAll` is enabled nor an event is prequeueing, the waiting room page will not refresh automatically. `"fifo"`	default value: fifo valid values: fifo, random, passthrough, reject
cookie_attributes object	Configures cookie attributes for the waiting room cookie. This encrypted cookie stores a user's status in the waiting room, such as queue position. `{ "samesite": "auto", "secure": "auto" }` An object with the following properties: Show definition »
queue_all boolean	If queue_all is `true`, all the traffic that is coming to a route will be sent to the waiting room. No new traffic can get to the route once this field is set and estimated time will become unavailable. `true`	default value: false valid values: (true,false)
disable_session_renewal boolean	Only available for the Waiting Room Advanced subscription. Disables automatic renewal of session cookies. If `true`, an accepted user will have session_duration minutes to browse the site. After that, they will have to go through the waiting room again. If `false`, a user's session cookie will be automatically renewed on every request. `false`	default value: false valid values: (true,false)
json_response_enabled boolean	Only available for the Waiting Room Advanced subscription. If `true`, requests to the waiting room with the header `Accept: application/json` will receive a JSON response object with information on the user's status in the waiting room as opposed to the configured static HTML page. This JSON response object has one property `cfWaitingRoom` which is an object containing the following fields: `inWaitingRoom`: Boolean indicating if the user is in the waiting room (always true). `waitTimeKnown`: Boolean indicating if the current estimated wait times are accurate. If false, they are not available. `waitTime`: Valid only when `waitTimeKnown` is true. Integer indicating the current estimated time in minutes the user will wait in the waiting room. When `queueingMethod` is random, this is set to `waitTime50Percentile`. `waitTime25Percentile`: Valid only when `queueingMethod` is random and `waitTimeKnown` is true. Integer indicating the current estimated maximum wait time for the 25% of users that gain entry the fastest (25th percentile). `waitTime50Percentile`: Valid only when `queueingMethod` is random and `waitTimeKnown` is true. Integer indicating the current estimated maximum wait time for the 50% of users that gain entry the fastest (50th percentile). In other words, half of the queued users are expected to let into the origin website before `waitTime50Percentile` and half are expected to be let in after it. `waitTime75Percentile`: Valid only when `queueingMethod` is random and `waitTimeKnown` is true. Integer indicating the current estimated maximum wait time for the 75% of users that gain entry the fastest (75th percentile). `waitTimeFormatted`: String displaying the `waitTime` formatted in English for users. If `waitTimeKnown` is false, `waitTimeFormatted` will display unavailable. `queueIsFull`: Boolean indicating if the waiting room's queue is currently full and not accepting new users at the moment. `queueAll`: Boolean indicating if all users will be queued in the waiting room and no one will be let into the origin website. `lastUpdated`: String displaying the timestamp as an ISO 8601 string of the user's last attempt to leave the waiting room and be let into the origin website. The user is able to make another attempt after `refreshIntervalSeconds` past this time. If the user makes a request too soon, it will be ignored and `lastUpdated` will not change. `refreshIntervalSeconds`: Integer indicating the number of seconds after `lastUpdated` until the user is able to make another attempt to leave the waiting room and be let into the origin website. When the `queueingMethod` is `reject`, there is no specified refresh time — it will always be zero. `queueingMethod`: The queueing method currently used by the waiting room. It is either fifo, random, passthrough, or reject. `isFIFOQueue`: Boolean indicating if the waiting room uses a FIFO (First-In-First-Out) queue. `isRandomQueue`: Boolean indicating if the waiting room uses a Random queue where users gain access randomly. `isPassthroughQueue`: Boolean indicating if the waiting room uses a passthrough queue. Keep in mind that when passthrough is enabled, this JSON response will only exist when `queueAll` is true or `isEventPrequeueing` is true because in all other cases requests will go directly to the origin. `isRejectQueue`: Boolean indicating if the waiting room uses a reject queue. `isEventActive`: Boolean indicating if an event is currently occurring. Events are able to change a waiting room's behavior during a specified period of time. For additional information, look at the event properties `prequeue_start_time`, `event_start_time`, and `event_end_time` in the documentation for creating waiting room events. Events are considered active between these start and end times, as well as during the prequeueing period if it exists. `isEventPrequeueing`: Valid only when `isEventActive` is true. Boolean indicating if an event is currently prequeueing users before it starts. `timeUntilEventStart`: Valid only when `isEventPrequeueing` is true. Integer indicating the number of minutes until the event starts. `timeUntilEventStartFormatted`: String displaying the `timeUntilEventStart` formatted in English for users. If `isEventPrequeueing` is false, `timeUntilEventStartFormatted` will display unavailable. `timeUntilEventEnd`: Valid only when `isEventActive` is true. Integer indicating the number of minutes until the event ends. `timeUntilEventEndFormatted`: String displaying the `timeUntilEventEnd` formatted in English for users. If `isEventActive` is false, `timeUntilEventEndFormatted` will display unavailable. `shuffleAtEventStart`: Valid only when `isEventActive` is true. Boolean indicating if the users in the prequeue are shuffled randomly when the event starts. An example cURL to a waiting room could be: `curl -X GET "https://example.com/waitingroom" \ -H "Accept: application/json"` If `json_response_enabled` is true and the request hits the waiting room, an example JSON response when `queueingMethod` is fifo and no event is active could be: { "cfWaitingRoom": { "inWaitingRoom": true, "waitTimeKnown": true, "waitTime": 10, "waitTime25Percentile": 0, "waitTime50Percentile": 0, "waitTime75Percentile": 0, "waitTimeFormatted": "10 minutes", "queueIsFull": false, "queueAll": false, "lastUpdated": "2020-08-03T23:46:00.000Z", "refreshIntervalSeconds": 20, "queueingMethod": "fifo", "isFIFOQueue": true, "isRandomQueue": false, "isPassthroughQueue": false, "isRejectQueue": false, "isEventActive": false, "isEventPrequeueing": false, "timeUntilEventStart": 0, "timeUntilEventStartFormatted": "unavailable", "timeUntilEventEnd": 0, "timeUntilEventEndFormatted": "unavailable", "shuffleAtEventStart": false } } If `json_response_enabled` is true and the request hits the waiting room, an example JSON response when `queueingMethod` is random and an event is active could be: { "cfWaitingRoom": { "inWaitingRoom": true, "waitTimeKnown": true, "waitTime": 10, "waitTime25Percentile": 5, "waitTime50Percentile": 10, "waitTime75Percentile": 15, "waitTimeFormatted": "5 minutes to 15 minutes", "queueIsFull": false, "queueAll": false, "lastUpdated": "2020-08-03T23:46:00.000Z", "refreshIntervalSeconds": 20, "queueingMethod": "random", "isFIFOQueue": false, "isRandomQueue": true, "isPassthroughQueue": false, "isRejectQueue": false, "isEventActive": true, "isEventPrequeueing": false, "timeUntilEventStart": 0, "timeUntilEventStartFormatted": "unavailable", "timeUntilEventEnd": 15, "timeUntilEventEndFormatted": "15 minutes", "shuffleAtEventStart": true } } `false`	default value: false valid values: (true,false)
suspended boolean	Suspends or allows traffic going to the waiting room. If set to `true`, the traffic will not go to the waiting room. `false`	default value: false valid values: (true,false)
description string	A note that you can use to add more details about the waiting room. `"Production - DO NOT MODIFY"`	default value:
session_duration integer	Lifetime of a cookie (in minutes) set by Cloudflare for users who get access to the route. If a user is not seen by Cloudflare again in that time period, they will be treated as a new user that visits the route. `10`	default value: 5 min value:1 max value:30
default_template_language string	The language of the default page template. If no default_template_language is provided, then `en-US` (English) will be used. `"es-ES"`	default value: en-US valid values: en-US, es-ES, de-DE, fr-FR, it-IT, ja-JP, ko-KR, pt-BR, zh-CN, zh-TW, nl-NL, pl-PL, id-ID, tr-TR, ar-EG

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/waiting_rooms/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"production_webinar","description":"Production - DO NOT MODIFY","suspended":false,"host":"shop.example.com","path":"/shop/checkout","queue_all":true,"new_users_per_minute":1000,"total_active_users":1000,"session_duration":10,"disable_session_renewal":false,"json_response_enabled":false,"queueing_method":"fifo","cookie_attributes":{"samesite":"auto","secure":"auto"},"custom_page_html":"{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Queue all enabled {{/waitTimeKnown}}","default_template_language":"es-ES"}'

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",
    "name": "production_webinar",
    "description": "Production - DO NOT MODIFY",
    "suspended": false,
    "host": "shop.example.com",
    "path": "/shop/checkout",
    "queue_all": true,
    "new_users_per_minute": 1000,
    "total_active_users": 1000,
    "session_duration": 10,
    "disable_session_renewal": false,
    "json_response_enabled": false,
    "queueing_method": "fifo",
    "cookie_attributes": {
      "samesite": "auto",
      "secure": "auto"
    },
    "custom_page_html": "{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Queue all enabled {{/waitTimeKnown}}",
    "default_template_language": "es-ES",
    "next_event_prequeue_start_time": "2021-09-28T15:00:00.000Z",
    "next_event_start_time": "2021-09-28T15:00:00.000Z"
  }
}

waiting-room-delete-waiting-room

DELETE Delete waiting room
free
pro
business
enterprise

Deletes a waiting room.

DELETE zones/:zone_identifier/waiting_rooms/:waiting_room_id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/waiting_rooms/699d98642c564d2e855e9661899b7252" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

waiting-room-list-events

GET List events
free
pro
business
enterprise

Lists events for a waiting room.

GET zones/:zone_identifier/waiting_rooms/:waiting_room_id/events

Optional parameters

Name /type	Description /example	Constraints
page number	Page number of paginated results. `1`	default value: 1 min value:1
per_page number	Sets the number of items per page. `25`	default value: 25 min value:5 max value:1000

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/waiting_rooms/699d98642c564d2e855e9661899b7252/events?page=1&per_page=25" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "25756b2dfe6e378a06b033b670413757",
      "created_on": "2014-01-01T05:20:00.12345Z",
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "name": "production_webinar_event",
      "description": "Production event - DO NOT MODIFY",
      "suspended": false,
      "prequeue_start_time": "2021-09-28T15:00:00.000Z",
      "event_start_time": "2021-09-28T15:30:00.000Z",
      "event_end_time": "2021-09-28T17:00:00.000Z",
      "shuffle_at_event_start": false,
      "new_users_per_minute": 2000,
      "total_active_users": 2500,
      "session_duration": null,
      "disable_session_renewal": null,
      "queueing_method": "random",
      "custom_page_html": "{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Event is prequeueing / Queue all enabled {{/waitTimeKnown}}"
    }
  ]
}

waiting-room-create-event

POST Create event
free
pro
business
enterprise

Only available for the Waiting Room Advanced subscription. Creates an event for a waiting room. An event takes place during a specified period of time, temporarily changing the behavior of a waiting room. While the event is active, some of the properties in the event's configuration may either override or inherit from the waiting room's configuration. Note that events cannot overlap with each other, so only one event can be active at a time.

POST zones/:zone_identifier/waiting_rooms/:waiting_room_id/events

Required parameters

Name /type	Description /example	Constraints
name string	A unique name to identify the event. Only alphanumeric characters, hyphens and underscores are allowed. `"production_webinar_event"`
event_start_time string	An ISO 8601 timestamp that marks the start of the event. At this time, queued users will be processed with the event's configuration. The start time must be at least one minute before `event_end_time`. `"2021-09-28T15:30:00.000Z"`
event_end_time string	An ISO 8601 timestamp that marks the end of the event. `"2021-09-28T17:00:00.000Z"`

Optional parameters

Name /type	Description /example	Constraints
total_active_users integernull	If set, the event will override the waiting room's `total_active_users` property while it is active. If null, the event will inherit it. This can only be set if the event's `new_users_per_minute` property is also set. `2500`	default value: null min value:200 max value:2147483647
new_users_per_minute integernull	If set, the event will override the waiting room's `new_users_per_minute` property while it is active. If null, the event will inherit it. This can only be set if the event's `total_active_users` property is also set. `2000`	default value: null min value:200 max value:2147483647
custom_page_html stringnull	If set, the event will override the waiting room's `custom_page_html` property while it is active. If null, the event will inherit it. `"{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Event is prequeueing / Queue all enabled {{/waitTimeKnown}}"`	default value: null
queueing_method stringnull	If set, the event will override the waiting room's `queueing_method` property while it is active. If null, the event will inherit it. `"random"`	default value: null
shuffle_at_event_start boolean	If enabled, users in the prequeue will be shuffled randomly at the `event_start_time`. Requires that `prequeue_start_time` is not null. This is useful for situations when many users will join the event prequeue at the same time and you want to shuffle them to ensure fairness. Naturally, it makes the most sense to enable this feature when the `queueing_method` during the event respects ordering such as fifo, or else the shuffling may be unnecessary. `false`	default value: false valid values: (true,false)
disable_session_renewal booleannull	If set, the event will override the waiting room's `disable_session_renewal` property while it is active. If null, the event will inherit it. `null`	default value: null
prequeue_start_time stringnull	An ISO 8601 timestamp that marks when to begin queueing all users before the event starts. The prequeue must start at least five minutes before `event_start_time`. `"2021-09-28T15:00:00.000Z"`	default value: null
suspended boolean	Suspends or allows an event. If set to `true`, the event is ignored and traffic will be handled based on the waiting room configuration. `false`	default value: false valid values: (true,false)
description string	A note that you can use to add more details about the event. `"Production event - DO NOT MODIFY"`	default value:
session_duration integernull	If set, the event will override the waiting room's `session_duration` property while it is active. If null, the event will inherit it. `null`	default value: null min value:1 max value:30

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/waiting_rooms/699d98642c564d2e855e9661899b7252/events" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"production_webinar_event","description":"Production event - DO NOT MODIFY","suspended":false,"prequeue_start_time":"2021-09-28T15:00:00.000Z","event_start_time":"2021-09-28T15:30:00.000Z","event_end_time":"2021-09-28T17:00:00.000Z","shuffle_at_event_start":false,"new_users_per_minute":2000,"total_active_users":2500,"session_duration":null,"disable_session_renewal":null,"queueing_method":"random","custom_page_html":"{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Event is prequeueing / Queue all enabled {{/waitTimeKnown}}"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "25756b2dfe6e378a06b033b670413757",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "name": "production_webinar_event",
    "description": "Production event - DO NOT MODIFY",
    "suspended": false,
    "prequeue_start_time": "2021-09-28T15:00:00.000Z",
    "event_start_time": "2021-09-28T15:30:00.000Z",
    "event_end_time": "2021-09-28T17:00:00.000Z",
    "shuffle_at_event_start": false,
    "new_users_per_minute": 2000,
    "total_active_users": 2500,
    "session_duration": null,
    "disable_session_renewal": null,
    "queueing_method": "random",
    "custom_page_html": "{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Event is prequeueing / Queue all enabled {{/waitTimeKnown}}"
  }
}

waiting-room-event-details

GET Event details
free
pro
business
enterprise

Fetches a single configured event for a waiting room.

GET zones/:zone_identifier/waiting_rooms/:waiting_room_id/events/:event_id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/waiting_rooms/699d98642c564d2e855e9661899b7252/events/25756b2dfe6e378a06b033b670413757" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "25756b2dfe6e378a06b033b670413757",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "name": "production_webinar_event",
    "description": "Production event - DO NOT MODIFY",
    "suspended": false,
    "prequeue_start_time": "2021-09-28T15:00:00.000Z",
    "event_start_time": "2021-09-28T15:30:00.000Z",
    "event_end_time": "2021-09-28T17:00:00.000Z",
    "shuffle_at_event_start": false,
    "new_users_per_minute": 2000,
    "total_active_users": 2500,
    "session_duration": null,
    "disable_session_renewal": null,
    "queueing_method": "random",
    "custom_page_html": "{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Event is prequeueing / Queue all enabled {{/waitTimeKnown}}"
  }
}

waiting-room-update-event

PUT Update event
free
pro
business
enterprise

Updates a configured event for a waiting room.

PUT zones/:zone_identifier/waiting_rooms/:waiting_room_id/events/:event_id

Required parameters

Name /type	Description /example	Constraints
name string	A unique name to identify the event. Only alphanumeric characters, hyphens and underscores are allowed. `"production_webinar_event"`
event_start_time string	An ISO 8601 timestamp that marks the start of the event. At this time, queued users will be processed with the event's configuration. The start time must be at least one minute before `event_end_time`. `"2021-09-28T15:30:00.000Z"`
event_end_time string	An ISO 8601 timestamp that marks the end of the event. `"2021-09-28T17:00:00.000Z"`

Optional parameters

Name /type	Description /example	Constraints
total_active_users integernull	If set, the event will override the waiting room's `total_active_users` property while it is active. If null, the event will inherit it. This can only be set if the event's `new_users_per_minute` property is also set. `2500`	default value: null min value:200 max value:2147483647
new_users_per_minute integernull	If set, the event will override the waiting room's `new_users_per_minute` property while it is active. If null, the event will inherit it. This can only be set if the event's `total_active_users` property is also set. `2000`	default value: null min value:200 max value:2147483647
custom_page_html stringnull	If set, the event will override the waiting room's `custom_page_html` property while it is active. If null, the event will inherit it. `"{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Event is prequeueing / Queue all enabled {{/waitTimeKnown}}"`	default value: null
queueing_method stringnull	If set, the event will override the waiting room's `queueing_method` property while it is active. If null, the event will inherit it. `"random"`	default value: null
shuffle_at_event_start boolean	If enabled, users in the prequeue will be shuffled randomly at the `event_start_time`. Requires that `prequeue_start_time` is not null. This is useful for situations when many users will join the event prequeue at the same time and you want to shuffle them to ensure fairness. Naturally, it makes the most sense to enable this feature when the `queueing_method` during the event respects ordering such as fifo, or else the shuffling may be unnecessary. `false`	default value: false valid values: (true,false)
disable_session_renewal booleannull	If set, the event will override the waiting room's `disable_session_renewal` property while it is active. If null, the event will inherit it. `null`	default value: null
prequeue_start_time stringnull	An ISO 8601 timestamp that marks when to begin queueing all users before the event starts. The prequeue must start at least five minutes before `event_start_time`. `"2021-09-28T15:00:00.000Z"`	default value: null
suspended boolean	Suspends or allows an event. If set to `true`, the event is ignored and traffic will be handled based on the waiting room configuration. `false`	default value: false valid values: (true,false)
description string	A note that you can use to add more details about the event. `"Production event - DO NOT MODIFY"`	default value:
session_duration integernull	If set, the event will override the waiting room's `session_duration` property while it is active. If null, the event will inherit it. `null`	default value: null min value:1 max value:30

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/waiting_rooms/699d98642c564d2e855e9661899b7252/events/25756b2dfe6e378a06b033b670413757" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"production_webinar_event","description":"Production event - DO NOT MODIFY","suspended":false,"prequeue_start_time":"2021-09-28T15:00:00.000Z","event_start_time":"2021-09-28T15:30:00.000Z","event_end_time":"2021-09-28T17:00:00.000Z","shuffle_at_event_start":false,"new_users_per_minute":2000,"total_active_users":2500,"session_duration":null,"disable_session_renewal":null,"queueing_method":"random","custom_page_html":"{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Event is prequeueing / Queue all enabled {{/waitTimeKnown}}"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "25756b2dfe6e378a06b033b670413757",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "name": "production_webinar_event",
    "description": "Production event - DO NOT MODIFY",
    "suspended": false,
    "prequeue_start_time": "2021-09-28T15:00:00.000Z",
    "event_start_time": "2021-09-28T15:30:00.000Z",
    "event_end_time": "2021-09-28T17:00:00.000Z",
    "shuffle_at_event_start": false,
    "new_users_per_minute": 2000,
    "total_active_users": 2500,
    "session_duration": null,
    "disable_session_renewal": null,
    "queueing_method": "random",
    "custom_page_html": "{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Event is prequeueing / Queue all enabled {{/waitTimeKnown}}"
  }
}

waiting-room-patch-event

PATCH Patch event
free
pro
business
enterprise

Patches a configured event for a waiting room.

PATCH zones/:zone_identifier/waiting_rooms/:waiting_room_id/events/:event_id

Required parameters

Name /type	Description /example	Constraints
name string	A unique name to identify the event. Only alphanumeric characters, hyphens and underscores are allowed. `"production_webinar_event"`
event_start_time string	An ISO 8601 timestamp that marks the start of the event. At this time, queued users will be processed with the event's configuration. The start time must be at least one minute before `event_end_time`. `"2021-09-28T15:30:00.000Z"`
event_end_time string	An ISO 8601 timestamp that marks the end of the event. `"2021-09-28T17:00:00.000Z"`

Optional parameters

Name /type	Description /example	Constraints
total_active_users integernull	If set, the event will override the waiting room's `total_active_users` property while it is active. If null, the event will inherit it. This can only be set if the event's `new_users_per_minute` property is also set. `2500`	default value: null min value:200 max value:2147483647
new_users_per_minute integernull	If set, the event will override the waiting room's `new_users_per_minute` property while it is active. If null, the event will inherit it. This can only be set if the event's `total_active_users` property is also set. `2000`	default value: null min value:200 max value:2147483647
custom_page_html stringnull	If set, the event will override the waiting room's `custom_page_html` property while it is active. If null, the event will inherit it. `"{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Event is prequeueing / Queue all enabled {{/waitTimeKnown}}"`	default value: null
queueing_method stringnull	If set, the event will override the waiting room's `queueing_method` property while it is active. If null, the event will inherit it. `"random"`	default value: null
shuffle_at_event_start boolean	If enabled, users in the prequeue will be shuffled randomly at the `event_start_time`. Requires that `prequeue_start_time` is not null. This is useful for situations when many users will join the event prequeue at the same time and you want to shuffle them to ensure fairness. Naturally, it makes the most sense to enable this feature when the `queueing_method` during the event respects ordering such as fifo, or else the shuffling may be unnecessary. `false`	default value: false valid values: (true,false)
disable_session_renewal booleannull	If set, the event will override the waiting room's `disable_session_renewal` property while it is active. If null, the event will inherit it. `null`	default value: null
prequeue_start_time stringnull	An ISO 8601 timestamp that marks when to begin queueing all users before the event starts. The prequeue must start at least five minutes before `event_start_time`. `"2021-09-28T15:00:00.000Z"`	default value: null
suspended boolean	Suspends or allows an event. If set to `true`, the event is ignored and traffic will be handled based on the waiting room configuration. `false`	default value: false valid values: (true,false)
description string	A note that you can use to add more details about the event. `"Production event - DO NOT MODIFY"`	default value:
session_duration integernull	If set, the event will override the waiting room's `session_duration` property while it is active. If null, the event will inherit it. `null`	default value: null min value:1 max value:30

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/waiting_rooms/699d98642c564d2e855e9661899b7252/events/25756b2dfe6e378a06b033b670413757" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"production_webinar_event","description":"Production event - DO NOT MODIFY","suspended":false,"prequeue_start_time":"2021-09-28T15:00:00.000Z","event_start_time":"2021-09-28T15:30:00.000Z","event_end_time":"2021-09-28T17:00:00.000Z","shuffle_at_event_start":false,"new_users_per_minute":2000,"total_active_users":2500,"session_duration":null,"disable_session_renewal":null,"queueing_method":"random","custom_page_html":"{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Event is prequeueing / Queue all enabled {{/waitTimeKnown}}"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "25756b2dfe6e378a06b033b670413757",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "name": "production_webinar_event",
    "description": "Production event - DO NOT MODIFY",
    "suspended": false,
    "prequeue_start_time": "2021-09-28T15:00:00.000Z",
    "event_start_time": "2021-09-28T15:30:00.000Z",
    "event_end_time": "2021-09-28T17:00:00.000Z",
    "shuffle_at_event_start": false,
    "new_users_per_minute": 2000,
    "total_active_users": 2500,
    "session_duration": null,
    "disable_session_renewal": null,
    "queueing_method": "random",
    "custom_page_html": "{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Event is prequeueing / Queue all enabled {{/waitTimeKnown}}"
  }
}

waiting-room-delete-event

DELETE Delete event
free
pro
business
enterprise

Deletes an event for a waiting room.

DELETE zones/:zone_identifier/waiting_rooms/:waiting_room_id/events/:event_id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/waiting_rooms/699d98642c564d2e855e9661899b7252/events/25756b2dfe6e378a06b033b670413757" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

waiting-room-preview-active-event-details

GET Preview active event details
free
pro
business
enterprise

Previews an event's configuration as if it was active. Inherited fields from the waiting room will be displayed with their current values.

GET zones/:zone_identifier/waiting_rooms/:waiting_room_id/events/:event_id/details

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/waiting_rooms/699d98642c564d2e855e9661899b7252/events/25756b2dfe6e378a06b033b670413757/details" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "25756b2dfe6e378a06b033b670413757",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "name": "production_webinar_event",
    "description": "Production event - DO NOT MODIFY",
    "suspended": false,
    "prequeue_start_time": "2021-09-28T15:00:00.000Z",
    "event_start_time": "2021-09-28T15:30:00.000Z",
    "event_end_time": "2021-09-28T17:00:00.000Z",
    "shuffle_at_event_start": false,
    "new_users_per_minute": 2000,
    "total_active_users": 2500,
    "session_duration": 10,
    "disable_session_renewal": false,
    "queueing_method": "random",
    "custom_page_html": "{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Event is prequeueing / Queue all enabled {{/waitTimeKnown}}"
  }
}

waiting-room-get-waiting-room-status

GET Get waiting room status
free
pro
business
enterprise

Fetches the status of a configured waiting room. Response fields include:

status: String indicating the status of the waiting room. The possible status are:
- not_queueing indicates that the configured thresholds have not been met and all users are going through to the origin.
- queueing indicates that the thresholds have been met and some users are held in the waiting room.
- event_prequeueing indicates that an event is active and is currently prequeueing users before it starts.
event_id: String of the current event's id if an event is active, otherwise an empty string.
estimated_queued_users: Integer of the estimated number of users currently waiting in the queue.
estimated_total_active_users: Integer of the estimated number of users currently active on the origin.
max_estimated_time_minutes: Integer of the maximum estimated time currently presented to the users.

GET zones/:zone_identifier/waiting_rooms/:waiting_room_id/status

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/waiting_rooms/699d98642c564d2e855e9661899b7252/status" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "status": "queueing",
    "event_id": "25756b2dfe6e378a06b033b670413757",
    "estimated_queued_users": 10,
    "estimated_total_active_users": 9,
    "max_estimated_time_minutes": 5
  }
}

waiting-room-create-a-custom-waiting-room-page-preview

POST Create a custom waiting room page preview
free
pro
business
enterprise

Creates a waiting room page preview. Upload a custom waiting room page for preview. You will receive a preview URL in the form http://waitingrooms.dev/preview/<uuid>. You can use the following query parameters to change the state of the preview:

force_queue: Boolean indicating if all users will be queued in the waiting room and no one will be let into the origin website (also known as queueAll).
queue_is_full: Boolean indicating if the waiting room's queue is currently full and not accepting new users at the moment.
queueing_method: The queueing method currently used by the waiting room.
- fifo indicates a FIFO queue.
- random indicates a Random queue.
- passthrough indicates a Passthrough queue. Keep in mind that the waiting room page will only be displayed if force_queue=true or event=prequeueing — for other cases the request will pass through to the origin. For our preview, this will be a fake origin website returning "Welcome".
- reject indicates a Reject queue.
event: Used to preview a waiting room event.
- none indicates no event is occurring.
- prequeueing indicates that an event is prequeueing (between prequeue_start_time and event_start_time).
- started indicates that an event has started (between event_start_time and event_end_time).
shuffle_at_event_start: Boolean indicating if the event will shuffle users in the prequeue when it starts. This can only be set to true if an event is active (event is not none).

For example, you can make a request to http://waitingrooms.dev/preview/<uuid>?force_queue=false&queue_is_full=false&queueing_method=random&event=started&shuffle_at_event_start=true

waitTime: Non-zero, positive integer indicating the estimated wait time in minutes. The default value is 10 minutes.

For example, you can make a request to http://waitingrooms.dev/preview/<uuid>?waitTime=50 to configure the estimated wait time as 50 minutes.

POST zones/:zone_identifier/waiting_rooms/preview

Required parameters

Name /type	Description /example	Constraints
custom_html string	Only available for the Waiting Room Advanced subscription. This is a template html file that will be rendered at the edge. If no custom_page_html is provided, the default waiting room will be used. The template is based on mustache ( https://mustache.github.io/ ). There are several variables that are evaluated by the Cloudflare edge: {{`waitTimeKnown`}} Acts like a boolean value that indicates the behavior to take when wait time is not available, for instance when queue_all is true. {{`waitTimeFormatted`}} Estimated wait time for the user. For example, five minutes. Alternatively, you can use: {{`waitTime`}} Number of minutes of estimated wait for a user. {{`waitTimeHours`}} Number of hours of estimated wait for a user (`Math.floor(waitTime/60)`). {{`waitTimeHourMinutes`}} Number of minutes above the `waitTimeHours` value (`waitTime%60`). {{`queueIsFull`}} Changes to true when no more people can be added to the queue. To view the full list of variables, look at the `cfWaitingRoom` object described under the `json_response_enabled` property in other Waiting Room API calls. `"{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Queue all enabled {{/waitTimeKnown}}"`	default value:

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/waiting_rooms/preview" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"custom_html":"{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Queue all enabled {{/waitTimeKnown}}"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "preview_url": "http://waitingrooms.dev/preview/35af8c12-6d68-4608-babb-b53435a5ddfb"
  }
}

Registrar Domains

Manage domains names with Cloudflare Registrar.

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: user@example.com" \
     -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": "user@example.com",
        "fax": "123-867-5309"
      }
    }
  ]
}

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: user@example.com" \
     -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": "user@example.com",
      "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	Shows whether a registrar lock is in place for a 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: user@example.com" \
     -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": "user@example.com",
      "fax": "123-867-5309"
    }
  }
}

Registrar Domains error codes

Code	Description
10000	Internal server error.
10001	Authentication failure.

Argo Tunnel

A tunnel that can route traffic to a user origin

Please use equivalent Cloudflare Tunnels API endpoints.

argo-tunnel

Object definition

View properties and constraints defined on the object

Show definition

Deprecation Warning

End of life Date: February 4, 2024

This endpoint and its related APIs are deprecated in favor of the Cloudflare Tunnels equivalent APIs.

argo-tunnel-list-argo-tunnels

GET List Argo Tunnels

List, search and filter an account's Argo Tunnels

GET accounts/:account_identifier/tunnels

Optional parameters

Name /type	Description /example	Constraints
name string	A user-friendly name chosen when the tunnel is created. Cannot be empty `"blog"`
uuid string	UUID of the tunnel `"f70ff985-a4ef-4643-bbbc-4a0ed4fc8415"`	max length: 36 read only
is_deleted boolean	If true, only include deleted tunnels. If false, exclude deleted tunnels. If not provided, all tunnels will be included `true`	valid values: (true,false)
existed_at string (date-time)	If provided, include only tunnels that were created before this time and not deleted at this time `"2019-10-12T07:20:50.52Z"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/tunnels?name=blog&uuid=f70ff985-a4ef-4643-bbbc-4a0ed4fc8415&is_deleted=true&existed_at=2019-10-12T07:20:50.52Z" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
      "name": "blog",
      "created_at": "2021-01-25T18:22:34.317854Z",
      "deleted_at": "2009-11-10T23:00:00Z",
      "connections": [
        {
          "colo_name": "DFW",
          "uuid": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
          "is_pending_reconnect": false
        }
      ]
    }
  ]
}

Deprecation Warning

End of life Date: February 4, 2024

This endpoint and its related APIs are deprecated in favor of the Cloudflare Tunnels equivalent APIs.

argo-tunnel-create-argo-tunnel

POST Create Argo Tunnel

Create an Argo Tunnel in an account

POST accounts/:account_identifier/tunnels

Required parameters

Name /type	Description /example	Constraints
name string	A user-friendly name chosen when the tunnel is created. Cannot be empty `"blog"`
tunnel_secret string	32 or more bytes, encoded as a base64 string. The Create Argo Tunnel endpoint sets this as the tunnel's password. Anyone wishing to run the tunnel needs this password `"AQIDBAUGBwgBAgMEBQYHCAECAwQFBgcIAQIDBAUGBwg="`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/tunnels" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"blog","tunnel_secret":"AQIDBAUGBwgBAgMEBQYHCAECAwQFBgcIAQIDBAUGBwg="}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
    "name": "blog",
    "created_at": "2021-01-25T18:22:34.317854Z",
    "deleted_at": "2009-11-10T23:00:00Z",
    "connections": [
      {
        "colo_name": "DFW",
        "uuid": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
        "is_pending_reconnect": false
      }
    ]
  }
}

Deprecation Warning

End of life Date: February 4, 2024

This endpoint and its related APIs are deprecated in favor of the Cloudflare Tunnels equivalent APIs.

argo-tunnel-get-argo-tunnel

GET Get Argo Tunnel

Get the details of an Argo Tunnel from an account

GET accounts/:account_identifier/tunnels/:tunnel_id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/tunnels/f70ff985-a4ef-4643-bbbc-4a0ed4fc8415?" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
    "name": "blog",
    "created_at": "2021-01-25T18:22:34.317854Z",
    "deleted_at": "2009-11-10T23:00:00Z",
    "connections": [
      {
        "colo_name": "DFW",
        "uuid": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
        "is_pending_reconnect": false
      }
    ]
  }
}

Deprecation Warning

End of life Date: February 4, 2024

This endpoint and its related APIs are deprecated in favor of the Cloudflare Tunnels equivalent APIs.

argo-tunnel-delete-argo-tunnel

DELETE Delete Argo Tunnel

Delete an Argo Tunnel from an account

DELETE accounts/:account_identifier/tunnels/:tunnel_id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/tunnels/f70ff985-a4ef-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
    "name": "blog",
    "created_at": "2021-01-25T18:22:34.317854Z",
    "deleted_at": "2009-11-10T23:00:00Z",
    "connections": [
      {
        "colo_name": "DFW",
        "uuid": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
        "is_pending_reconnect": false
      }
    ]
  }
}

Deprecation Warning

End of life Date: February 4, 2024

This endpoint and its related APIs are deprecated in favor of the Cloudflare Tunnels equivalent APIs.

argo-tunnel-clean-up-argo-tunnel-connections

DELETE Clean Up Argo Tunnel Connections

Remove stale connection resources from an Argo Tunnel

DELETE accounts/:account_identifier/tunnels/:tunnel_id/connections

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/tunnels/f70ff985-a4ef-4643-bbbc-4a0ed4fc8415/connections" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{}'

Response (example)

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

Cloudflare Tunnel

A tunnel that can route traffic to a user origin

cloudflare-tunnel

Object definition

View properties and constraints defined on the object

Show definition

cloudflare-tunnel-list-cloudflare-tunnels

GET List Cloudflare Tunnels

List, search and filter an account's Cloudflare Tunnels

GET accounts/:account_identifier/cfd_tunnel

Optional parameters

Name /type	Description /example	Constraints
name string	A user-friendly name chosen when the tunnel is created. Cannot be empty `"blog"`
uuid string	UUID of the tunnel `"f70ff985-a4ef-4643-bbbc-4a0ed4fc8415"`	max length: 36 read only
is_deleted boolean	If true, only include deleted tunnels. If false, exclude deleted tunnels. If not provided, all tunnels will be included `true`	valid values: (true,false)
existed_at string (date-time)	If provided, include only tunnels that were created before this time and not deleted at this time `"2019-10-12T07:20:50.52Z"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/cfd_tunnel?name=blog&uuid=f70ff985-a4ef-4643-bbbc-4a0ed4fc8415&is_deleted=true&existed_at=2019-10-12T07:20:50.52Z" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
      "account_tag": "01a7362d577a6c3019a474fd6f485823",
      "created_at": "2021-01-25T18:22:34.317854Z",
      "deleted_at": "2009-11-10T23:00:00Z",
      "name": "blog",
      "connections": [
        {
          "colo_name": "DFW",
          "id": "1bedc50d-42b3-473c-b108-ff3d10c0d925",
          "is_pending_reconnect": false,
          "client_id": "1bedc50d-42b3-473c-b108-ff3d10c0d925",
          "client_version": "2022.7.1",
          "opened_at": "2021-01-25T18:22:34.317854Z",
          "origin_ip": "85.12.78.6"
        }
      ],
      "conns_active_at": "2009-11-10T23:00:00Z",
      "conns_inactive_at": "2009-11-10T23:00:00Z",
      "status": "active",
      "remote_config": true
    }
  ]
}

cloudflare-tunnel-create-cloudflare-tunnel

POST Create Cloudflare Tunnel

Create a Cloudflare Tunnel in an account

POST accounts/:account_identifier/cfd_tunnel

Required parameters

Name /type	Description /example	Constraints
name string	A user-friendly name chosen when the tunnel is created. Cannot be empty `"blog"`
tunnel_secret string	A secret encoded as a base64 string. The Create Cloudflare Tunnel endpoint sets this as the tunnel's password. Anyone wishing to run the tunnel needs this password `"AQIDBAUGBwgBAgMEBQYHCAECAwQFBgcIAQIDBAUGBwg="`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/cfd_tunnel" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"blog","tunnel_secret":"AQIDBAUGBwgBAgMEBQYHCAECAwQFBgcIAQIDBAUGBwg="}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
    "account_tag": "01a7362d577a6c3019a474fd6f485823",
    "created_at": "2021-01-25T18:22:34.317854Z",
    "deleted_at": "2009-11-10T23:00:00Z",
    "name": "blog",
    "connections": [
      {
        "colo_name": "DFW",
        "id": "1bedc50d-42b3-473c-b108-ff3d10c0d925",
        "is_pending_reconnect": false,
        "client_id": "1bedc50d-42b3-473c-b108-ff3d10c0d925",
        "client_version": "2022.7.1",
        "opened_at": "2021-01-25T18:22:34.317854Z",
        "origin_ip": "85.12.78.6"
      }
    ],
    "conns_active_at": "2009-11-10T23:00:00Z",
    "conns_inactive_at": "2009-11-10T23:00:00Z",
    "status": "active",
    "remote_config": true
  }
}

cloudflare-tunnel-update-cloudflare-tunnel

PATCH Update Cloudflare Tunnel

Updates a Cloudflare Tunnel in an account

PATCH accounts/:account_identifier/cfd_tunnel/:tunnel_id

Optional parameters

Name /type	Description /example	Constraints
name string	A user-friendly name chosen when the tunnel is created. Cannot be empty `"blog"`
tunnel_secret string	A secret encoded as a base64 string. The endpoint sets this as the tunnel's password. Anyone wishing to run the tunnel needs this password `"AQIDBAUGBwgBAgMEBQYHCAECAwQFBgcIAQIDBAUGBwg="`

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/cfd_tunnel/f70ff985-a4ef-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"blog","tunnel_secret":"AQIDBAUGBwgBAgMEBQYHCAECAwQFBgcIAQIDBAUGBwg="}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
    "account_tag": "01a7362d577a6c3019a474fd6f485823",
    "created_at": "2021-01-25T18:22:34.317854Z",
    "deleted_at": "2009-11-10T23:00:00Z",
    "name": "blog",
    "connections": [
      {
        "colo_name": "DFW",
        "id": "1bedc50d-42b3-473c-b108-ff3d10c0d925",
        "is_pending_reconnect": false,
        "client_id": "1bedc50d-42b3-473c-b108-ff3d10c0d925",
        "client_version": "2022.7.1",
        "opened_at": "2021-01-25T18:22:34.317854Z",
        "origin_ip": "85.12.78.6"
      }
    ],
    "conns_active_at": "2009-11-10T23:00:00Z",
    "conns_inactive_at": "2009-11-10T23:00:00Z",
    "status": "active",
    "remote_config": true
  }
}

cloudflare-tunnel-get-cloudflare-tunnel

GET Get Cloudflare Tunnel

Get the details of a Cloudflare Tunnel from an account

GET accounts/:account_identifier/cfd_tunnel/:tunnel_id

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/cfd_tunnel/f70ff985-a4ef-4643-bbbc-4a0ed4fc8415?" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
    "account_tag": "01a7362d577a6c3019a474fd6f485823",
    "created_at": "2021-01-25T18:22:34.317854Z",
    "deleted_at": "2009-11-10T23:00:00Z",
    "name": "blog",
    "connections": [
      {
        "colo_name": "DFW",
        "id": "1bedc50d-42b3-473c-b108-ff3d10c0d925",
        "is_pending_reconnect": false,
        "client_id": "1bedc50d-42b3-473c-b108-ff3d10c0d925",
        "client_version": "2022.7.1",
        "opened_at": "2021-01-25T18:22:34.317854Z",
        "origin_ip": "85.12.78.6"
      }
    ],
    "conns_active_at": "2009-11-10T23:00:00Z",
    "conns_inactive_at": "2009-11-10T23:00:00Z",
    "status": "active",
    "remote_config": true
  }
}

cloudflare-tunnel-delete-cloudflare-tunnel

DELETE Delete Cloudflare Tunnel

Delete a Cloudflare Tunnel from an account

DELETE accounts/:account_identifier/cfd_tunnel/:tunnel_id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/cfd_tunnel/f70ff985-a4ef-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
    "account_tag": "01a7362d577a6c3019a474fd6f485823",
    "created_at": "2021-01-25T18:22:34.317854Z",
    "deleted_at": "2009-11-10T23:00:00Z",
    "name": "blog",
    "connections": [
      {
        "colo_name": "DFW",
        "id": "1bedc50d-42b3-473c-b108-ff3d10c0d925",
        "is_pending_reconnect": false,
        "client_id": "1bedc50d-42b3-473c-b108-ff3d10c0d925",
        "client_version": "2022.7.1",
        "opened_at": "2021-01-25T18:22:34.317854Z",
        "origin_ip": "85.12.78.6"
      }
    ],
    "conns_active_at": "2009-11-10T23:00:00Z",
    "conns_inactive_at": "2009-11-10T23:00:00Z",
    "status": "active",
    "remote_config": true
  }
}

cloudflare-tunnel-list-cloudflare-tunnel-connections

GET List Cloudflare Tunnel Connections

List all of the connection resources for a Cloudflare Tunnel

GET accounts/:account_identifier/cfd_tunnel/:tunnel_id/connections

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/cfd_tunnel/f70ff985-a4ef-4643-bbbc-4a0ed4fc8415/connections?" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "1bedc50d-42b3-473c-b108-ff3d10c0d925",
      "features": [
        "ha-origin"
      ],
      "version": "2022.7.1",
      "arch": "linux_amd64",
      "conns": [
        {
          "colo_name": "DFW",
          "id": "1bedc50d-42b3-473c-b108-ff3d10c0d925",
          "is_pending_reconnect": false,
          "client_id": "1bedc50d-42b3-473c-b108-ff3d10c0d925",
          "client_version": "2022.7.1",
          "opened_at": "2021-01-25T18:22:34.317854Z",
          "origin_ip": "85.12.78.6"
        }
      ],
      "run_at": "2009-11-10T23:00:00Z"
    }
  ]
}

cloudflare-tunnel-clean-up-cloudflare-tunnel-connections

DELETE Clean Up Cloudflare Tunnel Connections

Remove stale connection resources from a Cloudflare Tunnel

DELETE accounts/:account_identifier/cfd_tunnel/:tunnel_id/connections

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/cfd_tunnel/f70ff985-a4ef-4643-bbbc-4a0ed4fc8415/connections" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{}'

Response (example)

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

cloudflare-tunnel-get-cloudflare-tunnel-token

GET Get Cloudflare Tunnel Token

Gets the Tunnel for a previously created Cloudflare Tunnel

GET accounts/:account_identifier/cfd_tunnel/:tunnel_id/token

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/cfd_tunnel/f70ff985-a4ef-4643-bbbc-4a0ed4fc8415/token?" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": "ZHNraGdhc2RraGFza2hqZGFza2poZGFza2poYXNrZGpoYWtzamRoa2FzZGpoa2FzamRoa2Rhc2po\na2FzamRoa2FqCg=="
}

Cloudflare Tunnel configuration

Remote Configuration for Cloudflare tunnel

cloudflare-tunnel-configuration

Object definition

View properties and constraints defined on the object

Show definition

cloudflare-tunnel-configuration-put-configuration

PUT Put Configuration

Add or update a configuration for a cloudflared tunnel

PUT accounts/:account_identifier/cfd_tunnel/:tunnel_id/configurations

Optional parameters

Name /type	Description /example	Constraints
config object	This is a json that conforms to the same syntax rules as the config.yaml `"{\"warp-routing\": {\"enabled\": true}, \"originRequest\" : {\"connectTimeout\": 10}, \"ingress\" : [ {\"hostname\": \"test\", \"service\": \"https://localhost:8000\" } , {\"service\": \"http_status:404\"} ]}"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/cfd_tunnel/f70ff985-a4ef-4643-bbbc-4a0ed4fc8415/configurations" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"config":"{\"warp-routing\": {\"enabled\": true},  \"originRequest\" : {\"connectTimeout\": 10}, \"ingress\" : [ {\"hostname\": \"test\", \"service\": \"https://localhost:8000\" } , {\"service\": \"http_status:404\"} ]}"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "config": "{\"warp-routing\": {\"enabled\": true},  \"originRequest\" : {\"connectTimeout\": 10}, \"ingress\" : [ {\"hostname\": \"test\", \"service\": \"https://localhost:8000\" } , {\"service\": \"http_status:404\"} ]}",
    "tunnel_id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
    "version": 5,
    "created_at": "2021-01-25T18:22:34.317854Z"
  }
}

cloudflare-tunnel-configuration-get-configuration

GET Get Configuration

Get the configuration of a specific Cloudflare Tunnel

GET accounts/:account_identifier/cfd_tunnel/:tunnel_id/configurations

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/cfd_tunnel/f70ff985-a4ef-4643-bbbc-4a0ed4fc8415/configurations" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "config": "{\"warp-routing\": {\"enabled\": true},  \"originRequest\" : {\"connectTimeout\": 10}, \"ingress\" : [ {\"hostname\": \"test\", \"service\": \"https://localhost:8000\" } , {\"service\": \"http_status:404\"} ]}",
    "tunnel_id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
    "version": 5,
    "created_at": "2021-01-25T18:22:34.317854Z"
  }
}

Tunnel Route

A network address range that the Tunnel connects.

tunnel-route

Object definition

View properties and constraints defined on the object

Show definition

tunnel-route-list-tunnel-routes

GET List Tunnel Routes

List, search and filter an account's tunnel routes

GET accounts/:account_identifier/teamnet/routes

Optional parameters

Name /type	Description /example	Constraints
tunnel_id string	UUID of the tunnel `"f70ff985-a4ef-4643-bbbc-4a0ed4fc8415"`	max length: 36 read only
comment string	Optional remark describing the route. Empty if none `"Example comment for this route"`
is_deleted boolean	If true, only include deleted routes. If false, exclude deleted routes. If not provided, all routes will be included `true`	valid values: (true,false)
network_subset string	If set, only list routes that are a subset of this network `"172.16.0.0%2F16"`
network_superset string	If set, only list routes that are a superset of this network `"172.16.0.0%2F16"`
existed_at string (date-time)	If provided, include only routes that were created before this time and not deleted at this time `"2019-10-12T07:20:50.52Z"`
virtual_network_id string	UUID of the virtual network `"f70ff985-a4ef-4643-bbbc-4a0ed4fc8415"`	max length: 36 read only

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/teamnet/routes?tunnel_id=f70ff985-a4ef-4643-bbbc-4a0ed4fc8415&comment=Example comment for this route&is_deleted=true&network_subset=172.16.0.0%2F16&network_superset=172.16.0.0%2F16&existed_at=2019-10-12T07:20:50.52Z&virtual_network_id=f70ff985-a4ef-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "network": "172.16.0.0/16",
      "tunnel_id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
      "tunnel_name": "blog",
      "comment": "Example comment for this route",
      "created_at": "2021-01-25T18:22:34.317854Z",
      "deleted_at": "2021-01-25T18:22:34.317854Z",
      "virtual_network_id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415"
    }
  ]
}

tunnel-route-get-tunnel-route-by-ip

GET Get Tunnel Route by IP

Find the Tunnel Route that encompasses the given IP

GET accounts/:account_identifier/teamnet/routes/ip/:ip

Optional parameters

Name /type	Description /example	Constraints
virtual_network_id string	UUID of the virtual network `"f70ff985-a4ef-4643-bbbc-4a0ed4fc8415"`	max length: 36 read only

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/teamnet/routes/ip/10.1.0.137?virtual_network_id=f70ff985-a4ef-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "network": "172.16.0.0/16",
    "tunnel_id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
    "tunnel_name": "blog",
    "comment": "Example comment for this route",
    "created_at": "2021-01-25T18:22:34.317854Z",
    "deleted_at": "2021-01-25T18:22:34.317854Z",
    "virtual_network_id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415"
  }
}

tunnel-route-create-route

POST Create Route

Add a new route to the account's routing table for the given tunnel

POST accounts/:account_identifier/teamnet/routes/network/:ip_network_encoded

Required parameters

Name /type	Description /example	Constraints
tunnel_id string	UUID of the tunnel for which this route is being added `"f70ff985-a4ef-4643-bbbc-4a0ed4fc8415"`	max length: 36 read only

Optional parameters

Name /type	Description /example	Constraints
comment string	Optional remark describing the route. Empty if none `"Example comment for this route"`
virtual_network_id string	optional UUID of the virtual network for which this route is being added; uses the default virtual network of the account if none is provided `"f70ff985-a4ef-4643-bbbc-4a0ed4fc8415"`	max length: 36 read only

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/teamnet/routes/network/172.16.0.0%2F16" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"tunnel_id":"f70ff985-a4ef-4643-bbbc-4a0ed4fc8415","comment":"Example comment for this route","virtual_network_id":"f70ff985-a4ef-4643-bbbc-4a0ed4fc8415"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "network": "172.16.0.0/16",
    "tunnel_id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
    "tunnel_name": "blog",
    "comment": "Example comment for this route",
    "created_at": "2021-01-25T18:22:34.317854Z",
    "deleted_at": "2021-01-25T18:22:34.317854Z",
    "virtual_network_id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415"
  }
}

tunnel-route-update-route

PATCH Update Route

Update an existing route in the account's routing table for the given tunnel

PATCH accounts/:account_identifier/teamnet/routes/network/:ip_network_encoded

Optional parameters

Name /type	Description /example	Constraints
tunnel_id string	UUID of the tunnel this route should belong to `"f70ff985-a4ef-4643-bbbc-4a0ed4fc8415"`	max length: 36 read only
comment string	Optional remark describing the route. Empty if none `"Example comment for this route"`
network string	New CIDR of this route `"172.16.0.0/16"`
virtual_network_id string	UUID of the virtual network to which this route belongs to `"f70ff985-a4ef-4643-bbbc-4a0ed4fc8415"`	max length: 36 read only

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/teamnet/routes/network/172.16.0.0%2F16" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"tunnel_id":"f70ff985-a4ef-4643-bbbc-4a0ed4fc8415","comment":"Example comment for this route","network":"172.16.0.0/16","virtual_network_id":"f70ff985-a4ef-4643-bbbc-4a0ed4fc8415"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "network": "172.16.0.0/16",
    "tunnel_id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
    "tunnel_name": "blog",
    "comment": "Example comment for this route",
    "created_at": "2021-01-25T18:22:34.317854Z",
    "deleted_at": "2021-01-25T18:22:34.317854Z",
    "virtual_network_id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415"
  }
}

tunnel-route-delete-route

DELETE Delete Route

Delete an existing route from the account's routing table

DELETE accounts/:account_identifier/teamnet/routes/network/:ip_network_encoded

Optional parameters

Name /type	Description /example	Constraints
virtual_network_id string	UUID of the virtual network `"f70ff985-a4ef-4643-bbbc-4a0ed4fc8415"`	max length: 36 read only

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/teamnet/routes/network/172.16.0.0%2F16" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"virtual_network_id":"f70ff985-a4ef-4643-bbbc-4a0ed4fc8415"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "network": "172.16.0.0/16",
    "tunnel_id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
    "tunnel_name": "blog",
    "comment": "Example comment for this route",
    "created_at": "2021-01-25T18:22:34.317854Z",
    "deleted_at": "2021-01-25T18:22:34.317854Z",
    "virtual_network_id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415"
  }
}

Tunnel Virtual Network

Segregation of Tunnel IP Routes via Virtualized Networks to handle overlapping private IPs in your origins.

tunnel-virtual-network

Object definition

View properties and constraints defined on the object

Show definition

tunnel-virtual-network-list-virtual-networks

GET List Virtual Networks

List, search and filter an account's virtual networks

GET accounts/:account_identifier/teamnet/virtual_networks

Optional parameters

Name /type	Description /example	Constraints
id string	UUID of the virtual network `"f70ff985-a4ef-4643-bbbc-4a0ed4fc8415"`	max length: 36 read only
name string	A user-friendly name chosen when the virtual network is created. Cannot be empty `"us-east-1-vpc"`
is_default boolean	If true, return the default virtual network only. If false, return all other virtual networks. If not provided, then consider all virtual networks. `true`	valid values: (true,false)
is_deleted boolean	If true, only include deleted virtual networks. If false, exclude deleted virtual networks. If not provided, all virtual networks will be included `true`	valid values: (true,false)

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/teamnet/virtual_networks?id=f70ff985-a4ef-4643-bbbc-4a0ed4fc8415&name=us-east-1-vpc&is_default=true&is_deleted=true" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
      "name": "us-east-1-vpc",
      "is_default_network": true,
      "comment": "Staging VPC for data science",
      "created_at": "2021-01-25T18:22:34.317854Z",
      "deleted_at": "2021-01-25T18:22:34.317854Z"
    }
  ]
}

tunnel-virtual-network-create-virtual-network

POST Create Virtual Network

Add a new virtual network to the account

POST accounts/:account_identifier/teamnet/virtual_networks

Required parameters

Name /type	Description /example	Constraints
name string	A user-friendly name chosen when the virtual network is created. Cannot be empty `"us-east-1-vpc"`

Optional parameters

Name /type	Description /example	Constraints
comment string	Optional remark describing the virtual network. Empty if none `"Staging VPC for data science"`
is_default boolean	Whether this virtual network is the default one for the account. This means IP Routes belong to this virtual network and Teams Clients in the account route through this virtual network, unless specified otherwise for each case. `true`	valid values: (true,false)

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/teamnet/virtual_networks" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"us-east-1-vpc","comment":"Staging VPC for data science","is_default":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
    "name": "us-east-1-vpc",
    "is_default_network": true,
    "comment": "Staging VPC for data science",
    "created_at": "2021-01-25T18:22:34.317854Z",
    "deleted_at": "2021-01-25T18:22:34.317854Z"
  }
}

tunnel-virtual-network-update-virtual-network

PATCH Update Virtual Network

Update an existing virtual network in the account

PATCH accounts/:account_identifier/teamnet/virtual_networks/:vnet_id

Optional parameters

Name /type	Description /example	Constraints
name string	A user-friendly name chosen when the virtual network is created. Cannot be empty `"us-east-1-vpc"`
comment string	Optional remark describing the virtual network. Empty if none `"Staging VPC for data science"`
is_default_network boolean	Whether this virtual network is the default one for the account. This means IP Routes belong to this virtual network and Teams Clients in the account route through this virtual network, unless specified otherwise for each case. `true`	valid values: (true,false)

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/teamnet/virtual_networks/f70ff985-a4ef-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"us-east-1-vpc","comment":"Staging VPC for data science","is_default_network":true}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
    "name": "us-east-1-vpc",
    "is_default_network": true,
    "comment": "Staging VPC for data science",
    "created_at": "2021-01-25T18:22:34.317854Z",
    "deleted_at": "2021-01-25T18:22:34.317854Z"
  }
}

tunnel-virtual-network-delete-virtual-network

DELETE Delete Virtual Network

Delete an existing virtual network from the account

DELETE accounts/:account_identifier/teamnet/virtual_networks/:vnet_id

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/teamnet/virtual_networks/f70ff985-a4ef-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
    "name": "us-east-1-vpc",
    "is_default_network": true,
    "comment": "Staging VPC for data science",
    "created_at": "2021-01-25T18:22:34.317854Z",
    "deleted_at": "2021-01-25T18:22:34.317854Z"
  }
}

Magic Static Routes

Used to route traffic through GRE tunnels for Magic Transit and Magic WAN.

magic-static-routes

Object definition

View properties and constraints defined on the object

Show definition

magic-static-routes-list-routes

GET List Routes
free
pro
business
enterprise

List all Magic static routes

GET accounts/:account_identifier/magic/routes

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/routes" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "routes": [
      {
        "id": "c4a7362d577a6c3019a474fd6f485821",
        "created_on": "2017-06-14T00:00:00Z",
        "modified_on": "2017-06-14T05:20:00Z",
        "prefix": "192.0.2.0/24",
        "nexthop": "203.0.113.1",
        "priority": 100,
        "description": "New route for new prefix 203.0.113.1",
        "weight": 100,
        "scope": {
          "colo_regions": [
            "APAC"
          ],
          "colo_names": [
            "den01"
          ]
        }
      }
    ]
  }
}

magic-static-routes-route-details

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

Get a specific Magic static route

GET accounts/:account_identifier/magic/routes/:route_identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/routes/01a7362d577a6c3019a474fd6f485823" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "route": {
      "id": "c4a7362d577a6c3019a474fd6f485821",
      "created_on": "2017-06-14T00:00:00Z",
      "modified_on": "2017-06-14T05:20:00Z",
      "prefix": "192.0.2.0/24",
      "nexthop": "203.0.113.1",
      "priority": 100,
      "description": "New route for new prefix 203.0.113.1",
      "weight": 100,
      "scope": {
        "colo_regions": [
          "APAC"
        ],
        "colo_names": [
          "den01"
        ]
      }
    }
  }
}

magic-static-routes-create-routes

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

Creates a new Magic static route. Use ?validate_only=true as an optional query parameter to run validation only without persisting changes

POST accounts/:account_identifier/magic/routes?validate_only=:validate_only

Required parameters

Name /type	Description /example	Constraints

Optional parameters

Name /type	Description /example	Constraints
routes array	`[ { "prefix": "192.0.2.0/24", "nexthop": "203.0.113.1", "priority": 100, "description": "New route for new prefix 203.0.113.1", "weight": 100, "scope": { "colo_regions": [ "APAC" ], "colo_names": [ "den01" ] } } ]` An array with items in the following form: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/routes?validate_only=true" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"routes":[{"prefix":"192.0.2.0/24","nexthop":"203.0.113.1","priority":100,"description":"New route for new prefix 203.0.113.1","weight":100,"scope":{"colo_regions":["APAC"],"colo_names":["den01"]}}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "routes": [
      {
        "id": "c4a7362d577a6c3019a474fd6f485821",
        "created_on": "2017-06-14T00:00:00Z",
        "modified_on": "2017-06-14T05:20:00Z",
        "prefix": "192.0.2.0/24",
        "nexthop": "203.0.113.1",
        "priority": 100,
        "description": "New route for new prefix 203.0.113.1",
        "weight": 100,
        "scope": {
          "colo_regions": [
            "APAC"
          ],
          "colo_names": [
            "den01"
          ]
        }
      }
    ]
  }
}

magic-static-routes-update-route

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

Update a specific Magic static route. Use ?validate_only=true as an optional query parameter to run validation only without persisting changes

PUT accounts/:account_identifier/magic/routes/:route_identifier?validate_only=:validate_only

Optional parameters

Name /type	Description /example	Constraints
prefix string	IP Prefix in Classless Inter-Domain Routing format `"192.0.2.0/24"`
nexthop string	The next-hop IP Address for the static route `"203.0.113.1"`
priority integer	Priority of the static route `100`
description string	An optional human provided description of the static route `"New route for new prefix 203.0.113.1"`
weight integer	Optional weight of the ECMP scope - if provided `100`
scope object	Used only for ECMP routes `{ "colo_regions": [ "APAC" ], "colo_names": [ "den01" ] }` An object with the following properties: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/routes/01a7362d577a6c3019a474fd6f485823?validate_only=true" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"prefix":"192.0.2.0/24","nexthop":"203.0.113.1","priority":100,"description":"New route for new prefix 203.0.113.1","weight":100,"scope":{"colo_regions":["APAC"],"colo_names":["den01"]}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "modified": true,
    "modified_route": {
      "id": "c4a7362d577a6c3019a474fd6f485821",
      "created_on": "2017-06-14T00:00:00Z",
      "modified_on": "2017-06-14T05:20:00Z",
      "prefix": "192.0.2.0/24",
      "nexthop": "203.0.113.1",
      "priority": 100,
      "description": "New route for new prefix 203.0.113.1",
      "weight": 100,
      "scope": {
        "colo_regions": [
          "APAC"
        ],
        "colo_names": [
          "den01"
        ]
      }
    }
  }
}

magic-static-routes-update-many-routes

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

Update multiple Magic static routes. Use ?validate_only=true as an optional query parameter to run validation only without persisting changes. Only fields for a route that need to be changed need be provided.

PUT accounts/:account_identifier/magic/routes?validate_only=:validate_only

Required parameters

Name /type	Description /example	Constraints
routes array	`[ { "id": "01a7362d577a6c3019a474fd6f485823", "prefix": "192.0.2.0/24", "nexthop": "203.0.113.1", "priority": 100, "description": "New route for new prefix 203.0.113.1", "weight": 100, "scope": { "colo_regions": [ "APAC" ], "colo_names": [ "den01" ] } } ]` An array with items in the following form: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/routes?validate_only=true" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"routes":[{"id":"01a7362d577a6c3019a474fd6f485823","prefix":"192.0.2.0/24","nexthop":"203.0.113.1","priority":100,"description":"New route for new prefix 203.0.113.1","weight":100,"scope":{"colo_regions":["APAC"],"colo_names":["den01"]}}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "modified": true,
    "modified_routes": [
      {
        "id": "c4a7362d577a6c3019a474fd6f485821",
        "created_on": "2017-06-14T00:00:00Z",
        "modified_on": "2017-06-14T05:20:00Z",
        "prefix": "192.0.2.0/24",
        "nexthop": "203.0.113.1",
        "priority": 100,
        "description": "New route for new prefix 203.0.113.1",
        "weight": 100,
        "scope": {
          "colo_regions": [
            "APAC"
          ],
          "colo_names": [
            "den01"
          ]
        }
      }
    ]
  }
}

magic-static-routes-delete-route

DELETE Delete Route permission needed: #organization:edit
free
pro
business
enterprise

Disable and remove a specific Magic static route

DELETE accounts/:account_identifier/magic/routes/:route_identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/routes/01a7362d577a6c3019a474fd6f485823" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "deleted": true,
    "deleted_route": {
      "id": "c4a7362d577a6c3019a474fd6f485821",
      "created_on": "2017-06-14T00:00:00Z",
      "modified_on": "2017-06-14T05:20:00Z",
      "prefix": "192.0.2.0/24",
      "nexthop": "203.0.113.1",
      "priority": 100,
      "description": "New route for new prefix 203.0.113.1",
      "weight": 100,
      "scope": {
        "colo_regions": [
          "APAC"
        ],
        "colo_names": [
          "den01"
        ]
      }
    }
  }
}

Magic Static Routes error codes

Code	Description

Magic GRE tunnels

GRE tunnels that connect Cloudflare with your endpoints

magic-gre-tunnels

Object definition

View properties and constraints defined on the object

Show definition

magic-gre-tunnels-list-gre-tunnels

GET List GRE tunnels
free
pro
business
enterprise

Lists GRE tunnels associated with an account.

GET accounts/:account_identifier/magic/gre_tunnels

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/gre_tunnels" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "gre_tunnels": [
      {
        "id": "c4a7362d577a6c3019a474fd6f485821",
        "created_on": "2017-06-14T00:00:00Z",
        "modified_on": "2017-06-14T05:20:00Z",
        "name": "GRE_1",
        "customer_gre_endpoint": "203.0.113.1",
        "cloudflare_gre_endpoint": "203.0.113.1",
        "interface_address": "192.0.2.0/31",
        "description": "Tunnel for ISP X",
        "ttl": 64,
        "mtu": 1476,
        "health_check": {
          "enabled": true,
          "target": "203.0.113.1",
          "type": "request"
        }
      }
    ]
  }
}

magic-gre-tunnels-list-gre-tunnel-details

GET List GRE Tunnel Details
free
pro
business
enterprise

Lists informtion for a specific GRE tunnel.

GET accounts/:account_identifier/magic/gre_tunnels/:tunnel_identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/gre_tunnels/01a7362d577a6c3019a474fd6f485823" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "gre_tunnel": {
      "id": "c4a7362d577a6c3019a474fd6f485821",
      "created_on": "2017-06-14T00:00:00Z",
      "modified_on": "2017-06-14T05:20:00Z",
      "name": "GRE_1",
      "customer_gre_endpoint": "203.0.113.1",
      "cloudflare_gre_endpoint": "203.0.113.1",
      "interface_address": "192.0.2.0/31",
      "description": "Tunnel for ISP X",
      "ttl": 64,
      "mtu": 1476,
      "health_check": {
        "enabled": true,
        "target": "203.0.113.1",
        "type": "request"
      }
    }
  }
}

magic-gre-tunnels-create-gre-tunnels

POST Create GRE tunnels
free
pro
business
enterprise

Creates new GRE tunnels. Use ?validate_only=true as an optional query parameter to only run validation without persisting changes.

POST accounts/:account_identifier/magic/gre_tunnels?validate_only=:validate_only

Required parameters

Name /type	Description /example	Constraints

Optional parameters

Name /type	Description /example	Constraints
gre_tunnels array	`[ { "name": "GRE_1", "customer_gre_endpoint": "203.0.113.1", "cloudflare_gre_endpoint": "203.0.113.1", "interface_address": "192.0.2.0/31", "description": "Tunnel for ISP X", "ttl": 64, "mtu": 1476, "health_check": { "enabled": true, "target": "203.0.113.1", "type": "request" } } ]` An array with items in the following form: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/gre_tunnels?validate_only=true" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"gre_tunnels":[{"name":"GRE_1","customer_gre_endpoint":"203.0.113.1","cloudflare_gre_endpoint":"203.0.113.1","interface_address":"192.0.2.0/31","description":"Tunnel for ISP X","ttl":64,"mtu":1476,"health_check":{"enabled":true,"target":"203.0.113.1","type":"request"}}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "gre_tunnels": [
      {
        "id": "c4a7362d577a6c3019a474fd6f485821",
        "created_on": "2017-06-14T00:00:00Z",
        "modified_on": "2017-06-14T05:20:00Z",
        "name": "GRE_1",
        "customer_gre_endpoint": "203.0.113.1",
        "cloudflare_gre_endpoint": "203.0.113.1",
        "interface_address": "192.0.2.0/31",
        "description": "Tunnel for ISP X",
        "ttl": 64,
        "mtu": 1476,
        "health_check": {
          "enabled": true,
          "target": "203.0.113.1",
          "type": "request"
        }
      }
    ]
  }
}

magic-gre-tunnels-update-gre-tunnel

PUT Update GRE Tunnel
free
pro
business
enterprise

Updates a specific GRE tunnel. Use ?validate_only=true as an optional query parameter to only run validation without persisting changes.

PUT accounts/:account_identifier/magic/gre_tunnels/:tunnel_identifier?validate_only=:validate_only

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the tunnel. The name cannot contain spaces or special characters, must be 15 characters or less, and cannot share a name with another GRE tunnel. `"GRE_1"`
customer_gre_endpoint string	The IP address assigned to the customer side of the GRE tunnel. `"203.0.113.1"`
cloudflare_gre_endpoint string	The IP address assigned to the Cloudflare side of the GRE tunnel. `"203.0.113.1"`
interface_address string	A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255. `"192.0.2.0/31"`
description string	An optional description of the GRE tunnel. `"Tunnel for ISP X"`
ttl integer	Time To Live (TTL) in number of hops of the GRE tunnel. `64`	default value: 64
mtu integer	Maximum Transmission Unit (MTU) in bytes for the GRE tunnel. The minimum value is 576. `1476`	default value: 1476
health_check object	`{ "enabled": true, "target": "203.0.113.1", "type": "request" }` An object with the following properties: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/gre_tunnels/01a7362d577a6c3019a474fd6f485823?validate_only=true" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"GRE_1","customer_gre_endpoint":"203.0.113.1","cloudflare_gre_endpoint":"203.0.113.1","interface_address":"192.0.2.0/31","description":"Tunnel for ISP X","ttl":64,"mtu":1476,"health_check":{"enabled":true,"target":"203.0.113.1","type":"request"}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "modified": true,
    "modified_gre_tunnel": {
      "id": "c4a7362d577a6c3019a474fd6f485821",
      "created_on": "2017-06-14T00:00:00Z",
      "modified_on": "2017-06-14T05:20:00Z",
      "name": "GRE_1",
      "customer_gre_endpoint": "203.0.113.1",
      "cloudflare_gre_endpoint": "203.0.113.1",
      "interface_address": "192.0.2.0/31",
      "description": "Tunnel for ISP X",
      "ttl": 64,
      "mtu": 1476,
      "health_check": {
        "enabled": true,
        "target": "203.0.113.1",
        "type": "request"
      }
    }
  }
}

magic-gre-tunnels-update-multiple-gre-tunnels

PUT Update multiple GRE tunnels
free
pro
business
enterprise

Updates multiple GRE tunnels. Use ?validate_only=true as an optional query parameter to only run validation without persisting changes.

PUT accounts/:account_identifier/magic/gre_tunnels?validate_only=:validate_only

Required parameters

Name /type	Description /example	Constraints

Optional parameters

Name /type	Description /example	Constraints
gre_tunnels array	`[ { "id": "01a7362d577a6c3019a474fd6f485823", "name": "GRE_1", "customer_gre_endpoint": "203.0.113.1", "cloudflare_gre_endpoint": "203.0.113.1", "interface_address": "192.0.2.0/31", "description": "Tunnel for ISP X", "ttl": 64, "mtu": 1476, "health_check": { "enabled": true, "target": "203.0.113.1", "type": "request" } } ]` An array with items in the following form: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/gre_tunnels?validate_only=true" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"gre_tunnels":[{"id":"01a7362d577a6c3019a474fd6f485823","name":"GRE_1","customer_gre_endpoint":"203.0.113.1","cloudflare_gre_endpoint":"203.0.113.1","interface_address":"192.0.2.0/31","description":"Tunnel for ISP X","ttl":64,"mtu":1476,"health_check":{"enabled":true,"target":"203.0.113.1","type":"request"}}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "modified": true,
    "modified_gre_tunnels": [
      {
        "id": "c4a7362d577a6c3019a474fd6f485821",
        "created_on": "2017-06-14T00:00:00Z",
        "modified_on": "2017-06-14T05:20:00Z",
        "name": "GRE_1",
        "customer_gre_endpoint": "203.0.113.1",
        "cloudflare_gre_endpoint": "203.0.113.1",
        "interface_address": "192.0.2.0/31",
        "description": "Tunnel for ISP X",
        "ttl": 64,
        "mtu": 1476,
        "health_check": {
          "enabled": true,
          "target": "203.0.113.1",
          "type": "request"
        }
      }
    ]
  }
}

magic-gre-tunnels-delete-gre-tunnel

DELETE Delete GRE Tunnel
free
pro
business
enterprise

Disables and removes a specific static GRE tunnel. Use ?validate_only=true as an optional query parameter to only run validation without persisting changes.

DELETE accounts/:account_identifier/magic/gre_tunnels/:tunnel_identifier?validate_only=:validate_only

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/gre_tunnels/01a7362d577a6c3019a474fd6f485823?validate_only=true" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "deleted": true,
    "deleted_gre_tunnel": {
      "id": "c4a7362d577a6c3019a474fd6f485821",
      "created_on": "2017-06-14T00:00:00Z",
      "modified_on": "2017-06-14T05:20:00Z",
      "name": "GRE_1",
      "customer_gre_endpoint": "203.0.113.1",
      "cloudflare_gre_endpoint": "203.0.113.1",
      "interface_address": "192.0.2.0/31",
      "description": "Tunnel for ISP X",
      "ttl": 64,
      "mtu": 1476,
      "health_check": {
        "enabled": true,
        "target": "203.0.113.1",
        "type": "request"
      }
    }
  }
}

Magic GRE tunnels error codes

Code	Description

Magic IPsec tunnels

IPsec tunnels that connect Cloudflare with your endpoints

magic-ipsec-tunnels

Object definition

View properties and constraints defined on the object

Show definition

magic-ipsec-tunnels-list-ipsec-tunnels

GET List IPsec tunnels
free
pro
business
enterprise

Lists IPsec tunnels associated with an account.

GET accounts/:account_identifier/magic/ipsec_tunnels

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/ipsec_tunnels" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "ipsec_tunnels": [
      {
        "id": "c4a7362d577a6c3019a474fd6f485821",
        "created_on": "2017-06-14T00:00:00Z",
        "modified_on": "2017-06-14T05:20:00Z",
        "name": "IPsec_1",
        "customer_endpoint": "203.0.113.1",
        "cloudflare_endpoint": "203.0.113.1",
        "interface_address": "192.0.2.0/31",
        "description": "Tunnel for ISP X",
        "psk_metadata": {
          "last_generated_on": "2017-06-14T05:20:00Z"
        },
        "tunnel_health_check": {
          "enabled": true,
          "target": "203.0.113.1",
          "type": "request"
        },
        "allow_null_cipher": "true"
      }
    ]
  }
}

magic-ipsec-tunnels-list-ipsec-tunnel-details

GET List IPsec tunnel details
free
pro
business
enterprise

Lists details for a specific IPsec tunnel.

GET accounts/:account_identifier/magic/ipsec_tunnels/:tunnel_identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/ipsec_tunnels/01a7362d577a6c3019a474fd6f485823" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "ipsec_tunnel": {
      "id": "c4a7362d577a6c3019a474fd6f485821",
      "created_on": "2017-06-14T00:00:00Z",
      "modified_on": "2017-06-14T05:20:00Z",
      "name": "IPsec_1",
      "customer_endpoint": "203.0.113.1",
      "cloudflare_endpoint": "203.0.113.1",
      "interface_address": "192.0.2.0/31",
      "description": "Tunnel for ISP X",
      "psk_metadata": {
        "last_generated_on": "2017-06-14T05:20:00Z"
      },
      "tunnel_health_check": {
        "enabled": true,
        "target": "203.0.113.1",
        "type": "request"
      },
      "allow_null_cipher": "true"
    }
  }
}

magic-ipsec-tunnels-create-ipsec-tunnels

POST Create IPsec tunnels
free
pro
business
enterprise

Creates new IPsec tunnels associated with an account. Use ?validate_only=true as an optional query parameter to only run validation without persisting changes.

POST accounts/:account_identifier/magic/ipsec_tunnels?validate_only=:validate_only

Required parameters

Name /type	Description /example	Constraints

Optional parameters

Name /type	Description /example	Constraints
ipsec_tunnels array	`[ { "name": "IPsec_1", "customer_endpoint": "203.0.113.1", "cloudflare_endpoint": "203.0.113.1", "interface_address": "192.0.2.0/31", "description": "Tunnel for ISP X", "psk": "O3bwKSjnaoCxDoUxjcq4Rk8ZKkezQUiy" } ]` An array with items in the following form: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/ipsec_tunnels?validate_only=true" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"ipsec_tunnels":[{"name":"IPsec_1","customer_endpoint":"203.0.113.1","cloudflare_endpoint":"203.0.113.1","interface_address":"192.0.2.0/31","description":"Tunnel for ISP X","psk":"O3bwKSjnaoCxDoUxjcq4Rk8ZKkezQUiy"}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "ipsec_tunnels": [
      {
        "id": "c4a7362d577a6c3019a474fd6f485821",
        "created_on": "2017-06-14T00:00:00Z",
        "modified_on": "2017-06-14T05:20:00Z",
        "name": "IPsec_1",
        "customer_endpoint": "203.0.113.1",
        "cloudflare_endpoint": "203.0.113.1",
        "interface_address": "192.0.2.0/31",
        "description": "Tunnel for ISP X",
        "psk_metadata": {
          "last_generated_on": "2017-06-14T05:20:00Z"
        },
        "tunnel_health_check": {
          "enabled": true,
          "target": "203.0.113.1",
          "type": "request"
        },
        "allow_null_cipher": "true"
      }
    ]
  }
}

magic-ipsec-tunnels-generate-pre-shared-key-psk-for-ipsec-tunnels

POST Generate Pre Shared Key (PSK) for IPsec tunnels
free
pro
business
enterprise

Generates a Pre Shared Key for a specific IPsec tunnel used in the IKE session. Use ?validate_only=true as an optional query parameter to only run validation without persisting changes. After a PSK is generated, the PSK is immediately persisted to Cloudflare's edge and cannot be retrieved later. Note the PSK in a safe place.

POST accounts/:account_identifier/magic/ipsec_tunnels/:tunnel_identifier/psk_generate?validate_only=:validate_only

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/ipsec_tunnels/01a7362d577a6c3019a474fd6f485823/psk_generate?validate_only=true" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "psk_metadata": {
      "last_generated_on": "2017-06-14T05:20:00Z"
    },
    "psk": "O3bwKSjnaoCxDoUxjcq4Rk8ZKkezQUiy",
    "ipsec_tunnel_id": "01a7362d577a6c3019a474fd6f485823"
  }
}

magic-ipsec-tunnels-update-ipsec-tunnel

PUT Update IPsec Tunnel
free
pro
business
enterprise

Updates a specific IPsec tunnel associated with an account. Use ?validate_only=true as an optional query parameter to only run validation without persisting changes.

PUT accounts/:account_identifier/magic/ipsec_tunnels/:tunnel_identifier?validate_only=:validate_only

Optional parameters

Name /type	Description /example	Constraints
name string	The name of the IPsec tunnel. The name cannot share a name with other tunnels. `"IPsec_1"`
customer_endpoint string	The IP address assigned to the customer side of the IPsec tunnel `"203.0.113.1"`
cloudflare_endpoint string	The IP address assigned to the Cloudflare side of the IPsec tunnel `"203.0.113.1"`
interface_address string	A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255. `"192.0.2.0/31"`
description string	An optional description forthe IPsec tunnel. `"Tunnel for ISP X"`
psk string	A randomly generated or provided string for use in the IPsec tunnel `"O3bwKSjnaoCxDoUxjcq4Rk8ZKkezQUiy"`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/ipsec_tunnels/01a7362d577a6c3019a474fd6f485823?validate_only=true" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"IPsec_1","customer_endpoint":"203.0.113.1","cloudflare_endpoint":"203.0.113.1","interface_address":"192.0.2.0/31","description":"Tunnel for ISP X","psk":"O3bwKSjnaoCxDoUxjcq4Rk8ZKkezQUiy"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "modified": true,
    "modified_ipsec_tunnel": {
      "id": "c4a7362d577a6c3019a474fd6f485821",
      "created_on": "2017-06-14T00:00:00Z",
      "modified_on": "2017-06-14T05:20:00Z",
      "name": "IPsec_1",
      "customer_endpoint": "203.0.113.1",
      "cloudflare_endpoint": "203.0.113.1",
      "interface_address": "192.0.2.0/31",
      "description": "Tunnel for ISP X",
      "psk_metadata": {
        "last_generated_on": "2017-06-14T05:20:00Z"
      },
      "tunnel_health_check": {
        "enabled": true,
        "target": "203.0.113.1",
        "type": "request"
      },
      "allow_null_cipher": "true"
    }
  }
}

magic-ipsec-tunnels-update-multiple-ipsec-tunnels

PUT Update multiple IPsec tunnels
free
pro
business
enterprise

Update multiple IPsec tunnels associated with an account. Use ?validate_only=true as an optional query parameter to only run validation without persisting changes.

PUT accounts/:account_identifier/magic/ipsec_tunnels?validate_only=:validate_only

Required parameters

Name /type	Description /example	Constraints

Optional parameters

Name /type	Description /example	Constraints
ipsec_tunnels array	`[ { "id": "01a7362d577a6c3019a474fd6f485823", "name": "IPsec_1", "customer_endpoint": "203.0.113.1", "cloudflare_endpoint": "203.0.113.1", "interface_address": "192.0.2.0/31", "description": "Tunnel for ISP X", "psk": "O3bwKSjnaoCxDoUxjcq4Rk8ZKkezQUiy" } ]` An array with items in the following form: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/ipsec_tunnels?validate_only=true" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"ipsec_tunnels":[{"id":"01a7362d577a6c3019a474fd6f485823","name":"IPsec_1","customer_endpoint":"203.0.113.1","cloudflare_endpoint":"203.0.113.1","interface_address":"192.0.2.0/31","description":"Tunnel for ISP X","psk":"O3bwKSjnaoCxDoUxjcq4Rk8ZKkezQUiy"}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "modified": true,
    "modified_ipsec_tunnels": [
      {
        "id": "c4a7362d577a6c3019a474fd6f485821",
        "created_on": "2017-06-14T00:00:00Z",
        "modified_on": "2017-06-14T05:20:00Z",
        "name": "IPsec_1",
        "customer_endpoint": "203.0.113.1",
        "cloudflare_endpoint": "203.0.113.1",
        "interface_address": "192.0.2.0/31",
        "description": "Tunnel for ISP X",
        "psk_metadata": {
          "last_generated_on": "2017-06-14T05:20:00Z"
        },
        "tunnel_health_check": {
          "enabled": true,
          "target": "203.0.113.1",
          "type": "request"
        },
        "allow_null_cipher": "true"
      }
    ]
  }
}

magic-ipsec-tunnels-delete-ipsec-tunnel

DELETE Delete IPsec Tunnel
free
pro
business
enterprise

Disables and removes a specific static IPsec Tunnel associated with an account. Use ?validate_only=true as an optional query parameter to only run validation without persisting changes.

DELETE accounts/:account_identifier/magic/ipsec_tunnels/:tunnel_identifier?validate_only=:validate_only

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/ipsec_tunnels/01a7362d577a6c3019a474fd6f485823?validate_only=true" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "deleted": true,
    "deleted_ipsec_tunnel": {
      "id": "c4a7362d577a6c3019a474fd6f485821",
      "created_on": "2017-06-14T00:00:00Z",
      "modified_on": "2017-06-14T05:20:00Z",
      "name": "IPsec_1",
      "customer_endpoint": "203.0.113.1",
      "cloudflare_endpoint": "203.0.113.1",
      "interface_address": "192.0.2.0/31",
      "description": "Tunnel for ISP X",
      "psk_metadata": {
        "last_generated_on": "2017-06-14T05:20:00Z"
      },
      "tunnel_health_check": {
        "enabled": true,
        "target": "203.0.113.1",
        "type": "request"
      },
      "allow_null_cipher": "true"
    }
  }
}

Magic IPsec tunnels error codes

Code	Description

Magic Interconnects

Interconnects used with Cloudflare CNI

magic-interconnects

Object definition

View properties and constraints defined on the object

Show definition

magic-interconnects-list-interconnects

GET List interconnects
free
pro
business
enterprise

Lists interconnects associated with an account.

GET accounts/:account_identifier/magic/cf_interconnects

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/cf_interconnects" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "interconnects": [
      {
        "id": "c4a7362d577a6c3019a474fd6f485821",
        "created_on": "2017-06-14T00:00:00Z",
        "modified_on": "2017-06-14T05:20:00Z",
        "name": "pni_ord",
        "interface_address": "192.0.2.0/31",
        "description": "Tunnel for Interconnect to ORD",
        "health_check": {
          "enabled": true,
          "target": "203.0.113.1",
          "type": "request"
        },
        "gre": {
          "cloudflare_endpoint": "203.0.113.1",
          "customer_endpoint": "203.0.113.1",
          "is_colo_cast": true
        },
        "mtu": 1476,
        "colo_name": "pni_ord"
      }
    ]
  }
}

magic-interconnects-list-interconnect-details

GET List interconnect Details
free
pro
business
enterprise

Lists details for a specific interconnect.

GET accounts/:account_identifier/magic/cf_interconnects/:tunnel_identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/cf_interconnects/01a7362d577a6c3019a474fd6f485823" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "interconnect": {
      "id": "c4a7362d577a6c3019a474fd6f485821",
      "created_on": "2017-06-14T00:00:00Z",
      "modified_on": "2017-06-14T05:20:00Z",
      "name": "pni_ord",
      "interface_address": "192.0.2.0/31",
      "description": "Tunnel for Interconnect to ORD",
      "health_check": {
        "enabled": true,
        "target": "203.0.113.1",
        "type": "request"
      },
      "gre": {
        "cloudflare_endpoint": "203.0.113.1",
        "customer_endpoint": "203.0.113.1",
        "is_colo_cast": true
      },
      "mtu": 1476,
      "colo_name": "pni_ord"
    }
  }
}

magic-interconnects-update-interconnect

PUT Update interconnect
free
pro
business
enterprise

Updates a specific interconnect associated with an account. Use ?validate_only=true as an optional query parameter to only run validation without persisting changes.

PUT accounts/:account_identifier/magic/cf_interconnects/:tunnel_identifier?validate_only=:validate_only

Optional parameters

Name /type	Description /example	Constraints
mtu integer	The Maximum Transmission Unit (MTU) in bytes for the interconnect. The minimum value is 576. `1476`	default value: 1476
interface_address string	A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255. `"192.0.2.0/31"`
description string	An optional description of the interconnect `"Tunnel for Interconnect to ORD"`
gre object	The configuration specific to GRE interconnects. `{ "cloudflare_endpoint": "203.0.113.1", "customer_endpoint": "203.0.113.1", "is_colo_cast": true }` An object with the following properties: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/cf_interconnects/01a7362d577a6c3019a474fd6f485823?validate_only=true" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"mtu":1476,"interface_address":"192.0.2.0/31","description":"Tunnel for Interconnect to ORD","gre":{"cloudflare_endpoint":"203.0.113.1","customer_endpoint":"203.0.113.1","is_colo_cast":true}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "modified": true,
    "modified_interconnect": {
      "id": "c4a7362d577a6c3019a474fd6f485821",
      "created_on": "2017-06-14T00:00:00Z",
      "modified_on": "2017-06-14T05:20:00Z",
      "name": "pni_ord",
      "interface_address": "192.0.2.0/31",
      "description": "Tunnel for Interconnect to ORD",
      "health_check": {
        "enabled": true,
        "target": "203.0.113.1",
        "type": "request"
      },
      "gre": {
        "cloudflare_endpoint": "203.0.113.1",
        "customer_endpoint": "203.0.113.1",
        "is_colo_cast": true
      },
      "mtu": 1476,
      "colo_name": "pni_ord"
    }
  }
}

magic-interconnects-update-multiple-interconnects

PUT Update multiple interconnects
free
pro
business
enterprise

Updates multiple interconnects associated with an account. Use ?validate_only=true as an optional query parameter to only run validation without persisting changes.

PUT accounts/:account_identifier/magic/cf_interconnects?validate_only=:validate_only

Required parameters

Name /type	Description /example	Constraints

Optional parameters

Name /type	Description /example	Constraints
interconnects array	`[ { "id": "01a7362d577a6c3019a474fd6f485823", "mtu": 1476, "interface_address": "192.0.2.0/31", "description": "Tunnel for Interconnect to ORD", "gre": { "cloudflare_endpoint": "203.0.113.1", "customer_endpoint": "203.0.113.1", "is_colo_cast": true } } ]` An array with items in the following form: Show definition »

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/magic/cf_interconnects?validate_only=true" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"interconnects":[{"id":"01a7362d577a6c3019a474fd6f485823","mtu":1476,"interface_address":"192.0.2.0/31","description":"Tunnel for Interconnect to ORD","gre":{"cloudflare_endpoint":"203.0.113.1","customer_endpoint":"203.0.113.1","is_colo_cast":true}}]}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "modified": true,
    "modified_interconnects": [
      {
        "id": "c4a7362d577a6c3019a474fd6f485821",
        "created_on": "2017-06-14T00:00:00Z",
        "modified_on": "2017-06-14T05:20:00Z",
        "name": "pni_ord",
        "interface_address": "192.0.2.0/31",
        "description": "Tunnel for Interconnect to ORD",
        "health_check": {
          "enabled": true,
          "target": "203.0.113.1",
          "type": "request"
        },
        "gre": {
          "cloudflare_endpoint": "203.0.113.1",
          "customer_endpoint": "203.0.113.1",
          "is_colo_cast": true
        },
        "mtu": 1476,
        "colo_name": "pni_ord"
      }
    ]
  }
}

Magic Interconnects error codes

Code	Description

Magic PCAP collection

APIs for collecting account PCAPs inside Magic Transit

magic-pcap-collection

Object definition

View properties and constraints defined on the object

Show definition

magic-pcap-collection-list-packet-capture-requests

GET List packet capture requests
free
pro
business
enterprise

Lists all packet capture requests for an account.

GET accounts/:account_identifier/pcaps

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/pcaps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "66802ca5668e47a2b82c2e6746e45037",
      "submitted": "2020-01-01T08:00:00Z",
      "filter_v1": {
        "destination_address": "1.2.3.4",
        "source_address": "1.2.3.4",
        "source_port": 123,
        "destination_port": 80,
        "protocol": 6
      },
      "time_limit": 300,
      "status": "success",
      "type": "simple",
      "system": "magic-transit"
    }
  ]
}

magic-pcap-collection-create-simple-pcap-request

POST Create Simple PCAP request
free
pro
business
enterprise

Create new PCAP request for account.

POST accounts/:account_identifier/pcaps

Required parameters

Name /type	Description /example	Constraints
time_limit number	The packet capture duration in seconds. `300`	min value:1 max value:300
packet_limit number	The limit of packets contained in a packet capture. `10000`	min value:1 max value:10000
type string	The type of packet capture. `Simple` captures sampled packets, and `full` captures entire payloads and non-sampled packets. `"simple"`	valid values: simple, full
system string	The system used to collect packet captures. `"magic-transit"`	valid values: magic-transit

Optional parameters

Name /type	Description /example	Constraints
filter_v1 object	The packet capture filter. When this field is empty, all packets are captured. `{ "destination_address": "1.2.3.4", "source_address": "1.2.3.4", "source_port": 123, "destination_port": 80, "protocol": 6 }` An object with the following properties: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/pcaps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"filter_v1":{"destination_address":"1.2.3.4","source_address":"1.2.3.4","source_port":123,"destination_port":80,"protocol":6},"time_limit":300,"packet_limit":10000,"type":"simple","system":"magic-transit"}'

Response (example)

{
  "id": "66802ca5668e47a2b82c2e6746e45037",
  "submitted": "2020-01-01T08:00:00Z",
  "filter_v1": {
    "destination_address": "1.2.3.4",
    "source_address": "1.2.3.4",
    "source_port": 123,
    "destination_port": 80,
    "protocol": 6
  },
  "time_limit": 300,
  "status": "success",
  "type": "simple",
  "system": "magic-transit"
}

magic-pcap-collection-create-full-pcap-request

POST Create Full PCAP request
free
pro
business
enterprise

Create new PCAP request for account.

POST accounts/:account_identifier/pcaps

Required parameters

Name /type	Description /example	Constraints
time_limit number	The packet capture duration in seconds. `300`	min value:1 max value:300
type string	The type of packet capture. `Simple` captures sampled packets, and `full` captures entire payloads and non-sampled packets. `"simple"`	valid values: simple, full
system string	The system used to collect packet captures. `"magic-transit"`	valid values: magic-transit
colo_name string	The name of the data center used for the packet capture. This can be a specific colo (ord02) or a multi-colo name (ORD). This field only applies to `full` packet captures. `"ord02"`
destination_conf string	The full URI for the bucket. This field only applies to `full` packet captures. `"s3://pcaps-bucket?region=us-east-1"`

Optional parameters

Name /type	Description /example	Constraints
filter_v1 object	The packet capture filter. When this field is empty, all packets are captured. `{ "destination_address": "1.2.3.4", "source_address": "1.2.3.4", "source_port": 123, "destination_port": 80, "protocol": 6 }` An object with the following properties: Show definition »
packet_limit number	The limit of packets contained in a packet capture. `10000`	min value:1 max value:10000
byte_limit number	The maximum number of bytes to capture. This field only applies to `full` packet captures. `500000`	min value:1 max value:1000000000

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/pcaps" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"filter_v1":{"destination_address":"1.2.3.4","source_address":"1.2.3.4","source_port":123,"destination_port":80,"protocol":6},"time_limit":300,"packet_limit":10000,"type":"simple","system":"magic-transit","byte_limit":500000,"colo_name":"ord02","destination_conf":"s3://pcaps-bucket?region=us-east-1"}'

Response (example)

{
  "id": "66802ca5668e47a2b82c2e6746e45037",
  "submitted": "2020-01-01T08:00:00Z",
  "filter_v1": {
    "destination_address": "1.2.3.4",
    "source_address": "1.2.3.4",
    "source_port": 123,
    "destination_port": 80,
    "protocol": 6
  },
  "time_limit": 300,
  "status": "success",
  "error_message": "No packets matched the filter in the time limit given. Please modify the filter or try again.",
  "type": "simple",
  "system": "magic-transit",
  "byte_limit": 500000,
  "colo_name": "ord02",
  "destination_conf": "s3://pcaps-bucket?region=us-east-1"
}

magic-pcap-collection-get-pcap-request

GET Get PCAP request
free
pro
business
enterprise

Get information for a PCAP request by id.

GET accounts/:account_identifier/pcaps/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/pcaps/69cd1e104af3e6ed3cb344f263fd0d5a" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "66802ca5668e47a2b82c2e6746e45037",
    "submitted": "2020-01-01T08:00:00Z",
    "filter_v1": {
      "destination_address": "1.2.3.4",
      "source_address": "1.2.3.4",
      "source_port": 123,
      "destination_port": 80,
      "protocol": 6
    },
    "time_limit": 300,
    "status": "success",
    "type": "simple",
    "system": "magic-transit"
  }
}

magic-pcap-collection-download-simple-pcap

GET Download Simple PCAP
free
pro
business
enterprise

Download PCAP information into a file. Response is a binary PCAP file.

GET accounts/:account_identifier/pcaps/:identifier/download

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/pcaps/69cd1e104af3e6ed3cb344f263fd0d5a/download" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/vnd.tcpdump.pcap"

Response (example)

magic-pcap-collection-list-pcaps-bucket-ownership

GET List PCAPs Bucket Ownership
free
pro
business
enterprise

List all buckets configured for use with PCAPs API.

GET accounts/:account_identifier/pcaps/ownership

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/pcaps/ownership" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

magic-pcap-collection-add-buckets-for-full-packet-captures

POST Add buckets for full packet captures
free
pro
business
enterprise

Adds an AWS or GCP bucket to use with full packet captures.

POST accounts/:account_identifier/pcaps/ownership

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/pcaps/ownership" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "destination_conf": "s3://pcaps-bucket?region=us-east-1"
}

magic-pcap-collection-validate-buckets-for-full-packet-captures

POST Validate buckets for full packet captures
free
pro
business
enterprise

Validates buckets added to the packet captures API.

POST accounts/:account_identifier/pcaps/ownership/validate

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/pcaps/ownership/validate" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "destination_conf": "s3://pcaps-bucket?region=us-east-1",
  "ownership_challenge": "ownership-challenge-9883874ecac311ec8475433579a6bf5f.txt"
}

magic-pcap-collection-delete-buckets-for-full-packet-captures

DELETE Delete buckets for full packet captures
free
pro
business
enterprise

Deletes buckets added to the packet captures API.

DELETE accounts/:account_identifier/pcaps/ownership/:ownership_identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/pcaps/ownership/b2df3c4fcfc84ea49a28df6d55ce16cb" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

Domain Intelligence

Domain overview (Beta)

domain-intelligence

Object definition

View properties and constraints defined on the object

Show definition

domain-intelligence-get-domain-details

GET Get Domain Details

GET accounts/:account_identifier/intel/domain

Required parameters

Name /type	Description /example	Constraints
domain string	`"cloudflare.com"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/intel/domain?domain=cloudflare.com" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "domain": "cloudflare.com",
    "resolves_to_refs": [
      {
        "id": "ipv4-addr--baa568ec-6efe-5902-be55-0663833db537",
        "value": "192.0.2.0"
      }
    ],
    "popularity_rank": 18,
    "application": {
      "id": 1370,
      "name": "CLOUDFLARE"
    },
    "risk_types": [],
    "content_categories": [
      {
        "id": 155,
        "super_category_id": 26,
        "name": "Technology"
      }
    ],
    "additional_information": {
      "suspected_malware_family": ""
    }
  }
}

domain-intelligence-get-multiple-domain-details

GET Get Multiple Domain Details

GET accounts/:account_identifier/intel/domain/bulk

Required parameters

Name /type	Description /example	Constraints
domain string	Accepts multiple values, i.e. `?domain=cloudflare.com&domain=example.com` `"cloudflare.com"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/intel/domain/bulk?domain=cloudflare.com" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "domain": "cloudflare.com",
      "popularity_rank": 18,
      "application": {
        "id": 1370,
        "name": "CLOUDFLARE"
      },
      "risk_types": [],
      "content_categories": [
        {
          "id": 155,
          "super_category_id": 26,
          "name": "Technology"
        }
      ],
      "additional_information": {
        "suspected_malware_family": ""
      }
    }
  ]
}

Domain History

Historical domain categorization (Beta)

domain-history

Object definition

View properties and constraints defined on the object

Show definition

domain-history-get-domain-history

GET Get Domain History

GET accounts/:account_identifier/intel/domain-history

Optional parameters

Name /type	Description /example	Constraints
domain string	`"example.com"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/intel/domain-history?domain=example.com" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "domain": "cloudflare.com",
      "categorizations": [
        {
          "categories": [
            {
              "id": 155,
              "name": "Technology"
            }
          ],
          "start": "2021-04-01",
          "end": "2021-04-30"
        }
      ]
    }
  ]
}

WHOIS Record

WHOIS (Beta)

whois-record

Object definition

View properties and constraints defined on the object

Show definition

whois-record-get-whois-record

GET Get WHOIS Record

GET accounts/:account_identifier/intel/whois

Required parameters

Name /type	Description /example	Constraints
domain string	`"cloudflare.com"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/intel/whois?domain=cloudflare.com" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "domain": "cloudflare.com",
    "created_date": "2009-02-17",
    "updated_date": "2017-05-24",
    "registrant": "DATA REDACTED",
    "registrant_org": "DATA REDACTED",
    "registrant_country": "United States",
    "registrant_email": "https://domaincontact.cloudflareregistrar.com/cloudflare.com",
    "registrar": "Cloudflare, Inc.",
    "nameservers": [
      "ns3.cloudflare.com",
      "ns4.cloudflare.com",
      "ns5.cloudflare.com",
      "ns6.cloudflare.com",
      "ns7.cloudflare.com"
    ]
  }
}

IP Intelligence

IP overview (Beta)

ip-intelligence

Object definition

View properties and constraints defined on the object

Show definition

ip-intelligence-get-ip-overview

GET Get IP Overview

GET accounts/:account_identifier/intel/ip

Optional parameters

Name /type	Description /example	Constraints
ipv4 string (ipv4)	`"192.0.2.0"`
ipv6 string (ipv6)	`"2001:0DB8::"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/intel/ip?ipv4=192.0.2.0&ipv6=2001:0DB8::" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "ip": "192.0.2.0",
      "belongs_to_ref": {
        "id": "autonomous-system--2fa28d71-3549-5a38-af05-770b79ad6ea8",
        "value": 13335,
        "type": "hosting_provider",
        "country": "US",
        "description": "CLOUDFLARENET"
      },
      "risk_types": [
        {
          "id": 131,
          "super_category_id": 21,
          "name": "Phishing"
        }
      ]
    }
  ]
}

IP List

IP list

ip-list

Object definition

View properties and constraints defined on the object

Show definition

ip-list-get-ip-lists

GET Get IP Lists

GET accounts/:account_identifier/intel/ip-list

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/intel/ip-list" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": 3,
      "name": "Malware"
    }
  ]
}

Passive DNS by IP

Passive DNS by IP (Beta)

passive-dns-by-ip

Object definition

View properties and constraints defined on the object

Show definition

passive-dns-by-ip-get-passive-dns-by-ip

GET Get Passive DNS by IP

GET accounts/:account_identifier/intel/dns

Optional parameters

Name /type	Description /example	Constraints
ipv4 string (ipv4)	`"192.0.2.0"`
start string (date)	Defaults to 30 days before the end parameter value `"2021-04-01"`
end string (date)	Defaults to the current date `"2021-04-30"`
page number	Requested page within paginated list of results `1`
per_page number	Maximum number of results requested `20`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/intel/dns?ipv4=192.0.2.0&start=2021-04-01&end=2021-04-30&page=1&per_page=20" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "reverse_records": [
      {
        "first_seen": "2021-04-01",
        "last_seen": "2021-04-30",
        "hostname": "cloudflare.com"
      }
    ],
    "count": 1,
    "page": 1,
    "per_page": 20
  }
}

Phishing URL Scanner

Phishing URL Scanner (Beta)

phishing-url-scanner

Object definition

View properties and constraints defined on the object

Show definition

phishing-url-scanner-scan-suspicious-url

GET Scan suspicious url

GET accounts/:account_identifier/intel-phishing/predict

Optional parameters

Name /type	Description /example	Constraints
url string (url)	`"https://www.cloudflare.com"`
skip boolean	Whether to skip the initial URL scanner and require a full HTML scan `true`	default value: false valid values: (true,false)

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/intel-phishing/predict?url=https://www.cloudflare.com&skip=true" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "url": "https://www.cloudflare.com",
    "phishing": false,
    "verified": false,
    "score": 0.99,
    "classifier": "MACHINE_LEARNING_v2"
  }
}

ASN Intelligence

Autonomous system overview (Beta)

asn-intelligence

Object definition

View properties and constraints defined on the object

Show definition

asn-intelligence-get-asn-overview

GET Get ASN Overview

GET accounts/:account_identifier/intel/asn/:asn

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/intel/asn/13335" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "asn": 13335,
      "description": "CLOUDFLARENET",
      "country": "US",
      "type": "hosting_provider",
      "domain_count": 1,
      "top_domains": [
        "example.com"
      ]
    }
  ]
}

asn-intelligence-get-asn-subnets

GET Get ASN Subnets

GET accounts/:account_identifier/intel/asn/:asn/subnets

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/intel/asn/13335/subnets" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "asn": 13335,
  "ip_count_total": 1,
  "subnets": [
    "192.0.2.0/24",
    "2001:DB8::/32"
  ],
  "count": 1,
  "page": 1,
  "per_page": 20
}

Miscategorization

miscategorization

Object definition

View properties and constraints defined on the object

Show definition

miscategorization-create-miscategorization

POST Create Miscategorization

POST accounts/:account_identifier/intel/miscategorization

Optional parameters

Name /type	Description /example	Constraints
indicator_type	`"domain"`	valid values: domain, ipv4, ipv6, url
ip	Provide only if indicator_type is `ipv4` or `ipv6` `"192.0.2.0"` Any of the following: Show definition » Show definition »
url string	Provide only if indicator_type is `domain` or `url`. Example if indicator_type is `domain`: `example.com`. Example if indicator_type is `url`: `https://example.com/news/`
content_adds array	Content category IDs to add `[ 82 ]` An array with items in the following form: Show definition »
content_removes array	Content category IDs to remove `[ 155 ]` An array with items in the following form: Show definition »
security_adds array	Security category IDs to add `[ 117, 131 ]` An array with items in the following form: Show definition »
security_removes array	Security category IDs to remove `[ 83 ]` An array with items in the following form: Show definition »

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/01a7362d577a6c3019a474fd6f485823/intel/miscategorization" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"indicator_type":"domain","ip":"192.0.2.0","content_adds":[82],"content_removes":[155],"security_adds":[117,131],"security_removes":[83]}'

Response (example)

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

Notification Alert Types

Products and events for which users can receive notifications.

notification-alert-types

Object definition

View properties and constraints defined on the object

Show definition

notification-alert-types-get-alert-types

GET Get Alert Types

Gets a list of all alert types for which an account is eligible.

GET accounts/:identifier/alerting/v3/available_alerts

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/alerting/v3/available_alerts" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "Origin Monitoring": [
      {
        "display_name": "Origin Error Rate Alert",
        "type": "http_alert_origin_error",
        "description": "High levels of 5xx HTTP errors at your origin",
        "filter_options": [
          {
            "Key": "zones",
            "ComparisonOperator": "==",
            "Optional": false
          },
          {
            "Key": "slo",
            "ComparisonOperator": ">=",
            "Optional": true
          }
        ]
      }
    ]
  }
}

Notification Mechanism Eligibility

Delivery mechanism availability.

notification-mechanism-eligibility

Object definition

View properties and constraints defined on the object

Show definition

notification-mechanism-eligibility-get-delivery-mechanism-eligibility

GET Get delivery mechanism eligibility

Get a list of all delivery mechanism types for which an account is eligible.

GET accounts/:identifier/alerting/v3/destinations/eligible

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/alerting/v3/destinations/eligible" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "email": {
      "eligible": true,
      "ready": true,
      "type": "email"
    }
  }
}

Notification destinations with PagerDuty

Configure a policy to dispatch via PagerDuty.

notification-destinations-with-pagerduty

Object definition

View properties and constraints defined on the object

Show definition

notification-destinations-with-pagerduty-list-pagerduty-services

GET List PagerDuty services
free
pro
business
enterprise

Get a list of all configured PagerDuty services

GET accounts/:identifier/alerting/v3/destinations/pagerduty

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/alerting/v3/destinations/pagerduty" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "name": "My PagerDuty Service"
    }
  ]
}

Notification policies

Notification policies control which notifications you receive for your account.

notification-policies

Object definition

View properties and constraints defined on the object

Show definition

notification-policies-list-notification-policies

GET List Notification policies

Get a list of all Notification policies.

GET accounts/:identifier/alerting/v3/policies

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/alerting/v3/policies" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "name": "SSL Notification Event Policy",
      "description": "Something describing the policy.",
      "enabled": true,
      "alert_type": "universal_ssl_event_type",
      "mechanisms": {
        "email": [
          {
            "id": "test@example.com"
          }
        ],
        "pagerduty": [
          {
            "id": "e8133a15-00a4-4d69-aec1-32f70c51f6e5"
          }
        ],
        "webhooks": [
          {
            "id": "14cc1190-5d2b-4b98-a696-c424cb2ad05f"
          }
        ]
      },
      "filters": {
        "slo": [
          "99.9"
        ]
      },
      "created": "2014-01-01T05:20:00.12345Z",
      "modified": "2014-01-01T05:20:00.12345Z"
    }
  ]
}

notification-policies-get-a-notification-policy

GET Get a Notification policy

Get details for a single policy.

GET accounts/:identifier/alerting/v3/policies/:uuid

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/alerting/v3/policies/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "SSL Notification Event Policy",
    "description": "Something describing the policy.",
    "enabled": true,
    "alert_type": "universal_ssl_event_type",
    "mechanisms": {
      "email": [
        {
          "id": "test@example.com"
        }
      ],
      "pagerduty": [
        {
          "id": "e8133a15-00a4-4d69-aec1-32f70c51f6e5"
        }
      ],
      "webhooks": [
        {
          "id": "14cc1190-5d2b-4b98-a696-c424cb2ad05f"
        }
      ]
    },
    "filters": {
      "slo": [
        "99.9"
      ]
    },
    "created": "2014-01-01T05:20:00.12345Z",
    "modified": "2014-01-01T05:20:00.12345Z"
  }
}

notification-policies-create-a-notification-policy

POST Create a Notification policy

Creates a new Notification policy.

POST accounts/:identifier/alerting/v3/policies

Required parameters

Name /type	Description /example	Constraints
name string	Name of the policy. `"SSL Notification Event Policy"`
enabled boolean	Whether or not the Notification policy is enabled. `true`	default value: true valid values: (true,false)
alert_type string	Refers to which event will trigger a Notification dispatch. You can use the endpoint to get available alert types which then will give you a list of possible values. `"universal_ssl_event_type"`
mechanisms object	List of IDs that will be used when dispatching a notification. IDs for email type will be the email address. `{ "email": [ { "id": "test@example.com" } ], "pagerduty": [ { "id": "e8133a15-00a4-4d69-aec1-32f70c51f6e5" } ], "webhooks": [ { "id": "14cc1190-5d2b-4b98-a696-c424cb2ad05f" } ] }`

Optional parameters

Name /type	Description /example	Constraints
description string	Optional description for the Notification policy. `"Something describing the policy."`
filters object	`{ "slo": [ "99.9" ] }`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/alerting/v3/policies" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"SSL Notification Event Policy","description":"Something describing the policy.","enabled":true,"alert_type":"universal_ssl_event_type","mechanisms":{"email":[{"id":"test@example.com"}],"pagerduty":[{"id":"e8133a15-00a4-4d69-aec1-32f70c51f6e5"}],"webhooks":[{"id":"14cc1190-5d2b-4b98-a696-c424cb2ad05f"}]},"filters":{"slo":["99.9"]}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
  }
}

notification-policies-update-a-notification-policy

PUT Update a Notification policy

Update a Notification policy.

PUT accounts/:identifier/alerting/v3/policies/:uuid

Optional parameters

Name /type	Description /example	Constraints
name string	Name of the policy. `"SSL Notification Event Policy"`
description string	Optional description for the Notification policy. `"Something describing the policy."`
enabled boolean	Whether or not the Notification policy is enabled. `true`	default value: true valid values: (true,false)
alert_type string	Refers to which event will trigger a Notification dispatch. You can use the endpoint to get available alert types which then will give you a list of possible values. `"universal_ssl_event_type"`
mechanisms object	List of IDs that will be used when dispatching a notification. IDs for email type will be the email address. `{ "email": [ { "id": "test@example.com" } ], "pagerduty": [ { "id": "e8133a15-00a4-4d69-aec1-32f70c51f6e5" } ], "webhooks": [ { "id": "14cc1190-5d2b-4b98-a696-c424cb2ad05f" } ] }`
filters object	`{ "slo": [ "99.9" ] }`

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/alerting/v3/policies/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"SSL Notification Event Policy","description":"Something describing the policy.","enabled":true,"alert_type":"universal_ssl_event_type","mechanisms":{"email":[{"id":"test@example.com"}],"pagerduty":[{"id":"e8133a15-00a4-4d69-aec1-32f70c51f6e5"}],"webhooks":[{"id":"14cc1190-5d2b-4b98-a696-c424cb2ad05f"}]},"filters":{"slo":["99.9"]}}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
  }
}

notification-policies-delete-a-notification-policy

DELETE Delete a Notification policy

Delete a Notification policy.

DELETE accounts/:identifier/alerting/v3/policies/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/alerting/v3/policies/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Notification webhooks

Notification webhooks are destination mechanisms that can be used in notification policies.

notification-webhooks

Object definition

View properties and constraints defined on the object

Show definition

notification-webhooks-list-webhooks

GET List webhooks
free
pro
business
enterprise

Gets a list of all configured webhook destinations.

GET accounts/:identifier/alerting/v3/destinations/webhooks

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/alerting/v3/destinations/webhooks" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "name": "Slack Webhook",
      "url": "https://hooks.slack.com/services/Ds3fdBFbV/456464Gdd",
      "type": "slack",
      "created_at": "2020-10-26T18:25:04.532316Z",
      "last_success": "2020-10-26T18:25:04.532316Z",
      "last_failure": "2020-10-26T18:25:04.532316Z"
    }
  ]
}

notification-webhooks-get-a-webhook

GET Get a webhook
free
pro
business
enterprise

Get details for a single webhooks destination.

GET accounts/:identifier/alerting/v3/destinations/webhooks/:uuid

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/alerting/v3/destinations/webhooks/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    "name": "Slack Webhook",
    "url": "https://hooks.slack.com/services/Ds3fdBFbV/456464Gdd",
    "type": "slack",
    "created_at": "2020-10-26T18:25:04.532316Z",
    "last_success": "2020-10-26T18:25:04.532316Z",
    "last_failure": "2020-10-26T18:25:04.532316Z"
  }
}

notification-webhooks-create-a-webhook

POST Create a webhook
free
pro
business
enterprise

Creates a new webhook destination.

POST accounts/:identifier/alerting/v3/destinations/webhooks

Required parameters

Name /type	Description /example	Constraints
name string	The name of the webhook destination. This will be included in the request body when you receive a webhook notification. `"Slack Webhook"`
url string	The POST endpoint to call when dispatching a notification. `"https://hooks.slack.com/services/Ds3fdBFbV/456464Gdd"`

Optional parameters

Name /type	Description /example	Constraints
secret string	Optional secret that will be passed in the `cf-webhook-auth` header when dispatching a webhook notification. Secrets are not returned in any API response body.

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/alerting/v3/destinations/webhooks" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Slack Webhook","url":"https://hooks.slack.com/services/Ds3fdBFbV/456464Gdd"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
  }
}

notification-webhooks-update-a-webhook

PUT Update a webhook
free
pro
business
enterprise

Update a webhook destination.

PUT accounts/:identifier/alerting/v3/destinations/webhooks/:uuid

Required parameters

Name /type	Description /example	Constraints
name string	The name of the webhook destination. This will be included in the request body when you receive a webhook notification. `"Slack Webhook"`
url string	The POST endpoint to call when dispatching a notification. `"https://hooks.slack.com/services/Ds3fdBFbV/456464Gdd"`

Optional parameters

Name /type	Description /example	Constraints
secret string	Optional secret that will be passed in the `cf-webhook-auth` header when dispatching a webhook notification. Secrets are not returned in any API response body.

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/alerting/v3/destinations/webhooks/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"Slack Webhook","url":"https://hooks.slack.com/services/Ds3fdBFbV/456464Gdd"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415"
  }
}

notification-webhooks-delete-a-webhook

DELETE Delete a webhook
free
pro
business
enterprise

Delete a configured webhook destination.

DELETE accounts/:identifier/alerting/v3/destinations/webhooks/:uuid

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/alerting/v3/destinations/webhooks/f174e90a-fafe-4643-bbbc-4a0ed4fc8415" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Notification History

History of notifications sent to users.

notification-history

Object definition

View properties and constraints defined on the object

Show definition

notification-history-list-history

GET List History

Gets a list of history records for notifications sent to an account. The records are displayed for last x number of days based on the zone plan (free = 30, pro = 30, biz = 30, ent = 90).

GET accounts/:identifier/alerting/v3/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. `25`	default value: 25 min value:5 max value:1000
since string (date-time)	Limit the returned results to history records newer than the specified date. This must be a timestamp that conforms to RFC3339 `"2022-05-19T20:29:58.679897Z"`
before string (date-time)	Limit the returned results to history records older than the specified date. This must be a timestamp that conforms to RFC3339 `"2022-05-20T20:29:58.679897Z"`

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/accounts/9a7806061c88ada191ed06f989cc3dac/alerting/v3/history?page=1&per_page=25&since=2022-05-19T20:29:58.679897Z&before=2022-05-20T20:29:58.679897Z" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "name": "SSL Notification Event Policy",
      "description": "Universal Certificate validation status, issuance, renewal, and expiration notices",
      "alert_body": "SSL certificate has expired",
      "alert_type": "universal_ssl_event_type",
      "mechanism": "test@example.com",
      "mechanism_type": "email",
      "sent": "2021-10-08T17:52:17.571336Z"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1
  }
}

Web3 Hostname

Manage hostnames for your zone that are routed to Web3 gateways via CNAME.

web3-hostname

Object definition

View properties and constraints defined on the object

Show definition

web3-hostname-list-web3-hostnames

GET List Web3 Hostnames
free
pro
business
enterprise

GET zones/:zone_identifier/web3/hostnames

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/web3/hostnames" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "9a7806061c88ada191ed06f989cc3dac",
      "name": "gateway.example.com",
      "description": "This is my IPFS gateway.",
      "status": "active",
      "target": "ipfs",
      "dnslink": "/ipns/onboarding.ipfs.cloudflare.com",
      "created_on": "2014-01-01T05:20:00.12345Z",
      "modified_on": "2014-01-01T05:20:00.12345Z"
    }
  ]
}

web3-hostname-create-web3-hostname

POST Create Web3 Hostname
free
pro
business
enterprise

POST zones/:zone_identifier/web3/hostnames

Required parameters

Name /type	Description /example	Constraints
name string	The hostname that will point to the target gateway via CNAME. `"gateway.example.com"`	max length: 255 read only
target string	Target gateway of the hostname. `"ipfs"`	valid values: ethereum, ipfs, ipfs_universal_path

Optional parameters

Name /type	Description /example	Constraints
description string	An optional description of the hostname. `"This is my IPFS gateway."`	max length: 500
dnslink string	DNSLink value used if the target is ipfs. `"/ipns/onboarding.ipfs.cloudflare.com"`

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/web3/hostnames" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"name":"gateway.example.com","description":"This is my IPFS gateway.","target":"ipfs","dnslink":"/ipns/onboarding.ipfs.cloudflare.com"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "name": "gateway.example.com",
    "description": "This is my IPFS gateway.",
    "status": "active",
    "target": "ipfs",
    "dnslink": "/ipns/onboarding.ipfs.cloudflare.com",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

web3-hostname-web3-hostname-details

GET Web3 Hostname Details
free
pro
business
enterprise

GET zones/:zone_identifier/web3/hostnames/:identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/web3/hostnames/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "name": "gateway.example.com",
    "description": "This is my IPFS gateway.",
    "status": "active",
    "target": "ipfs",
    "dnslink": "/ipns/onboarding.ipfs.cloudflare.com",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

web3-hostname-edit-web3-hostname

PATCH Edit Web3 Hostname
free
pro
business
enterprise

PATCH zones/:zone_identifier/web3/hostnames/:identifier

Optional parameters

Name /type	Description /example	Constraints
description string	An optional description of the hostname. `"This is my IPFS gateway."`	max length: 500
dnslink string	DNSLink value used if the target is ipfs. `"/ipns/onboarding.ipfs.cloudflare.com"`

cURL (example)

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/web3/hostnames/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"description":"This is my IPFS gateway.","dnslink":"/ipns/onboarding.ipfs.cloudflare.com"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "name": "gateway.example.com",
    "description": "This is my IPFS gateway.",
    "status": "active",
    "target": "ipfs",
    "dnslink": "/ipns/onboarding.ipfs.cloudflare.com",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

web3-hostname-delete-web3-hostname

DELETE Delete Web3 Hostname
free
pro
business
enterprise

DELETE zones/:zone_identifier/web3/hostnames/:identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/web3/hostnames/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

web3-hostname-ipfs-universal-path-gateway-content-list-details

GET IPFS Universal Path Gateway Content List Details
free
pro
business
enterprise

GET zones/:zone_identifier/web3/hostnames/:identifier/ipfs_universal_path/content_list

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/web3/hostnames/9a7806061c88ada191ed06f989cc3dac/ipfs_universal_path/content_list" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

web3-hostname-update-ipfs-universal-path-gateway-content-list

PUT Update IPFS Universal Path Gateway Content List
free
pro
business
enterprise

PUT zones/:zone_identifier/web3/hostnames/:identifier/ipfs_universal_path/content_list

Optional parameters

Name /type	Description /example	Constraints
action string	Behavior of the content list `"block"`	valid values: block

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/web3/hostnames/9a7806061c88ada191ed06f989cc3dac/ipfs_universal_path/content_list" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"action":"block"}'

Response (example)

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

web3-hostname-list-ipfs-universal-path-gateway-content-list-entries

GET List IPFS Universal Path Gateway Content List Entries
free
pro
business
enterprise

GET zones/:zone_identifier/web3/hostnames/:identifier/ipfs_universal_path/content_list/entries

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/web3/hostnames/9a7806061c88ada191ed06f989cc3dac/ipfs_universal_path/content_list/entries" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "entries": [
      {
        "id": "9a7806061c88ada191ed06f989cc3dac",
        "type": "cid",
        "content": "QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB",
        "description": "this is my content list entry",
        "created_on": "2014-01-01T05:20:00.12345Z",
        "modified_on": "2014-01-01T05:20:00.12345Z"
      }
    ]
  }
}

web3-hostname-create-ipfs-universal-path-gateway-content-list-entry

POST Create IPFS Universal Path Gateway Content List Entry
free
pro
business
enterprise

POST zones/:zone_identifier/web3/hostnames/:identifier/ipfs_universal_path/content_list/entries

Required parameters

Name /type	Description /example	Constraints
type string	Type of content list entry to block `"cid"`	valid values: cid, content_path
content string	CID or content path of content to block `"QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB"`	max length: 500

Optional parameters

Name /type	Description /example	Constraints
description string	An optional description of the content list entry. `"this is my content list entry"`	max length: 500

cURL (example)

curl -X POST "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/web3/hostnames/9a7806061c88ada191ed06f989cc3dac/ipfs_universal_path/content_list/entries" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"cid","content":"QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB","description":"this is my content list entry"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "type": "cid",
    "content": "QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB",
    "description": "this is my content list entry",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

web3-hostname-ipfs-universal-path-gateway-content-list-entry-details

GET IPFS Universal Path Gateway Content List Entry Details
free
pro
business
enterprise

GET zones/:zone_identifier/web3/hostnames/:identifier/ipfs_universal_path/content_list/entries/:content_list_entry_identifier

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/web3/hostnames/9a7806061c88ada191ed06f989cc3dac/ipfs_universal_path/content_list/entries/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "type": "cid",
    "content": "QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB",
    "description": "this is my content list entry",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

web3-hostname-edit-ipfs-universal-path-gateway-content-list-entry

PUT Edit IPFS Universal Path Gateway Content List Entry
free
pro
business
enterprise

PUT zones/:zone_identifier/web3/hostnames/:identifier/ipfs_universal_path/content_list/entries/:content_list_entry_identifier

Required parameters

Name /type	Description /example	Constraints
type string	Type of content list entry to block `"cid"`	valid values: cid, content_path
content string	CID or content path of content to block `"QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB"`	max length: 500

Optional parameters

Name /type	Description /example	Constraints
description string	An optional description of the content list entry. `"this is my content list entry"`	max length: 500

cURL (example)

curl -X PUT "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/web3/hostnames/9a7806061c88ada191ed06f989cc3dac/ipfs_universal_path/content_list/entries/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json" \
     --data '{"type":"cid","content":"QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB","description":"this is my content list entry"}'

Response (example)

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "9a7806061c88ada191ed06f989cc3dac",
    "type": "cid",
    "content": "QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB",
    "description": "this is my content list entry",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}

web3-hostname-delete-ipfs-universal-path-gateway-content-list-entry

DELETE Delete IPFS Universal Path Gateway Content List Entry
free
pro
business
enterprise

DELETE zones/:zone_identifier/web3/hostnames/:identifier/ipfs_universal_path/content_list/entries/:content_list_entry_identifier

cURL (example)

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/9a7806061c88ada191ed06f989cc3dac/web3/hostnames/9a7806061c88ada191ed06f989cc3dac/ipfs_universal_path/content_list/entries/9a7806061c88ada191ed06f989cc3dac" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

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

Radar NetFlows

Shows network traffic data collected in Cloudflare's edge routers. (Beta)

Either one or multiple queries can be requested at the same time - this is useful when you want, for example, to compare multiple time series (eg. dateRange=7d&location=US&dateRange=7d&location=CA would fetch two time series at the same time, the first for the US, the second for Canada). Take into account that the api is not real time and has a delay of about two hours.

radar-netflows

Object definition

View properties and constraints defined on the object

Show definition

radar-netflows-get-top-autonomous-systems

GET Get top autonomous systems permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top autonomous systems (AS) by network traffic. Values are a percentage out of the total network traffic.

GET radar/netflows/top/ases

Optional parameters

Name /type	Description /example	Constraints
limit number	Limit the number of objects in the response `5`	default value: 5
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/netflows/top/ases?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "result": {
    "top_0": [
      {
        "clientASN": 16509,
        "clientASName": "AMAZON-02",
        "value": "0.73996"
      }
    ]
  }
}

radar-netflows-get-top-locations

GET Get top locations permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top locations by network traffic. Values are a percentage out of the total network traffic.

GET radar/netflows/top/locations

Optional parameters

Name /type	Description /example	Constraints
limit number	Limit the number of objects in the response `5`	default value: 5
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/netflows/top/locations?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "result": {
    "top_0": [
      {
        "clientCountryName": "United States",
        "clientCountryAlpha2": "US",
        "value": "0.73996"
      }
    ]
  }
}

radar-netflows-get-netflow-time-series

GET Get NetFlow time series permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get network traffic change over time. Values are normalized using min-max by default, with the minimum set to 0. When asking for multiple time series, you can also get the percentage relative change of the first/main series, with respect to the second/control series - for example, to get the relative change of this week from the previous week, the first series would have a date range of 7d, the second, a date range of 7dControl, and the normalization would be set to PERCENTAGE_CHANGE.

GET radar/netflows/timeseries

Optional parameters

Name /type	Description /example	Constraints
aggInterval string	Aggregation interval results should be returned in (for example, in 15 minutes or 1 hour intervals). `"1h"`	valid values: 15m, 1h, 1d
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
product array	Array of network traffic product types. `[ "all" ]` An array with items in the following form: Show definition »	valid values: http, all
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
normalization string	Normalization method applied. `"MIN0_MAX"`	valid values: PERCENTAGE_CHANGE, MIN0_MAX

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/netflows/timeseries?aggInterval=1h&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&product=all&asn=15169&location=US,CA&normalization=MIN0_MAX&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "dataSource": "ALL",
          "eventType": "OUTAGE",
          "description": "Cable cut in Tonga",
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-16T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    },
    "aggInterval": "1h",
    "lastUpdated": "2022-09-17T10:22:57.555Z"
  },
  "result": {
    "series": {
      "timestamps": [
        "2022-09-17T10:22:57.555Z"
      ],
      "values": [
        0.56
      ]
    }
  }
}

Radar HTTP

Shows HTTP requests traffic data. (Beta)

radar-http

Object definition

View properties and constraints defined on the object

Show definition

radar-http-get-a-summary-of-device-types

GET Get a summary of device types permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Percentage distribution of traffic per device type.

GET radar/http/summary/device_type

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/summary/device_type?name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {},
  "result": {
    "summary_0": {
      "desktop": "65",
      "mobile": "30",
      "other": "5"
    }
  }
}

radar-http-get-a-summary-of-http-protocols

GET Get a summary of HTTP protocols permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Percentage distribution of traffic per HTTP protocol.

GET radar/http/summary/http_protocol

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/summary/http_protocol?name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {},
  "result": {
    "summary_0": {
      "http": "99",
      "https": "1"
    }
  }
}

radar-http-get-a-summary-of-http-versions

GET Get a summary of HTTP versions permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Percentage distribution of traffic per HTTP protocol version.

GET radar/http/summary/http_version

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/summary/http_version?name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {},
  "result": {
    "summary_0": {
      "HTTP/1.x": "1",
      "HTTP/2": "39",
      "HTTP/3": "60"
    }
  }
}

radar-http-get-a-summary-of-bot-classes

GET Get a summary of bot classes permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Percentage distribution of traffic classified as automated or human.

GET radar/http/summary/bot_class

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/summary/bot_class?name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {},
  "result": {
    "summary_0": {
      "human": "65",
      "bot": "35"
    }
  }
}

radar-http-get-a-summary-of-ip-versions

GET Get a summary of IP versions permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Percentage distribution of traffic per IP protocol version.

GET radar/http/summary/ip_version

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/summary/ip_version?name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {},
  "result": {
    "summary_0": {
      "IPv4": "65",
      "IPv6": "35"
    }
  }
}

radar-http-get-a-summary-of-tls-versions

GET Get a summary of TLS versions permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Percentage distribution of traffic per TLS protocol version.

GET radar/http/summary/tls_version

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/summary/tls_version?name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {},
  "result": {
    "summary_0": {
      "TLS 1.0": "0.5",
      "TLS 1.1": "0.5",
      "TLS 1.2": "60",
      "TLS 1.3": "10",
      "TLS QUIC": "29"
    }
  }
}

radar-http-get-time-series-of-device-types

GET Get time series of device types permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Percentage distribution of traffic per device type over time.

GET radar/http/timeseries/device_type

Optional parameters

Name /type	Description /example	Constraints
aggInterval string	Aggregation interval results should be returned in (for example, in 15 minutes or 1 hour intervals). `"1h"`	valid values: 15m, 1h, 1d
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/timeseries/device_type?aggInterval=1h&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {},
  "result": {
    "serie_0": {
      "timestamps": [
        {}
      ],
      "desktop": [
        {}
      ],
      "mobile": [
        {}
      ],
      "other": [
        {}
      ]
    }
  }
}

radar-http-get-time-series-of-http-protocols

GET Get time series of HTTP protocols permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Percentage distribution of traffic per HTTP protocol over time.

GET radar/http/timeseries/http_protocol

Optional parameters

Name /type	Description /example	Constraints
aggInterval string	Aggregation interval results should be returned in (for example, in 15 minutes or 1 hour intervals). `"1h"`	valid values: 15m, 1h, 1d
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/timeseries/http_protocol?aggInterval=1h&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {},
  "result": {
    "serie_0": {
      "timestamps": [
        {}
      ],
      "http": [
        {}
      ],
      "https": [
        {}
      ]
    }
  }
}

radar-http-get-time-series-of-http-versions

GET Get time series of HTTP versions permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Percentage distribution of traffic per HTTP protocol version over time.

GET radar/http/timeseries/http_version

Optional parameters

Name /type	Description /example	Constraints
aggInterval string	Aggregation interval results should be returned in (for example, in 15 minutes or 1 hour intervals). `"1h"`	valid values: 15m, 1h, 1d
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/timeseries/http_version?aggInterval=1h&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {},
  "result": {
    "serie_0": {
      "timestamps": [
        {}
      ],
      "HTTP/1.x": [
        {}
      ],
      "HTTP/2": [
        {}
      ],
      "HTTP/3": [
        {}
      ]
    }
  }
}

radar-http-get-time-series-of-bot-classes

GET Get time series of bot classes permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Percentage distribution of traffic classified as automated or human over time.

GET radar/http/timeseries/bot_class

Optional parameters

Name /type	Description /example	Constraints
aggInterval string	Aggregation interval results should be returned in (for example, in 15 minutes or 1 hour intervals). `"1h"`	valid values: 15m, 1h, 1d
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/timeseries/bot_class?aggInterval=1h&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {},
  "result": {
    "serie_0": {
      "timestamps": [
        {}
      ],
      "human": [
        {}
      ],
      "bot": [
        {}
      ]
    }
  }
}

radar-http-get-time-series-of-ip-versions

GET Get time series of IP versions permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Percentage distribution of traffic per IP protocol version over time.

GET radar/http/timeseries/ip_version

Optional parameters

Name /type	Description /example	Constraints
aggInterval string	Aggregation interval results should be returned in (for example, in 15 minutes or 1 hour intervals). `"1h"`	valid values: 15m, 1h, 1d
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/timeseries/ip_version?aggInterval=1h&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {},
  "result": {
    "serie_0": {
      "timestamps": [
        {}
      ],
      "IPv4": [
        {}
      ],
      "IPv6": [
        {}
      ]
    }
  }
}

radar-http-get-time-series-of-tls-versions

GET Get time series of TLS versions permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Percentage distribution of traffic per TLS protocol version over time.

GET radar/http/timeseries/tls_version

Optional parameters

Name /type	Description /example	Constraints
aggInterval string	Aggregation interval results should be returned in (for example, in 15 minutes or 1 hour intervals). `"1h"`	valid values: 15m, 1h, 1d
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/timeseries/tls_version?aggInterval=1h&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {},
  "result": {
    "serie_0": {
      "timestamps": [
        {}
      ],
      "TLS 1.0": [
        {}
      ],
      "TLS 1.1": [
        {}
      ],
      "TLS 1.2": [
        {}
      ],
      "TLS 1.3": [
        {}
      ],
      "TLS QUIC": [
        {}
      ]
    }
  }
}

radar-http-get-time-series-of-user-agents

GET Get time series of user agents permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Percentage distribution of traffic of the top user agents in the selected time range, over time.

GET radar/http/timeseries/browser

Optional parameters

Name /type	Description /example	Constraints
aggInterval string	Aggregation interval results should be returned in (for example, in 15 minutes or 1 hour intervals). `"1h"`	valid values: 15m, 1h, 1d
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
limitPerGroup number	Limit the number of objects (eg browsers) to the top items over the time range. `2`	default value: 2

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/timeseries/browser?aggInterval=1h&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&limitPerGroup=2&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {},
  "result": {
    "serie_0": {
      "timestamps": [
        {}
      ],
      "<browser name>": [
        {}
      ]
    }
  }
}

radar-http-get-time-series-of-user-agents-aggregated-in-families

GET Get time series of user agents aggregated in families permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Percentage distribution of traffic of the top user agents aggregated in families in the selected time range, over time.

GET radar/http/timeseries/browser_family

Optional parameters

Name /type	Description /example	Constraints
aggInterval string	Aggregation interval results should be returned in (for example, in 15 minutes or 1 hour intervals). `"1h"`	valid values: 15m, 1h, 1d
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
limitPerGroup number	Limit the number of objects (eg browsers) to the top items over the time range. `2`	default value: 2

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/timeseries/browser_family?aggInterval=1h&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&limitPerGroup=2&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {},
  "result": {
    "serie_0": {
      "timestamps": [
        {}
      ],
      "<browser name>": [
        {}
      ]
    }
  }
}

radar-http-get-top-locations-by-bot-class

GET Get top locations by bot class permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top locations, by HTTP traffic, of the requested bot class. These two categories use Cloudflare's bot score - refer to [Bot scores])https://developers.cloudflare.com/bots/concepts/bot-score). Values are a percentage out of the total traffic.

GET radar/http/top/locations/bot_class/:bot_class

Optional parameters

Name /type	Description /example	Constraints
limit number	Limit the number of objects in the response `5`	default value: 5
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/top/locations/bot_class/likely_automated?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-17T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    }
  },
  "result": {
    "top_0": [
      {
        "clientCountryAlpha2": "US",
        "clientCountryName": "United States",
        "value": "65"
      }
    ]
  }
}

radar-http-get-top-locations-by-device-type

GET Get top locations by device type permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top locations, by HTTP traffic, of the requested device type. Values are a percentage out of the total traffic.

GET radar/http/top/locations/device_type/:device_type

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
limit number	Limit the number of objects in the response `5`	default value: 5
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/top/locations/device_type/desktop?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-17T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    }
  },
  "result": {
    "top_0": [
      {
        "clientCountryAlpha2": "US",
        "clientCountryName": "United States",
        "value": "65"
      }
    ]
  }
}

radar-http-get-top-locations-by-tls-version

GET Get top locations by TLS version permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top locations, by HTTP traffic, of the requested TLS protocol version. Values are a percentage out of the total traffic.

GET radar/http/top/locations/tls_version/:tls_version

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
limit number	Limit the number of objects in the response `5`	default value: 5
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/top/locations/tls_version/tlsv1_0?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-17T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    }
  },
  "result": {
    "top_0": [
      {
        "clientCountryAlpha2": "US",
        "clientCountryName": "United States",
        "value": "65"
      }
    ]
  }
}

radar-http-get-top-locations-by-http-protocol

GET Get top locations by HTTP protocol permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top locations, by HTTP traffic, of the requested HTTP protocol. Values are a percentage out of the total traffic.

GET radar/http/top/locations/http_protocol/:http_protocol

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
limit number	Limit the number of objects in the response `5`	default value: 5
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/top/locations/http_protocol/http?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-17T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    }
  },
  "result": {
    "top_0": [
      {
        "clientCountryAlpha2": "US",
        "clientCountryName": "United States",
        "value": "65"
      }
    ]
  }
}

radar-http-get-top-locations-by-http-version

GET Get top locations by HTTP version permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top locations, by HTTP traffic, of the requested HTTP protocol. Values are a percentage out of the total traffic.

GET radar/http/top/locations/http_version/:http_version

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
limit number	Limit the number of objects in the response `5`	default value: 5
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/top/locations/http_version/httpv1?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-17T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    }
  },
  "result": {
    "top_0": [
      {
        "clientCountryAlpha2": "US",
        "clientCountryName": "United States",
        "value": "65"
      }
    ]
  }
}

radar-http-get-top-locations-by-ip-version

GET Get top locations by IP version permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top locations, by HTTP traffic, of the requested IP protocol version. Values are a percentage out of the total traffic.

GET radar/http/top/locations/ip_version/:ip_version

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
limit number	Limit the number of objects in the response `5`	default value: 5
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/top/locations/ip_version/ipv4?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-17T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    }
  },
  "result": {
    "top_0": [
      {
        "clientCountryAlpha2": "US",
        "clientCountryName": "United States",
        "value": "65"
      }
    ]
  }
}

radar-http-get-top-locations-by-http-requests

GET Get top locations by HTTP requests permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top locations by HTTP traffic. Values are a percentage out of the total traffic.

GET radar/http/top/locations

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
limit number	Limit the number of objects in the response `5`	default value: 5
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/top/locations?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-17T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    }
  },
  "result": {
    "top_0": [
      {
        "clientCountryAlpha2": "US",
        "clientCountryName": "United States",
        "value": "65"
      }
    ]
  }
}

radar-http-get-top-autonomous-systems-by-bot-class

GET Get top autonomous systems by bot class permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top autonomous systems (AS), by HTTP traffic, of the requested bot class. These two categories use Cloudflare's bot score - refer to Bot Scores for more information. Values are a percentage out of the total traffic.

GET radar/http/top/ases/bot_class/:bot_class

Optional parameters

Name /type	Description /example	Constraints
limit number	Limit the number of objects in the response `5`	default value: 5
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/top/ases/bot_class/likely_automated?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-17T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    }
  },
  "result": {
    "top_0": [
      {
        "clientASN": "3243",
        "clientASName": "MEO",
        "value": "3"
      }
    ]
  }
}

radar-http-get-top-autonomous-systems-by-device-type

GET Get top autonomous systems by device type permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top autonomous systems (AS), by HTTP traffic, of the requested device type. Values are a percentage out of the total traffic.

GET radar/http/top/ases/device_type/:device_type

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
limit number	Limit the number of objects in the response `5`	default value: 5
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/top/ases/device_type/desktop?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-17T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    }
  },
  "result": {
    "top_0": [
      {
        "clientASN": "3243",
        "clientASName": "MEO",
        "value": "3"
      }
    ]
  }
}

radar-http-get-top-autonomous-systems-by-tls-version

GET Get top autonomous systems by TLS version permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top autonomous systems (AS), by HTTP traffic, of the requested TLS protocol version. Values are a percentage out of the total traffic.

GET radar/http/top/ases/tls_version/:tls_version

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
limit number	Limit the number of objects in the response `5`	default value: 5
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/top/ases/tls_version/tlsv1_0?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-17T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    }
  },
  "result": {
    "top_0": [
      {
        "clientASN": "3243",
        "clientASName": "MEO",
        "value": "3"
      }
    ]
  }
}

radar-http-get-top-autonomous-systems-by-http-protocol

GET Get top autonomous systems by HTTP protocol permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top autonomous systems (AS), by HTTP traffic, of the requested HTTP protocol. Values are a percentage out of the total traffic.

GET radar/http/top/ases/http_protocol/:http_protocol

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
limit number	Limit the number of objects in the response `5`	default value: 5
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/top/ases/http_protocol/http?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-17T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    }
  },
  "result": {
    "top_0": [
      {
        "clientASN": "3243",
        "clientASName": "MEO",
        "value": "3"
      }
    ]
  }
}

radar-http-get-top-autonomous-systems-by-http-version

GET Get top autonomous systems by HTTP version permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top autonomous systems (AS), by HTTP traffic, of the requested HTTP protocol version. Values are a percentage out of the total traffic.

GET radar/http/top/ases/http_version/:http_version

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
limit number	Limit the number of objects in the response `5`	default value: 5
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/top/ases/http_version/httpv1?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-17T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    }
  },
  "result": {
    "top_0": [
      {
        "clientASN": "3243",
        "clientASName": "MEO",
        "value": "3"
      }
    ]
  }
}

radar-http-get-top-autonomous-systems-by-ip-version

GET Get top autonomous systems by IP version permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top autonomous systems, by HTTP traffic, of the requested IP protocol version. Values are a percentage out of the total traffic.

GET radar/http/top/ases/ip_version/:ip_version

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
limit number	Limit the number of objects in the response `5`	default value: 5
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/top/ases/ip_version/ipv4?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-17T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    }
  },
  "result": {
    "top_0": [
      {
        "clientASN": "3243",
        "clientASName": "MEO",
        "value": "3"
      }
    ]
  }
}

radar-http-get-top-autonomous-systems-by-http-requests

GET Get top autonomous systems by HTTP requests permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top autonomous systems (AS) by HTTP traffic. Values are a percentage out of the total traffic.

GET radar/http/top/ases

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
limit number	Limit the number of objects in the response `5`	default value: 5
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/top/ases?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-17T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    }
  },
  "result": {
    "top_0": [
      {
        "clientASN": "3243",
        "clientASName": "MEO",
        "value": "3"
      }
    ]
  }
}

radar-http-get-top-user-agents-by-http-requests

GET Get top user agents by HTTP requests permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top user agents by HTTP traffic. Values are a percentage out of the total traffic.

GET radar/http/top/browsers

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
limit number	Limit the number of objects in the response `5`	default value: 5
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/top/browsers?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-17T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    }
  },
  "result": {
    "top_0": [
      {}
    ]
  }
}

radar-http-get-top-user-agents-aggregated-in-families-by-http-requests

GET Get top user agents aggregated in families by HTTP requests permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top user agents aggregated in families by HTTP traffic. Values are a percentage out of the total traffic.

GET radar/http/top/browser_families

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
botClass array	Filter for bot class. Refer to Bot Groupings. `[ "LIKELY_AUTOMATED" ]` An array with items in the following form: Show definition »	valid values: LIKELY_AUTOMATED, LIKELY_HUMAN
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
limit number	Limit the number of objects in the response `5`	default value: 5
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/http/top/browser_families?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&botClass=LIKELY_AUTOMATED&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-17T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    }
  },
  "result": {
    "top_0": [
      {}
    ]
  }
}

Radar verified bots

Verified bots requests traffic data. (Beta)

radar-verified-bots

Object definition

View properties and constraints defined on the object

Show definition

radar-verified-bots-get-top-verified-bots-by-http-requests

GET Get top verified bots by HTTP requests permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get top verified bots by HTTP requests, with owner and category.

GET radar/verified_bots/top/bots

Optional parameters

Name /type	Description /example	Constraints
limit number	Limit the number of objects in the response `5`	default value: 5
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/verified_bots/top/bots?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-17T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    }
  },
  "result": {
    "top_0": [
      {
        "botName": "GoogleBot",
        "botCategory": "Search Engine Crawler",
        "botOwner": "Google",
        "value": "29.034407"
      }
    ]
  }
}

radar-verified-bots-get-top-verified-bot-categories-by-http-requests

GET Get top verified bot categories by HTTP requests permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get top verified bot categories by HTTP requests, along with their corresponding percentage, over the total verified bot HTTP requests.

GET radar/verified_bots/top/categories

Optional parameters

Name /type	Description /example	Constraints
limit number	Limit the number of objects in the response `5`	default value: 5
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/verified_bots/top/categories?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-17T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    }
  },
  "result": {
    "top_0": [
      {
        "botCategory": "Search",
        "value": "65"
      }
    ]
  }
}

Radar entities

Metadata information on locations and autonomous systems (AS). (Beta)

radar-entities

Object definition

View properties and constraints defined on the object

Show definition

radar-entities-get-location

GET Get location permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the requested location information. A confidence level below 5 indicates a low level of confidence in the traffic data - normally this happens because Cloudflare has a small amount of traffic from/to this location).

GET radar/entities/locations/:location

Optional parameters

Name /type	Description /example	Constraints
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/entities/locations/US?format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "result": {
    "location": {
      "name": "Afghanistan",
      "region": "Middle East",
      "subregion": "Southern Asia",
      "latitude": 33.939116,
      "longitude": 67.709953,
      "alpha2": "AF",
      "confidenceLvel": 5
    }
  }
}

radar-entities-get-locations

GET Get locations permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get a list of locations.

GET radar/entities/locations

Optional parameters

Name /type	Description /example	Constraints
limit number	Limit the number of objects in the response `5`	default value: 5
offset number	Number of objects to skip before grabbing results `"0"`	default value: 0
location string	Comma separated list of locations. Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `"US,CA"`
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/entities/locations?limit=5&offset=0&location=US,CA&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "result": {
    "locations": [
      {
        "name": "Afghanistan",
        "latitude": 33.939116,
        "longitude": 67.709953,
        "alpha2": "AF"
      }
    ]
  }
}

radar-entities-get-autonomous-system-information-by-ip-address

GET Get autonomous system information by IP address permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

GET radar/entities/asns/ip

Optional parameters

Name /type	Description /example	Constraints
ip string	IP address `"1.1.1.1"`
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/entities/asns/ip?ip=1.1.1.1&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "result": {
    "asn": {
      "name": "Apple Inc.",
      "related": [
        {}
      ],
      "asn": 714,
      "website": "https://www.apple.com/support/systemstatus/"
    }
  }
}

radar-entities-get-autonomous-system-as-by-id

GET Get autonomous system (AS) by ID permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the requested autonomous system information. A confidence level below 5 indicates a low level of confidence in the traffic data - normally this happens because Cloudflare has a small amount of traffic from/to this AS).

GET radar/entities/asns/:asn

Optional parameters

Name /type	Description /example	Constraints
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/entities/asns/3?format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "result": {
    "asn": {
      "name": "Apple Inc.",
      "confidenceLevel": 5,
      "related": [
        {
          "name": "Cogent-174",
          "asn": 174
        }
      ],
      "asn": 714,
      "website": "https://www.apple.com/support/systemstatus/"
    }
  }
}

radar-entities-get-autonomous-systems

GET Get autonomous systems permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Gets a list of autonomous systems (AS).

GET radar/entities/asns

Optional parameters

Name /type	Description /example	Constraints
limit number	Limit the number of objects in the response `5`	default value: 5
offset number	Number of objects to skip before grabbing results `"0"`	default value: 0
asn string	Comma separated list of ASNs. Start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `"174,7922"`
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/entities/asns?limit=5&offset=0&asn=174,7922&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "ases": [
    {
      "name": "Apple Inc.",
      "asn": 714,
      "website": "https://www.apple.com/support/systemstatus/"
    }
  ]
}

Radar attacks

Shows network (L3/4) and application layer (L7) attack traffic data. (Beta)

radar-attacks

Object definition

View properties and constraints defined on the object

Show definition

radar-attacks-get-layer-3-attacks-time-series

GET Get layer 3 attacks time series permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get layer 3/4 attacks change over time. Values are normalized using min-max by default, with the minimum set to 0. When asking for multiple time series, you can also get the percentual relative change of the 1st/main series, with respect to the 2nd/control series - for example, to get the relative change of this week from the previous week, the 1st series would have a date range of 7d, the 2nd, a date range of 7dControl, and the normalization would be set to PERCENTAGE_CHANGE.

GET radar/attacks/layer3/timeseries

Optional parameters

Name /type	Description /example	Constraints
aggInterval string	Aggregation interval results should be returned in (for example, in 15 minutes or 1 hour intervals). `"1h"`	valid values: 15m, 1h, 1d
attack array	Array of L3/4 attack types. `[ "tcp" ]` An array with items in the following form: Show definition »	valid values: udp, tcp, icmp, gre
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
normalization string	Normalization method applied. `"MIN0_MAX"`	valid values: PERCENTAGE_CHANGE, MIN0_MAX

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/attacks/layer3/timeseries?aggInterval=1h&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&attack=tcp&asn=15169&location=US,CA&normalization=MIN0_MAX&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "startTime": "2022-09-16T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    },
    "dateRange": {
      "startTime": "2022-09-16T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    },
    "aggInterval": "1h",
    "lastUpdated": "2022-09-17T10:22:57.555Z"
  },
  "result": {
    "series": {
      "timestamps": [
        "2022-09-17T10:22:57.555Z"
      ],
      "values": [
        0.56
      ]
    }
  }
}

radar-attacks-get-layer-3-attacks-by-network-protocol,-over-time

GET Get layer 3 attacks by network protocol, over time permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get percentage of what type of network protocols are used in layer 3/4 attacks, over time.

GET radar/attacks/layer3/timeseries_groups

Optional parameters

Name /type	Description /example	Constraints
aggInterval string	Aggregation interval results should be returned in (for example, in 15 minutes or 1 hour intervals). `"1h"`	valid values: 15m, 1h, 1d
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/attacks/layer3/timeseries_groups?aggInterval=1h&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "dataSource": "ALL",
          "eventType": "OUTAGE",
          "description": "Cable cut in Tonga",
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-16T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    },
    "aggInterval": "1h",
    "lastUpdated": "2022-09-17T10:22:57.555Z"
  },
  "result": {
    "serie_0": {
      "timeseries": [
        {}
      ],
      "udp": [
        "29"
      ],
      "tcp": [
        "70"
      ],
      "gre": [
        "0.9"
      ],
      "icmp": [
        "0.1"
      ]
    }
  }
}

radar-attacks-get-a-summary-of-layer-3-attacks

GET Get a summary of layer 3 attacks permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Percentage distribution of network protocols in layer 3/4 attacks.

GET radar/attacks/layer3/summary

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/attacks/layer3/summary?name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "result": {
    "meta": {
      "confidenceInfo": {
        "annotations": [
          {
            "dataSource": "ALL",
            "eventType": "OUTAGE",
            "description": "Cable cut in Tonga",
            "startTime": "2022-09-17T10:22:57.555Z",
            "endTime": "2022-09-17T10:22:57.555Z"
          }
        ]
      },
      "dateRange": {
        "startTime": "2022-09-16T10:22:57.555Z",
        "endTime": "2022-09-17T10:22:57.555Z"
      }
    },
    "summary_0": {
      "tcp": "60",
      "udp": "39",
      "gre": "0.9",
      "icmp": "0.1"
    }
  }
}

radar-attacks-get-attacks-layer-7-time-series

GET Get attacks layer 7 time series permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get layer 7 attacks change over time. Values are normalized using min-max by default, with the minimum set to 0. When asking for multiple time series, you can also get the percentage relative change of the first/main series, with respect to the second/control series - for example, to get the relative change of this week from the previous week, the first series would have a date range of 7d, the second, a date range of 7dControl, and the normalization would be set to PERCENTAGE_CHANGE.

GET radar/attacks/layer7/timeseries

Optional parameters

Name /type	Description /example	Constraints
aggInterval string	Aggregation interval results should be returned in (for example, in 15 minutes or 1 hour intervals). `"1h"`	valid values: 15m, 1h, 1d
attack array	Array of L7 attack types. `[ "ddos" ]` An array with items in the following form: Show definition »	valid values: ddos, waf, fw, other
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
normalization string	Normalization method applied. `"MIN0_MAX"`	valid values: PERCENTAGE_CHANGE, MIN0_MAX

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/attacks/layer7/timeseries?aggInterval=1h&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&attack=ddos&asn=15169&location=US,CA&normalization=MIN0_MAX&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "dataSource": "ALL",
          "eventType": "OUTAGE",
          "description": "Cable cut in Tonga",
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-16T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    },
    "aggInterval": "1h",
    "lastUpdated": "2022-09-17T10:22:57.555Z"
  },
  "result": {
    "series": {
      "timestamps": [
        "2022-09-17T10:22:57.555Z"
      ],
      "values": [
        0.56
      ]
    }
  }
}

radar-attacks-get-layer-7-attacks-by-mitigation-technique,-over-time

GET Get layer 7 attacks by mitigation technique, over time permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get percentage of what type of mitigation techniques are used to block layer 7 attacks, over time.

GET radar/attacks/layer7/timeseries_groups

Optional parameters

Name /type	Description /example	Constraints
aggInterval string	Aggregation interval results should be returned in (for example, in 15 minutes or 1 hour intervals). `"1h"`	valid values: 15m, 1h, 1d
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/attacks/layer7/timeseries_groups?aggInterval=1h&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "meta": {
    "confidenceInfo": {
      "annotations": [
        {
          "dataSource": "ALL",
          "eventType": "OUTAGE",
          "description": "Cable cut in Tonga",
          "startTime": "2022-09-17T10:22:57.555Z",
          "endTime": "2022-09-17T10:22:57.555Z"
        }
      ]
    },
    "dateRange": {
      "startTime": "2022-09-16T10:22:57.555Z",
      "endTime": "2022-09-17T10:22:57.555Z"
    },
    "aggInterval": "1h",
    "lastUpdated": "2022-09-17T10:22:57.555Z"
  },
  "result": {
    "serie_0": {
      "timeseries": [
        "2022-09-17T10:22:57.555Z"
      ],
      "udp": [
        "30"
      ],
      "tcp": [
        "60"
      ],
      "gre": [
        "5"
      ],
      "icmp": [
        "5"
      ]
    }
  }
}

radar-attacks-get-a-summary-of-layer-7-attacks

GET Get a summary of layer 7 attacks permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Percentage distribution of mitigation techniques in layer 7 attacks.

GET radar/attacks/layer7/summary

Optional parameters

Name /type	Description /example	Constraints
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
asn array	Array of comma separated list of ASNs, start with `-` to exclude from results. For example, `[-174, 3356]` excludes results from AS174, but includes results from AS3356. `[ "15169" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/attacks/layer7/summary?name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&asn=15169&location=US,CA&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "result": {
    "meta": {
      "confidenceInfo": {
        "annotations": [
          {
            "dataSource": "ALL",
            "eventType": "OUTAGE",
            "description": "Cable cut in Tonga",
            "startTime": "2022-09-17T10:22:57.555Z",
            "endTime": "2022-09-17T10:22:57.555Z"
          }
        ]
      },
      "dateRange": {
        "startTime": "2022-09-16T10:22:57.555Z",
        "endTime": "2022-09-17T10:22:57.555Z"
      }
    },
    "summary_0": {
      "tcp": "65",
      "udp": "34",
      "gre": "0.1",
      "icmp": "0.9"
    }
  }
}

radar-attacks-get-layer-7-top-origin-locations

GET Get layer 7 top origin locations permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top origin locations of and by layer 7 attacks. Values are a percentage out of the total layer 7 attacks. The origin location is determined by the client IP.

GET radar/attacks/layer7/top/locations/origin

Optional parameters

Name /type	Description /example	Constraints
limit number	Limit the number of objects in the response `5`	default value: 5
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/attacks/layer7/top/locations/origin?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "result": {
    "top_0": [
      {
        "originCountryName": "United States",
        "originCountryAlpha2": "US",
        "value": "0.73996",
        "rank": "1"
      }
    ]
  }
}

radar-attacks-get-layer-7-top-target-locations

GET Get layer 7 top target locations permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top target locations of and by layer 7 attacks. Values are a percentage out of the total layer 7 attacks. The target location is determined by the attacked zone's billing country, when available.

GET radar/attacks/layer7/top/locations/target

Optional parameters

Name /type	Description /example	Constraints
limit number	Limit the number of objects in the response `5`	default value: 5
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/attacks/layer7/top/locations/target?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "data": {
    "top_0": [
      {
        "targetCountryName": "United States",
        "targetCountryAlpha2": "US",
        "value": "0.73996",
        "rank": "1"
      }
    ]
  }
}

radar-attacks-get-layer-7-top-attack-pairs-origin-and-target-locations-

GET Get layer 7 top attack pairs (origin and target locations) permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

Get the top attacks from origin to target location. Values are a percentage out of the total layer 7 attacks (with billing country). The attack magnitude can be defined by the number of mitigated requests or by the number of zones affected. You can optionally limit the number of attacks per origin/target location (useful if all the top attacks are from or to the same location).

GET radar/attacks/layer7/top/attacks

Optional parameters

Name /type	Description /example	Constraints
limitDirection array	Array of attack origin/target location attack limits. Together with `limitPerLocation`, limits how many objects will be fetched per origin/target location. `[ "origin" ]` An array with items in the following form: Show definition »	valid values: ORIGIN, TARGET
name array	Array of names that will be used to name the series in responses. `[ "main_series" ]` An array with items in the following form: Show definition »
dateEnd array	Array of datetimes to filter the end of a series. `[ "2022-09-01T09:58:33Z" ]` An array with items in the following form: Show definition »
dateRange array	For example, use `7d` and `7dControl` to compare this week with the previous week. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). `[ "7d" ]` An array with items in the following form: Show definition »	valid values: 1d, 7d, 14d, 28d, 1dControl, 7dControl, 14dControl, 28dControl
magnitude array	Array of attack magnitude options. Attack magnitude can be defined by total requests mitigated or by total zones attacked. `[ "mitigated_requests" ]` An array with items in the following form: Show definition »	valid values: AFFECTED_ZONES, MITIGATED_REQUESTS
dateStart array	Array of datetimes to filter the start of a series. `[ "2022-08-01T09:58:33Z" ]` An array with items in the following form: Show definition »
location array	Array of comma separated list of locations (alpha-2 country codes). Start with `-` to exclude from results. For example, `[-US, PT]` excludes results from the US, but includes results from PT. `[ "US,CA" ]` An array with items in the following form: Show definition »
limitPerLocation number	Limit the number of attacks per origin/target (see `limitDirection` parameter) location. `10`	default value: 10
format string	Format results are returned in. `"json"`	default value: json valid values: json, csv
limit number	Limit the number of objects in the response `5`	default value: 5

cURL (example)

curl -X GET "https://api.cloudflare.com/client/v4/radar/attacks/layer7/top/attacks?limit=5&name=main_series&dateRange=7d&dateStart=2022-08-01T09:58:33Z&dateEnd=2022-09-01T09:58:33Z&location=US,CA&magnitude=mitigated_requests&limitDirection=origin&limitPerLocation=10&format=json" \
     -H "X-Auth-Email: user@example.com" \
     -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" \
     -H "Content-Type: application/json"

Response (example)

{
  "success": true,
  "errors": [
    {}
  ],
  "result": {
    "top_0": [
      {
        "originCountryName": "United States",
        "originCountryAlpha2": "US",
        "targetCountryName": "Portugal",
        "targetCountryAlpha2": "PT",
        "value": "0.73996",
        "rank": "1"
      }
    ]
  }
}

Cloudflare API v4 Documentation

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

API Tokens

Required parameters

Example request

API Token cURL (example)

API Keys

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 permission needed: com.cloudflare.api.user.readfreeprobusinessenterprise

free

pro

business

enterprise

cURL (example)

Response (example)

PATCH Edit User permission needed: com.cloudflare.api.user.updatefreeprobusinessenterprise

free

pro

business

enterprise

Optional parameters

cURL (example)

Response (example)

GET List Tokens permission needed: com.cloudflare.api.token.listfreeprobusinessenterprise

free

pro

business

enterprise

Optional parameters

cURL (example)

Response (example)

POST Create Token permission needed: com.cloudflare.api.token.createfreeprobusinessenterprise

free

pro

business

enterprise

Required parameters

Optional parameters

cURL (example)

Response (example)

GET Token Details permission needed: com.cloudflare.api.token.readfreeprobusinessenterprise

free

pro

business

enterprise

cURL (example)

Response (example)

PUT Update Token permission needed: com.cloudflare.api.token.updatefreeprobusinessenterprise

free

pro

business

enterprise

Optional parameters

cURL (example)

Response (example)

DELETE Delete Token permission needed: com.cloudflare.api.token.deletefreeprobusinessenterprise

free

pro

business

enterprise

GET User Details permission needed: com.cloudflare.api.user.read
free
pro
business
enterprise

PATCH Edit User permission needed: com.cloudflare.api.user.update
free
pro
business
enterprise

GET List Tokens permission needed: com.cloudflare.api.token.list
free
pro
business
enterprise

POST Create Token permission needed: com.cloudflare.api.token.create
free
pro
business
enterprise

GET Token Details permission needed: com.cloudflare.api.token.read
free
pro
business
enterprise

PUT Update Token permission needed: com.cloudflare.api.token.update
free
pro
business
enterprise

DELETE Delete Token permission needed: com.cloudflare.api.token.delete
free
pro
business
enterprise

PUT Roll Token permission needed: com.cloudflare.api.token.update
free
pro
business
enterprise

GET Verify Token
free
pro
business
enterprise

GET List Permission Groups permission needed: com.cloudflare.api.token.read
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