Skip to content
Cloudflare API
Start here
API Reference
Rulesets

Versions

List an account or zone ruleset's versions
rulesets.versions.list(strruleset_id, VersionListParams**kwargs) -> SyncSinglePage[VersionListResponse]
GET/{accounts_or_zones}/{account_or_zone_id}/rulesets/{ruleset_id}/versions
Get an account or zone ruleset version
rulesets.versions.get(strruleset_version, VersionGetParams**kwargs) -> VersionGetResponse
GET/{accounts_or_zones}/{account_or_zone_id}/rulesets/{ruleset_id}/versions/{ruleset_version}
Delete an account or zone ruleset version
rulesets.versions.delete(strruleset_version, VersionDeleteParams**kwargs)
DELETE/{accounts_or_zones}/{account_or_zone_id}/rulesets/{ruleset_id}/versions/{ruleset_version}
ModelsExpand Collapse
class VersionListResponse: …

A ruleset object.

id: str

The unique ID of the ruleset.

kind: Kind

The kind of the ruleset.

last_updated: datetime

The timestamp of when the ruleset was last modified.

formatdate-time
name: str

The human-readable name of the ruleset.

minLength1
phase: Phase

The phase of the ruleset.

version: str

The version of the ruleset.

description: Optional[str]

An informative description of the ruleset.

class VersionGetResponse: …

A ruleset object.

id: str

The unique ID of the ruleset.

kind: Kind

The kind of the ruleset.

last_updated: datetime

The timestamp of when the ruleset was last modified.

formatdate-time
name: str

The human-readable name of the ruleset.

minLength1
phase: Phase

The phase of the ruleset.

rules: List[Rule]

The list of rules in the ruleset.

One of the following:
class RuleBlockRule: …
id: str
action: str
enabled: bool
expression: str
ref: str
class RuleChallengeRule: …
id: str

The unique ID of the rule.

action: Literal["challenge"]

The action to perform when the rule matches.

enabled: bool

Whether the rule should be executed.

expression: str

The expression defining which traffic will match the rule.

minLength1
last_updated: datetime

The timestamp of when the rule was last modified.

formatdate-time
ref: str

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

minLength1
version: str

The version of the rule.

action_parameters: Optional[object]

The parameters configuring the rule’s action.

categories: Optional[List[str]]

The categories of the rule.

description: Optional[str]

An informative description of the rule.

exposed_credential_check: Optional[RuleChallengeRuleExposedCredentialCheck]

Configuration for exposed credential checking.

password_expression: str

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

minLength1
username_expression: str

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

minLength1
logging: Optional[Logging]

An object configuring the rule’s logging behavior.

ratelimit: Optional[RuleChallengeRuleRatelimit]

An object configuring the rule’s rate limit behavior.

characteristics: List[str]

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

period: int

Period in seconds over which the counter is being incremented.

minimum0
counting_expression: Optional[str]

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[int]

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

requests_per_period: Optional[int]

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

minimum1
requests_to_origin: Optional[bool]

Whether counting is only performed when an origin is reached.

score_per_period: Optional[int]

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

score_response_header_name: Optional[str]

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

minLength1
class RuleResponseCompressionRule: …
id: str
action: str
enabled: bool
expression: str
ref: str
class RuleDDoSDynamicRule: …
id: str
action: str
enabled: bool
expression: str
ref: str
class RuleExecuteRule: …
id: str
action: str
enabled: bool
expression: str
ref: str
class RuleForceConnectionCloseRule: …
id: str
action: str
enabled: bool
expression: str
ref: str
class RuleJavaScriptChallengeRule: …
id: str

The unique ID of the rule.

action: Literal["js_challenge"]

The action to perform when the rule matches.

enabled: bool

Whether the rule should be executed.

expression: str

The expression defining which traffic will match the rule.

minLength1
last_updated: datetime

The timestamp of when the rule was last modified.

formatdate-time
ref: str

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

minLength1
version: str

The version of the rule.

action_parameters: Optional[object]

The parameters configuring the rule’s action.

categories: Optional[List[str]]

The categories of the rule.

description: Optional[str]

An informative description of the rule.

exposed_credential_check: Optional[RuleJavaScriptChallengeRuleExposedCredentialCheck]

Configuration for exposed credential checking.

password_expression: str

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

minLength1
username_expression: str

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

minLength1
logging: Optional[Logging]

An object configuring the rule’s logging behavior.

ratelimit: Optional[RuleJavaScriptChallengeRuleRatelimit]

An object configuring the rule’s rate limit behavior.

characteristics: List[str]

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

period: int

Period in seconds over which the counter is being incremented.

minimum0
counting_expression: Optional[str]

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[int]

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

requests_per_period: Optional[int]

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

minimum1
requests_to_origin: Optional[bool]

Whether counting is only performed when an origin is reached.

score_per_period: Optional[int]

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

score_response_header_name: Optional[str]

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

minLength1
class RuleLogRule: …
id: str
action: str
enabled: bool
expression: str
ref: str
class RuleLogCustomFieldRule: …
id: str
action: str
enabled: bool
expression: str
ref: str
class RuleManagedChallengeRule: …
id: str
action: str
enabled: bool
expression: str
ref: str
class RuleRedirectRule: …
id: str
action: str
enabled: bool
expression: str
ref: str
class RuleRewriteRule: …
id: str
action: str
enabled: bool
expression: str
ref: str
class RuleRouteRule: …
id: str
action: str
enabled: bool
expression: str
ref: str
class RuleScoreRule: …
id: str
action: str
enabled: bool
expression: str
ref: str
class RuleServeErrorRule: …
id: str
action: str
enabled: bool
expression: str
ref: str
class RuleSetCacheControlRule: …
id: str

The unique ID of the rule.

action: Literal["set_cache_control"]

The action to perform when the rule matches.

enabled: bool
expression: str

The expression defining which traffic will match the rule.

minLength1
last_updated: datetime

The timestamp of when the rule was last modified.

formatdate-time
ref: str

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

minLength1
version: str

The version of the rule.

action_parameters: Optional[RuleSetCacheControlRuleActionParameters]

The parameters configuring the rule’s action.

immutable: Optional[RuleSetCacheControlRuleActionParametersImmutable]

A cache-control directive configuration.

One of the following:
class RuleSetCacheControlRuleActionParametersImmutableSetDirective: …

Set the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

class RuleSetCacheControlRuleActionParametersImmutableRemoveDirective: …

Remove the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

max_age: Optional[RuleSetCacheControlRuleActionParametersMaxAge]

A cache-control directive configuration that accepts a duration value in seconds.

One of the following:
class RuleSetCacheControlRuleActionParametersMaxAgeSetDirective: …

Set the directive with a duration value in seconds.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
value: int

The duration value in seconds for the directive.

minimum0
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

class RuleSetCacheControlRuleActionParametersMaxAgeRemoveDirective: …

Remove the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

must_revalidate: Optional[RuleSetCacheControlRuleActionParametersMustRevalidate]

A cache-control directive configuration.

One of the following:
class RuleSetCacheControlRuleActionParametersMustRevalidateSetDirective: …

Set the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

class RuleSetCacheControlRuleActionParametersMustRevalidateRemoveDirective: …

Remove the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

must_understand: Optional[RuleSetCacheControlRuleActionParametersMustUnderstand]

A cache-control directive configuration.

One of the following:
class RuleSetCacheControlRuleActionParametersMustUnderstandSetDirective: …

Set the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

class RuleSetCacheControlRuleActionParametersMustUnderstandRemoveDirective: …

Remove the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

no_cache: Optional[RuleSetCacheControlRuleActionParametersNoCache]

A cache-control directive configuration that accepts optional qualifiers (header names).

One of the following:
class RuleSetCacheControlRuleActionParametersNoCacheSetDirective: …

Set the directive with optional qualifiers.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

qualifiers: Optional[List[str]]

Optional list of header names to qualify the directive (e.g., for “private” or “no-cache” directives).

class RuleSetCacheControlRuleActionParametersNoCacheRemoveDirective: …

Remove the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

no_store: Optional[RuleSetCacheControlRuleActionParametersNoStore]

A cache-control directive configuration.

One of the following:
class RuleSetCacheControlRuleActionParametersNoStoreSetDirective: …

Set the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

class RuleSetCacheControlRuleActionParametersNoStoreRemoveDirective: …

Remove the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

no_transform: Optional[RuleSetCacheControlRuleActionParametersNoTransform]

A cache-control directive configuration.

One of the following:
class RuleSetCacheControlRuleActionParametersNoTransformSetDirective: …

Set the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

class RuleSetCacheControlRuleActionParametersNoTransformRemoveDirective: …

Remove the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

private: Optional[RuleSetCacheControlRuleActionParametersPrivate]

A cache-control directive configuration that accepts optional qualifiers (header names).

One of the following:
class RuleSetCacheControlRuleActionParametersPrivateSetDirective: …

Set the directive with optional qualifiers.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

qualifiers: Optional[List[str]]

Optional list of header names to qualify the directive (e.g., for “private” or “no-cache” directives).

class RuleSetCacheControlRuleActionParametersPrivateRemoveDirective: …

Remove the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

proxy_revalidate: Optional[RuleSetCacheControlRuleActionParametersProxyRevalidate]

A cache-control directive configuration.

One of the following:
class RuleSetCacheControlRuleActionParametersProxyRevalidateSetDirective: …

Set the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

class RuleSetCacheControlRuleActionParametersProxyRevalidateRemoveDirective: …

Remove the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

public: Optional[RuleSetCacheControlRuleActionParametersPublic]

A cache-control directive configuration.

One of the following:
class RuleSetCacheControlRuleActionParametersPublicSetDirective: …

Set the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

class RuleSetCacheControlRuleActionParametersPublicRemoveDirective: …

Remove the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

s_maxage: Optional[RuleSetCacheControlRuleActionParametersSMaxage]

A cache-control directive configuration that accepts a duration value in seconds.

One of the following:
class RuleSetCacheControlRuleActionParametersSMaxageSetDirective: …

Set the directive with a duration value in seconds.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
value: int

The duration value in seconds for the directive.

minimum0
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

class RuleSetCacheControlRuleActionParametersSMaxageRemoveDirective: …

Remove the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

stale_if_error: Optional[RuleSetCacheControlRuleActionParametersStaleIfError]

A cache-control directive configuration that accepts a duration value in seconds.

One of the following:
class RuleSetCacheControlRuleActionParametersStaleIfErrorSetDirective: …

Set the directive with a duration value in seconds.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
value: int

The duration value in seconds for the directive.

minimum0
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

class RuleSetCacheControlRuleActionParametersStaleIfErrorRemoveDirective: …

Remove the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

stale_while_revalidate: Optional[RuleSetCacheControlRuleActionParametersStaleWhileRevalidate]

A cache-control directive configuration that accepts a duration value in seconds.

One of the following:
class RuleSetCacheControlRuleActionParametersStaleWhileRevalidateSetDirective: …

Set the directive with a duration value in seconds.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
value: int

The duration value in seconds for the directive.

minimum0
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

class RuleSetCacheControlRuleActionParametersStaleWhileRevalidateRemoveDirective: …

Remove the directive.

operation: Literal["set", "remove"]

The operation to perform on the cache-control directive.

One of the following:
"set"
"remove"
cloudflare_only: Optional[bool]

Whether the directive should only be applied to the Cloudflare CDN cache.

categories: Optional[List[str]]

The categories of the rule.

description: Optional[str]

An informative description of the rule.

exposed_credential_check: Optional[RuleSetCacheControlRuleExposedCredentialCheck]

Configuration for exposed credential checking.

password_expression: str

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

minLength1
username_expression: str

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

minLength1
logging: Optional[Logging]

An object configuring the rule’s logging behavior.

ratelimit: Optional[RuleSetCacheControlRuleRatelimit]

An object configuring the rule’s rate limit behavior.

characteristics: List[str]

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

period: int

Period in seconds over which the counter is being incremented.

minimum0
counting_expression: Optional[str]

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[int]

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

requests_per_period: Optional[int]

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

minimum1
requests_to_origin: Optional[bool]

Whether counting is only performed when an origin is reached.

score_per_period: Optional[int]

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

score_response_header_name: Optional[str]

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

minLength1
class RuleSetCacheSettingsRule: …
id: str
action: str
enabled: bool
expression: str
ref: str
class RuleSetCacheTagsRule: …
id: str

The unique ID of the rule.

action: Literal["set_cache_tags"]

The action to perform when the rule matches.

enabled: bool
expression: str

The expression defining which traffic will match the rule.

minLength1
last_updated: datetime

The timestamp of when the rule was last modified.

formatdate-time
ref: str

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

minLength1
version: str

The version of the rule.

action_parameters: Optional[RuleSetCacheTagsRuleActionParameters]

The parameters configuring the rule’s action.

One of the following:
class RuleSetCacheTagsRuleActionParametersAddCacheTagsValues: …

Add cache tags using a list of values.

operation: Literal["add", "remove", "set"]

The operation to perform on the cache tags.

One of the following:
"add"
"remove"
"set"
values: List[str]

A list of cache tag values.

class RuleSetCacheTagsRuleActionParametersAddCacheTagsExpression: …

Add cache tags using an expression.

expression: str

An expression that evaluates to an array of cache tag values.

minLength1
operation: Literal["add", "remove", "set"]

The operation to perform on the cache tags.

One of the following:
"add"
"remove"
"set"
class RuleSetCacheTagsRuleActionParametersRemoveCacheTagsValues: …

Remove cache tags using a list of values.

operation: Literal["add", "remove", "set"]

The operation to perform on the cache tags.

One of the following:
"add"
"remove"
"set"
values: List[str]

A list of cache tag values.

class RuleSetCacheTagsRuleActionParametersRemoveCacheTagsExpression: …

Remove cache tags using an expression.

expression: str

An expression that evaluates to an array of cache tag values.

minLength1
operation: Literal["add", "remove", "set"]

The operation to perform on the cache tags.

One of the following:
"add"
"remove"
"set"
class RuleSetCacheTagsRuleActionParametersSetCacheTagsValues: …

Set cache tags using a list of values.

operation: Literal["add", "remove", "set"]

The operation to perform on the cache tags.

One of the following:
"add"
"remove"
"set"
values: List[str]

A list of cache tag values.

class RuleSetCacheTagsRuleActionParametersSetCacheTagsExpression: …

Set cache tags using an expression.

expression: str

An expression that evaluates to an array of cache tag values.

minLength1
operation: Literal["add", "remove", "set"]

The operation to perform on the cache tags.

One of the following:
"add"
"remove"
"set"
categories: Optional[List[str]]

The categories of the rule.

description: Optional[str]

An informative description of the rule.

exposed_credential_check: Optional[RuleSetCacheTagsRuleExposedCredentialCheck]

Configuration for exposed credential checking.

password_expression: str

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

minLength1
username_expression: str

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

minLength1
logging: Optional[Logging]

An object configuring the rule’s logging behavior.

ratelimit: Optional[RuleSetCacheTagsRuleRatelimit]

An object configuring the rule’s rate limit behavior.

characteristics: List[str]

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

period: int

Period in seconds over which the counter is being incremented.

minimum0
counting_expression: Optional[str]

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[int]

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

requests_per_period: Optional[int]

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

minimum1
requests_to_origin: Optional[bool]

Whether counting is only performed when an origin is reached.

score_per_period: Optional[int]

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

score_response_header_name: Optional[str]

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

minLength1
class RuleSetConfigurationRule: …
id: str
action: str
enabled: bool
expression: str
ref: str
class RuleSkipRule: …
id: str
action: str
enabled: bool
expression: str
ref: str
class RuleTransformResponseHTMLRule: …
id: str

The unique ID of the rule.

action: Literal["transform_response_html"]

The action to perform when the rule matches.

enabled: bool
expression: str

The expression defining which traffic will match the rule.

minLength1
last_updated: datetime

The timestamp of when the rule was last modified.

formatdate-time
ref: str

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

minLength1
version: str

The version of the rule.

action_parameters: Optional[RuleTransformResponseHTMLRuleActionParameters]

The parameters configuring the rule’s action.

categories: Optional[List[str]]

The categories of the rule.

description: Optional[str]

An informative description of the rule.

exposed_credential_check: Optional[RuleTransformResponseHTMLRuleExposedCredentialCheck]

Configuration for exposed credential checking.

password_expression: str

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

minLength1
username_expression: str

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

minLength1
logging: Optional[Logging]

An object configuring the rule’s logging behavior.

ratelimit: Optional[RuleTransformResponseHTMLRuleRatelimit]

An object configuring the rule’s rate limit behavior.

characteristics: List[str]

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

period: int

Period in seconds over which the counter is being incremented.

minimum0
counting_expression: Optional[str]

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[int]

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

requests_per_period: Optional[int]

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

minimum1
requests_to_origin: Optional[bool]

Whether counting is only performed when an origin is reached.

score_per_period: Optional[int]

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

score_response_header_name: Optional[str]

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

minLength1
version: str

The version of the ruleset.

description: Optional[str]

An informative description of the ruleset.