API docs by Redocly

API Gateway APIs (4.0.0)

Download OpenAPI specification:Download

The Cloudflare Client API

API Shield Settings

Retrieve information about specific configuration properties

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

query Parameters
properties
Array of strings (properties) unique
Items Value: "auth_id_characteristics"
Example: properties=auth_id_characteristics

Requests information about certain properties.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": {
    }
}

Set configuration properties

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

Request Body schema: application/json
required
Array of objects (characteristics) <= 10 items unique

Responses

Request samples

Content type
application/json
{
  • "auth_id_characteristics": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": { }
}

API Shield Endpoint Management

Retrieve information about an operation

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

operation_id
required
string <uuid> <= 36 characters
Example: f174e90a-fafe-4643-bbbc-4a0ed4fc8415

Identifier for the operation

query Parameters
feature
Array of strings unique
Items Enum: "thresholds" "parameter_schemas" "schema_info"
Example: feature=thresholds

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.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": {
    }
}

Delete an operation

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

operation_id
required
string <uuid> <= 36 characters
Example: f174e90a-fafe-4643-bbbc-4a0ed4fc8415

Identifier for the operation

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": { }
}

Retrieve information about all operations on a zone

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

query Parameters
page
number >= 1
Default: 1

Page number of paginated results.

per_page
number >= 5
Default: 20

Number of results to return per page

order
string
Enum: "method" "host" "endpoint" "thresholds.$key"
Example: order=method

Field to order by. When requesting a feature, the feature keys are available for ordering as well, e.g., thresholds.suggested_threshold.

direction
string
Enum: "asc" "desc"
Example: direction=desc

Direction to order results.

host
Array of strings unique
Example: host=api.cloudflare.com

Filter results to only include the specified hosts.

method
Array of strings unique
Example: method=GET

Filter results to only include the specified HTTP methods.

endpoint
string
Example: endpoint=/api/v1

Filter results to only include endpoints containing this pattern.

feature
Array of strings unique
Items Enum: "thresholds" "parameter_schemas" "schema_info"
Example: feature=thresholds

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.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": [
    ],
  • "result_info": {
    }
}

Add operations to a zone

Add one or more operations to a zone. Endpoints can contain path variables. Host, method, endpoint will be normalized to a canoncial form when creating an operation and must be unique on the zone. Inserting an operation that matches an existing one will return the record of the already existing operation and update its last_updated date.

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

Request Body schema: application/json
required
Array
method
required
string (method)
Enum: "GET" "POST" "HEAD" "OPTIONS" "PUT" "DELETE" "CONNECT" "PATCH" "TRACE"

The HTTP method used to access the endpoint.

host
required
string <hostname> (host) <= 255 characters

RFC3986-compliant host.

endpoint
required
string <uri-template> (endpoint) <= 4096 characters ^/.*$

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

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": [
    ],
  • "result_info": {
    }
}

Retrieve operations and features as OpenAPI schemas

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

query Parameters
host
Array of strings unique
Example: host=www.example.com

Receive schema only for the given host(s).

feature
Array of strings unique
Items Enum: "thresholds" "parameter_schemas" "schema_info"
Example: feature=thresholds

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.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": {
    }
}

API Shield API Discovery

Retrieve discovered operations on a zone

Retrieve the most up to date view of discovered operations

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

query Parameters
page
number >= 1
Default: 1

Page number of paginated results.

per_page
number [ 5 .. 50 ]
Default: 20

Maximum number of results per page.

host
Array of strings unique
Example: host=api.cloudflare.com

Filter results to only include the specified hosts.

method
Array of strings unique
Example: method=GET

Filter results to only include the specified HTTP methods.

endpoint
string
Example: endpoint=/api/v1

Filter results to only include endpoints containing this pattern.

direction
string
Enum: "asc" "desc"
Example: direction=desc

Direction to order results.

order
string
Enum: "host" "method" "endpoint" "traffic_stats.requests" "traffic_stats.last_updated"
Example: order=method

Field to order by

diff
boolean

When true, only return API Discovery results that are not saved into API Shield Endpoint Management

origin
string (api_discovery_origin)
Enum: "ML" "SessionIdentifier"

Filter results to only include discovery results sourced from a particular discovery engine

  • ML - Discovered operations that were sourced using ML API Discovery
  • SessionIdentifier - Discovered operations that were sourced using Session Identifier API Discovery
state
string (api_discovery_state)
Enum: "review" "saved" "ignored"

Filter results to only include discovery results in a particular state. States are as follows

  • review - Discovered operations that are not saved into API Shield Endpoint Management
  • saved - Discovered operations that are already saved into API Shield Endpoint Management
  • ignored - Discovered operations that have been marked as ignored

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": [
    ],
  • "result_info": {
    }
}

Patch discovered operations

Update the state on one or more discovered operations

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

Request Body schema: application/json
required
additional property
object (api_discovery_patch_multiple_request_entry)

Operation ID to patch state mappings

Responses

Request samples

Content type
application/json
{
  • "b17c8043-99a0-4202-b7d9-8f7cdbee02cd": {
    },
  • "3818d821-5901-4147-a474-f5f5aec1d54e": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": {
    }
}

Patch discovered operation

Update the state on a discovered operation

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

operation_id
required
string <uuid> (uuid) = 36 characters
Example: 0d9bf70c-92e1-4bb3-9411-34a3bcc59003

Identifier for the discovered operation

Request Body schema: application/json
required
state
string
Enum: "review" "ignored"

Mark state of operation in API Discovery

  • review - Mark operation as for review
  • ignored - Mark operation as ignored

Responses

Request samples

Content type
application/json
{
  • "state": "review"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": {
    }
}

Retrieve discovered operations on a zone rendered as OpenAPI schemas

Retrieve the most up to date view of discovered operations, rendered as OpenAPI schemas

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": {
    }
}

API Shield Schema Validation 2.0

Retrieve information about all schemas on a zone

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

query Parameters
page
number >= 1
Default: 1

Page number of paginated results.

per_page
number [ 5 .. 50 ]
Default: 20

Maximum number of results per page.

omit_source
boolean
Default: false

Omit the source-files of schemas and only retrieve their meta-data.

validation_enabled
boolean (validation_enabled)

Flag whether schema is enabled for validation.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": [
    ],
  • "result_info": {
    }
}

Upload a schema to a zone

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

Request Body schema: multipart/form-data
required
file
required
string <binary>

Schema file bytes

kind
required
string (kind)
Value: "openapi_v3"

Kind of schema

name
string

Name of the schema

validation_enabled
string
Enum: "true" "false"

Flag whether schema is enabled for validation.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": {
    }
}

Retrieve information about a specific schema on a zone

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

schema_id
required
string <uuid> <= 36 characters
Example: f174e90a-fafe-4643-bbbc-4a0ed4fc8415

Identifier for the schema-ID

query Parameters
omit_source
boolean
Default: false

Omit the source-files of schemas and only retrieve their meta-data.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": {
    }
}

Enable validation for a schema

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

schema_id
required
string <uuid> <= 36 characters
Example: f174e90a-fafe-4643-bbbc-4a0ed4fc8415

Identifier for the schema-ID

Request Body schema: application/json
required
validation_enabled
boolean
Value: true

Flag whether schema is enabled for validation.

Responses

Request samples

Content type
application/json
{
  • "validation_enabled": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": {
    }
}

Delete a schema

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

schema_id
required
string <uuid> <= 36 characters
Example: f174e90a-fafe-4643-bbbc-4a0ed4fc8415

Identifier for the schema-ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": { }
}

Retrieve all operations from a schema.

Retrieves all operations from the schema. Operations that already exist in API Shield Endpoint Management will be returned as full operations.

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
schema_id
required
string <uuid> <= 36 characters
Example: f174e90a-fafe-4643-bbbc-4a0ed4fc8415

Identifier for the schema-ID

zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

query Parameters
feature
Array of strings unique
Items Enum: "thresholds" "parameter_schemas" "schema_info"
Example: feature=thresholds

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.

host
Array of strings unique
Example: host=api.cloudflare.com

Filter results to only include the specified hosts.

method
Array of strings unique
Example: method=GET

Filter results to only include the specified HTTP methods.

endpoint
string
Example: endpoint=/api/v1

Filter results to only include endpoints containing this pattern.

page
number >= 1
Default: 1

Page number of paginated results.

per_page
number [ 5 .. 50 ]
Default: 20

Maximum number of results per page.

operation_status
string
Enum: "new" "existing"
Example: operation_status=new

Filter results by whether operations exist in API Shield Endpoint Management or not. new will just return operations from the schema that do not exist in API Shield Endpoint Management. existing will just return operations from the schema that already exist in API Shield Endpoint Management.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": [
    ],
  • "result_info": {
    }
}

Retrieve zone level schema validation settings

Retrieves zone level schema validation settings currently set on the zone

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

Responses

Response samples

Content type
application/json
{
  • "validation_default_mitigation_action": "block",
  • "validation_override_mitigation_action": "disable_override"
}

Update zone level schema validation settings

Updates zone level schema validation settings on the zone

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

Request Body schema: application/json
required
validation_default_mitigation_action
required
string (validation_default_mitigation_action)
Enum: "none" "log" "block"

The default mitigation action used when there is no mitigation action defined on the operation

Mitigation actions are as follows:

  • log - log request when request does not conform to schema
  • block - deny access to the site when request does not conform to schema

A special value of of none will skip running schema validation entirely for the request when there is no mitigation action defined on the operation

validation_override_mitigation_action
string or null (validation_override_mitigation_action_write)
Enum: "none" "disable_override" null

When set, this overrides both zone level and operation level mitigation actions.

  • none will skip running schema validation entirely for the request
  • null indicates that no override is in place

To clear any override, use the special value disable_override or null

Responses

Request samples

Content type
application/json
{
  • "validation_default_mitigation_action": "block",
  • "validation_override_mitigation_action": "none"
}

Response samples

Content type
application/json
{
  • "validation_default_mitigation_action": "block",
  • "validation_override_mitigation_action": "disable_override"
}

Update zone level schema validation settings

Updates zone level schema validation settings on the zone

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

Request Body schema: application/json
required
validation_default_mitigation_action
string or null (validation_default_mitigation_action_patch)
Enum: "none" "log" "block" null

The default mitigation action used when there is no mitigation action defined on the operation Mitigation actions are as follows:

  • log - log request when request does not conform to schema
  • block - deny access to the site when request does not conform to schema

A special value of of none will skip running schema validation entirely for the request when there is no mitigation action defined on the operation

null will have no effect.

validation_override_mitigation_action
string or null (validation_override_mitigation_action_patch)
Enum: "none" "disable_override" null

When set, this overrides both zone level and operation level mitigation actions.

  • none will skip running schema validation entirely for the request

To clear any override, use the special value disable_override

null will have no effect.

Responses

Request samples

Content type
application/json
{
  • "validation_default_mitigation_action": "block",
  • "validation_override_mitigation_action": "none"
}

Response samples

Content type
application/json
{
  • "validation_default_mitigation_action": "block",
  • "validation_override_mitigation_action": "disable_override"
}

Retrieve operation-level schema validation settings

Retrieves operation-level schema validation settings on the zone

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

operation_id
required
string <uuid> <= 36 characters
Example: f174e90a-fafe-4643-bbbc-4a0ed4fc8415

Identifier for the operation

Responses

Response samples

Content type
application/json
{
  • "mitigation_action": "block"
}

Update operation-level schema validation settings

Updates operation-level schema validation settings on the zone

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

operation_id
required
string <uuid> <= 36 characters
Example: f174e90a-fafe-4643-bbbc-4a0ed4fc8415

Identifier for the operation

Request Body schema: application/json
required
mitigation_action
string or null (operation_mitigation_action)
Enum: "log" "block" "none" null

When set, this applies a mitigation action to this operation

  • log log request when request does not conform to schema for this operation
  • block deny access to the site when request does not conform to schema for this operation
  • none will skip mitigation for this operation
  • null indicates that no operation level mitigation is in place, see Zone Level Schema Validation Settings for mitigation action that will be applied

Responses

Request samples

Content type
application/json
{
  • "mitigation_action": "block"
}

Response samples

Content type
application/json
{
  • "mitigation_action": "block"
}

Update multiple operation-level schema validation settings

Updates multiple operation-level schema validation settings on the zone

Authorizations:
(api_tokenapi_keyapi_email)
path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

Request Body schema: application/json
required
additional property
object (operation_schema_validation_settings_multiple_request_entry)

Operation ID to mitigation action mappings

Responses

Request samples

Content type
application/json
{
  • "b17c8043-99a0-4202-b7d9-8f7cdbee02cd": {
    },
  • "3818d821-5901-4147-a474-f5f5aec1d54e": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": {
    }
}

API Shield Sequence Rules

List rules

List all currently configured sequence rules.

path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

query Parameters
page
number >= 1
Default: 1

Page number of paginated results.

per_page
number [ 5 .. 50 ]
Default: 20

Maximum number of results per page.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": {
    },
  • "result_info": {
    }
}

Set rules

Replace the existing set of rules with the ones provided.

path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

Request Body schema: application/json
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "rules": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": {
    }
}

Add a rule

Adds a single rule to the set of sequence rules.

path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

Request Body schema: application/json
required
title
required
string [ 1 .. 50 ] characters

A short description of the rule

kind
required
string
Enum: "block" "allow"

Describes if the sequence should be allowed or forbidden

action
required
string
Enum: "block" "log"

The action that should be performed when the sequence rules is activated

sequence
required
Array of strings <uuid> = 2 items unique [ items <uuid > = 36 characters ]

References to operations from endpoint management which form a sequence. Operations must all have the same host.

priority
required
integer
Default: 0

An indicator which precedence this rules has over other rules. Rules with a higher priority number are executed before rules with a lower priority number. Rules with the same priority are executed in order that they were added.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "kind": "block",
  • "action": "block",
  • "sequence": [
    ],
  • "priority": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": {
    }
}

Edit a rule

Change properties of an existing rule within the set of sequence rules.

path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

rule_id
required
string <uuid> (uuid) = 36 characters
Example: 0d9bf70c-92e1-4bb3-9411-34a3bcc59003

UUID identifier

Request Body schema: application/json
required
non-empty
title
string [ 1 .. 50 ] characters

A short description of the rule

kind
string
Enum: "block" "allow"

Describes if the sequence should be allowed or forbidden

action
string
Enum: "block" "log"

The action that should be performed when the sequence rules is activated

sequence
Array of strings <uuid> = 2 items unique [ items <uuid > = 36 characters ]

References to operations from endpoint management which form a sequence. Operations must all have the same host.

priority
integer
Default: 0

An indicator which precedence this rules has over other rules. Rules with a higher priority number are executed before rules with a lower priority number. Rules with the same priority are executed in order that they were added.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "kind": "block",
  • "action": "block",
  • "sequence": [
    ],
  • "priority": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": {
    }
}

Delete a rule

Removes a single rule from the set of sequence rules.

path Parameters
zone_id
required
string (identifier) <= 32 characters
Example: 023e105f4ecef8ad9ca31a8372d0c353

Identifier

rule_id
required
string <uuid> (uuid) = 36 characters
Example: 0d9bf70c-92e1-4bb3-9411-34a3bcc59003

UUID identifier

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": [ ],
  • "messages": [ ],
  • "result": {
    }
}