Get an account or zone ruleset

GET/{accounts_or_zones}/{account_or_zone_id}/rulesets/{ruleset_id}

Fetches the latest version of an account or zone ruleset.

Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

Accepted Permissions (at least one required)

Mass URL Redirects WriteMass URL Redirects ReadMagic Firewall WriteMagic Firewall ReadL4 DDoS Managed Ruleset WriteL4 DDoS Managed Ruleset ReadTransform Rules WriteTransform Rules ReadSelect Configuration WriteSelect Configuration ReadAccount WAF WriteAccount WAF ReadAccount Rulesets ReadAccount Rulesets WriteLogs WriteLogs Read

Path ParametersExpand Collapse

ruleset_id: string

The unique ID of the ruleset.

account_id: optional string

The Account ID to use for this endpoint. Mutually exclusive with the Zone ID.

zone_id: optional string

The Zone ID to use for this endpoint. Mutually exclusive with the Account ID.

ReturnsExpand Collapse

errors: array of object { message, code, source }

A list of error messages.

message: string

A text description of this message.

minLength1

code: optional number

A unique code for this message.

source: optional object { pointer }

The source of this message.

pointer: string

A JSON pointer to the field that is the source of the message.

minLength1

messages: array of object { message, code, source }

A list of warning messages.

message: string

A text description of this message.

minLength1

code: optional number

A unique code for this message.

source: optional object { pointer }

The source of this message.

pointer: string

A JSON pointer to the field that is the source of the message.

minLength1

result: object { id, kind, last_updated, 5 more }

A ruleset object.

id: string

The unique ID of the ruleset.

kind: Kind

The kind of the ruleset.

One of the following:

"managed"

"custom"

"root"

"zone"

last_updated: string

The timestamp of when the ruleset was last modified.

formatdate-time

name: string

The human-readable name of the ruleset.

minLength1

phase: Phase

The phase of the ruleset.

One of the following:

"ddos_l4"

"ddos_l7"

"http_config_settings"

"http_custom_errors"

"http_log_custom_fields"

"http_ratelimit"

"http_request_cache_settings"

"http_request_dynamic_redirect"

"http_request_firewall_custom"

"http_request_firewall_managed"

"http_request_late_transform"

"http_request_origin"

"http_request_redirect"

"http_request_sanitize"

"http_request_sbfm"

"http_request_transform"

"http_response_cache_settings"

"http_response_compression"

"http_response_firewall_managed"

"http_response_headers_transform"

"magic_transit"

"magic_transit_ids_managed"

"magic_transit_managed"

"magic_transit_ratelimit"

rules: array of BlockRule { last_updated, version, id, 10 more } or object { last_updated, version, id, 10 more } or CompressResponseRule { last_updated, version, id, 10 more } or 17 more

The list of rules in the ruleset.

One of the following:

BlockRule object { last_updated, version, id, 10 more }

last_updated: string

The timestamp of when the rule was last modified.

formatdate-time

version: string

The version of the rule.

id: optional string

The unique ID of the rule.

action: optional "block"

The action to perform when the rule matches.

action_parameters: optional object { response }

The parameters configuring the rule’s action.

response: optional object { content, content_type, status_code }

The response to show when the block is applied.

content: string

The content to return.

minLength1

content_type: string

The type of the content to return.

minLength1

status_code: number

The status code to return.

maximum499

minimum400

categories: optional array of string

The categories of the rule.

description: optional string

An informative description of the rule.

enabled: optional boolean

Whether the rule should be executed.

exposed_credential_check: optional object { password_expression, username_expression }

Configuration for exposed credential checking.

password_expression: string

An expression that selects the password used in the credentials check.

minLength1

username_expression: string

An expression that selects the user ID used in the credentials check.

minLength1

expression: optional string

The expression defining which traffic will match the rule.

minLength1

logging: optional Logging { enabled }

An object configuring the rule’s logging behavior.

enabled: boolean

Whether to generate a log when the rule matches.

ratelimit: optional object { characteristics, period, counting_expression, 5 more }

An object configuring the rule’s rate limit behavior.

characteristics: array of string

Characteristics of the request on which the rate limit counter will be incremented.

period: number

Period in seconds over which the counter is being incremented.

minimum0

counting_expression: optional string

An expression that defines when the rate limit counter should be incremented. It defaults to the same as the rule’s expression.

minLength1

mitigation_timeout: optional number

Period of time in seconds after which the action will be disabled following its first execution.

requests_per_period: optional number

The threshold of requests per period after which the action will be executed for the first time.

minimum1

requests_to_origin: optional boolean

Whether counting is only performed when an origin is reached.

score_per_period: optional number

The score threshold per period for which the action will be executed the first time.

score_response_header_name: optional string

A response header name provided by the origin, which contains the score to increment rate limit counter with.

minLength1

ref: optional string

The reference of the rule (the rule’s ID by default).

minLength1

Challenge object { last_updated, version, id, 10 more }

last_updated: string

The timestamp of when the rule was last modified.

formatdate-time

version: string

The version of the rule.

id: optional string

The unique ID of the rule.

action: optional "challenge"

The action to perform when the rule matches.

action_parameters: optional unknown

The parameters configuring the rule’s action.

categories: optional array of string

The categories of the rule.

description: optional string

An informative description of the rule.

enabled: optional boolean

Whether the rule should be executed.

exposed_credential_check: optional object { password_expression, username_expression }

Configuration for exposed credential checking.

password_expression: string

An expression that selects the password used in the credentials check.

minLength1

username_expression: string

An expression that selects the user ID used in the credentials check.

minLength1

expression: optional string

The expression defining which traffic will match the rule.

minLength1

logging: optional Logging { enabled }

An object configuring the rule’s logging behavior.

enabled: boolean

Whether to generate a log when the rule matches.

ratelimit: optional object { characteristics, period, counting_expression, 5 more }

An object configuring the rule’s rate limit behavior.

characteristics: array of string

Characteristics of the request on which the rate limit counter will be incremented.

period: number

Period in seconds over which the counter is being incremented.

minimum0

counting_expression: optional string

An expression that defines when the rate limit counter should be incremented. It defaults to the same as the rule’s expression.

minLength1

mitigation_timeout: optional number

Period of time in seconds after which the action will be disabled following its first execution.

requests_per_period: optional number

The threshold of requests per period after which the action will be executed for the first time.

minimum1

requests_to_origin: optional boolean

Whether counting is only performed when an origin is reached.

score_per_period: optional number

The score threshold per period for which the action will be executed the first time.

score_response_header_name: optional string

A response header name provided by the origin, which contains the score to increment rate limit counter with.

minLength1

ref: optional string

The reference of the rule (the rule’s ID by default).

minLength1

CompressResponseRule object { last_updated, version, id, 10 more }

last_updated: string

The timestamp of when the rule was last modified.

formatdate-time

version: string

The version of the rule.

id: optional string

The unique ID of the rule.

action: optional "compress_response"

The action to perform when the rule matches.

action_parameters: optional object { algorithms }

The parameters configuring the rule’s action.

algorithms: array of object { name }

Custom order for compression algorithms.

name: optional "none" or "auto" or "default" or 3 more

Name of the compression algorithm to enable.

One of the following:

"none"

"auto"

"default"

"gzip"

"brotli"

"zstd"

categories: optional array of string

The categories of the rule.

description: optional string

An informative description of the rule.

enabled: optional boolean

Whether the rule should be executed.

exposed_credential_check: optional object { password_expression, username_expression }

Configuration for exposed credential checking.

password_expression: string

An expression that selects the password used in the credentials check.

minLength1

username_expression: string

An expression that selects the user ID used in the credentials check.

minLength1

expression: optional string

The expression defining which traffic will match the rule.

minLength1

logging: optional Logging { enabled }

An object configuring the rule’s logging behavior.

enabled: boolean

Whether to generate a log when the rule matches.

ratelimit: optional object { characteristics, period, counting_expression, 5 more }

An object configuring the rule’s rate limit behavior.

characteristics: array of string

Characteristics of the request on which the rate limit counter will be incremented.

period: number

Period in seconds over which the counter is being incremented.

minimum0

counting_expression: optional string

An expression that defines when the rate limit counter should be incremented. It defaults to the same as the rule’s expression.

minLength1

mitigation_timeout: optional number

Period of time in seconds after which the action will be disabled following its first execution.

requests_per_period: optional number

The threshold of requests per period after which the action will be executed for the first time.

minimum1

requests_to_origin: optional boolean

Whether counting is only performed when an origin is reached.

score_per_period: optional number

The score threshold per period for which the action will be executed the first time.

score_response_header_name: optional string

A response header name provided by the origin, which contains the score to increment rate limit counter with.

minLength1

ref: optional string

The reference of the rule (the rule’s ID by default).

minLength1

DDoSDynamicRule object { last_updated, version, id, 10 more }

last_updated: string

The timestamp of when the rule was last modified.

formatdate-time

version: string

The version of the rule.

id: optional string

The unique ID of the rule.

action: optional "ddos_dynamic"

The action to perform when the rule matches.

action_parameters: optional unknown

The parameters configuring the rule’s action.

categories: optional array of string

The categories of the rule.

description: optional string

An informative description of the rule.

enabled: optional boolean

Whether the rule should be executed.

exposed_credential_check: optional object { password_expression, username_expression }

Configuration for exposed credential checking.

password_expression: string

An expression that selects the password used in the credentials check.

minLength1

username_expression: string

An expression that selects the user ID used in the credentials check.

minLength1

expression: optional string

The expression defining which traffic will match the rule.

minLength1

logging: optional Logging { enabled }

An object configuring the rule’s logging behavior.

enabled: boolean

Whether to generate a log when the rule matches.

ratelimit: optional object { characteristics, period, counting_expression, 5 more }

An object configuring the rule’s rate limit behavior.

characteristics: array of string

Characteristics of the request on which the rate limit counter will be incremented.

period: number

Period in seconds over which the counter is being incremented.

minimum0

counting_expression: optional string

An expression that defines when the rate limit counter should be incremented. It defaults to the same as the rule’s expression.

minLength1

mitigation_timeout: optional number

Period of time in seconds after which the action will be disabled following its first execution.

requests_per_period: optional number

The threshold of requests per period after which the action will be executed for the first time.

minimum1

requests_to_origin: optional boolean

Whether counting is only performed when an origin is reached.

score_per_period: optional number

The score threshold per period for which the action will be executed the first time.

score_response_header_name: optional string

A response header name provided by the origin, which contains the score to increment rate limit counter with.

minLength1

ref: optional string

The reference of the rule (the rule’s ID by default).

minLength1

ExecuteRule object { last_updated, version, id, 10 more }

last_updated: string

The timestamp of when the rule was last modified.

formatdate-time

version: string

The version of the rule.

id: optional string

The unique ID of the rule.

action: optional "execute"

The action to perform when the rule matches.

action_parameters: optional object { id, matched_data, overrides }

The parameters configuring the rule’s action.

id: string

The ID of the ruleset to execute.

matched_data: optional object { public_key }

The configuration to use for matched data logging.

public_key: string

The public key to encrypt matched data logs with.

minLength1

overrides: optional object { action, categories, enabled, 2 more }

A set of overrides to apply to the target ruleset.

action: optional string

An action to override all rules with. This option has lower precedence than rule and category overrides.

categories: optional array of object { category, action, enabled, sensitivity_level }

A list of category-level overrides. This option has the second-highest precedence after rule-level overrides.

category: string

The name of the category to override.

minLength1

action: optional string

The action to override rules in the category with.

enabled: optional boolean

Whether to enable execution of rules in the category.

sensitivity_level: optional "default" or "medium" or "low" or "eoff"

The sensitivity level to use for rules in the category. This option is only applicable for DDoS phases.

One of the following:

"default"

"medium"

"low"

"eoff"

enabled: optional boolean

Whether to enable execution of all rules. This option has lower precedence than rule and category overrides.

rules: optional array of object { id, action, enabled, 2 more }

A list of rule-level overrides. This option has the highest precedence.

id: string

The ID of the rule to override.

action: optional string

The action to override the rule with.

enabled: optional boolean

Whether to enable execution of the rule.

score_threshold: optional number

The score threshold to use for the rule.

sensitivity_level: optional "default" or "medium" or "low" or "eoff"

The sensitivity level to use for the rule. This option is only applicable for DDoS phases.

One of the following:

"default"

"medium"

"low"

"eoff"