--- title: Create an account or zone ruleset rule --- [Skip to content](#_top) [API Reference](https://developers.cloudflare.com/api/python) [Rulesets](https://developers.cloudflare.com/api/python/resources/rulesets) [Rules](https://developers.cloudflare.com/api/python/resources/rulesets/subresources/rules) Copy Markdown Open in **Claude**Open in **ChatGPT**Open in **Cursor** --- **Copy Markdown****View as Markdown** # Create an account or zone ruleset rule rulesets.rules.create(strruleset\_id, RuleCreateParams\*\*kwargs) -> [RuleCreateResponse]() POST/{accounts\_or\_zones}/{account\_or\_zone\_id}/rulesets/{ruleset\_id}/rules Adds a new rule to an account or zone ruleset. The rule will be added to the end of the existing list of rules in the ruleset by default. ##### 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 Write``Magic Firewall Write``L4 DDoS Managed Ruleset Write``Transform Rules Write``Select Configuration Write``Account WAF Write``Account Rulesets Write``Logs Write` ##### ParametersExpand Collapse ruleset\_id: str The unique ID of the ruleset. [Link to this property](<#(resource)%20rulesets.rules%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20ruleset_id%20%3E%20(schema)>) account\_id: Optional\[str] The Account ID to use for this endpoint. Mutually exclusive with the Zone ID. [Link to this property](<#(resource)%20rulesets.rules%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20account_id%20%3E%20(schema)>) zone\_id: Optional\[str] The Zone ID to use for this endpoint. Mutually exclusive with the Account ID. [Link to this property](<#(resource)%20rulesets.rules%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20zone_id%20%3E%20(schema)>) dry\_run: Optional\[[bool]()] Validates the request without persisting changes when set to `true`. Responses that normally return 200 return `result: null`; endpoints that normally return 204 continue to return 204. [Link to this property](<#(resource)%20rulesets.rules%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20dry_run%20%3E%20(schema)>) id: Optional\[str] The unique ID of the rule. [Link to this property](<#(resource)%20rulesets.rules%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20id%20%3E%20(schema)>) action: Optional\[Literal\["block"]] The action to perform when the rule matches. [Link to this property](<#(resource)%20rulesets.rules%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20action%20%3E%20(schema)>)
action\_parameters: Optional\[BlockRuleActionParameters] The parameters configuring the rule’s action.
response: Optional\[BlockRuleActionParametersResponse] The response to show when the block is applied. content: str The content to return. minLength1 Link to this property content\_type: str The type of the content to return. minLength1 Link to this property status\_code: int The status code to return. maximum499 minimum400 Link to this property
Link to this property
[Link to this property](<#(resource)%20rulesets.rules%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20action_parameters%20%3E%20(schema)>) description: Optional\[str] An informative description of the rule. [Link to this property](<#(resource)%20rulesets.rules%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20description%20%3E%20(schema)>) enabled: Optional\[[bool]()] Whether the rule should be executed. [Link to this property](<#(resource)%20rulesets.rules%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20enabled%20%3E%20(schema)>)
exposed\_credential\_check: Optional\[BlockRuleExposedCredentialCheck] Configuration for exposed credential checking. password\_expression: str An expression that selects the password used in the credentials check. minLength1 Link to this property username\_expression: str An expression that selects the user ID used in the credentials check. minLength1 Link to this property
[Link to this property](<#(resource)%20rulesets.rules%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20exposed_credential_check%20%3E%20(schema)>) expression: Optional\[str] The expression defining which traffic will match the rule. minLength1 [Link to this property](<#(resource)%20rulesets.rules%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20expression%20%3E%20(schema)>)
logging: Optional\[LoggingParam] An object configuring the rule’s logging behavior. enabled: bool Whether to generate a log when the rule matches. Link to this property
[Link to this property](<#(resource)%20rulesets.rules%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20logging%20%3E%20(schema)>)
position: Optional\[BlockRulePosition] An object configuring where the rule will be placed. One of the following:
class BlockRulePositionBeforePosition: … An object configuring where the rule will be placed. before: Optional\[str] The ID of another rule to place the rule before. An empty value causes the rule to be placed at the top. Link to this property
Link to this property
class BlockRulePositionAfterPosition: … An object configuring where the rule will be placed. after: Optional\[str] The ID of another rule to place the rule after. An empty value causes the rule to be placed at the bottom. Link to this property
Link to this property
class BlockRulePositionIndexPosition: … An object configuring where the rule will be placed. index: Optional\[int] An index at which to place the rule, where index 1 is the first rule. minimum1 Link to this property
Link to this property
[Link to this property](<#(resource)%20rulesets.rules%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20position%20%3E%20(schema)>)
ratelimit: Optional\[BlockRuleRatelimit] An object configuring the rule’s rate limit behavior. characteristics: Sequence\[str] Characteristics of the request on which the rate limit counter will be incremented. Link to this property period: int Period in seconds over which the counter is being incremented. minimum0 Link to this property 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 Link to this property mitigation\_timeout: Optional\[int] Period of time in seconds after which the action will be disabled following its first execution. Link to this property requests\_per\_period: Optional\[int] The threshold of requests per period after which the action will be executed for the first time. minimum1 Link to this property requests\_to\_origin: Optional\[bool] Whether counting is only performed when an origin is reached. Link to this property score\_per\_period: Optional\[int] The score threshold per period for which the action will be executed the first time. Link to this property 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 Link to this property
[Link to this property](<#(resource)%20rulesets.rules%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20ratelimit%20%3E%20(schema)>) ref: Optional\[str] The reference of the rule (the rule’s ID by default). minLength1 [Link to this property](<#(resource)%20rulesets.rules%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20ref%20%3E%20(schema)>) ##### ReturnsExpand Collapse
RuleCreateResponse A result. One of the following:
class Ruleset: … A ruleset object. id: str The unique ID of the ruleset. Link to this property
kind: Kind The kind of the ruleset. One of the following: "managed" Link to this property "custom" Link to this property "root" Link to this property "zone" Link to this property
Link to this property last\_updated: datetime The timestamp of when the ruleset was last modified. formatdate-time Link to this property name: str The human-readable name of the ruleset. minLength1 Link to this property
phase: Phase The phase of the ruleset. One of the following: "ddos\_l4" Link to this property "ddos\_l7" Link to this property "http\_config\_settings" Link to this property "http\_custom\_errors" Link to this property "http\_log\_custom\_fields" Link to this property "http\_ratelimit" Link to this property "http\_request\_cache\_settings" Link to this property "http\_request\_dynamic\_redirect" Link to this property "http\_request\_firewall\_custom" Link to this property "http\_request\_firewall\_managed" Link to this property "http\_request\_late\_transform" Link to this property "http\_request\_origin" Link to this property "http\_request\_redirect" Link to this property "http\_request\_sanitize" Link to this property "http\_request\_sbfm" Link to this property "http\_request\_transform" Link to this property "http\_response\_cache\_settings" Link to this property "http\_response\_compression" Link to this property "http\_response\_firewall\_managed" Link to this property "http\_response\_headers\_transform" Link to this property "magic\_transit" Link to this property "magic\_transit\_ids\_managed" Link to this property "magic\_transit\_managed" Link to this property "magic\_transit\_ratelimit" Link to this property
Link to this property
rules: List\[RulesetRule] The list of rules in the ruleset. One of the following:
class RulesetRuleBlockRule: … id: str Link to this property action: str Link to this property enabled: bool Link to this property expression: str Link to this property ref: str Link to this property
Link to this property
class RulesetRuleChallengeRule: … id: str The unique ID of the rule. Link to this property action: Literal\["challenge"] The action to perform when the rule matches. Link to this property enabled: bool Whether the rule should be executed. Link to this property expression: str The expression defining which traffic will match the rule. minLength1 Link to this property last\_updated: datetime The timestamp of when the rule was last modified. formatdate-time Link to this property ref: str The reference of the rule (the rule’s ID by default). minLength1 Link to this property version: str The version of the rule. Link to this property action\_parameters: Optional\[object] The parameters configuring the rule’s action. Link to this property categories: Optional\[List\[str]] The categories of the rule. Link to this property description: Optional\[str] An informative description of the rule. Link to this property
exposed\_credential\_check: Optional\[RulesetRuleChallengeRuleExposedCredentialCheck] Configuration for exposed credential checking. password\_expression: str An expression that selects the password used in the credentials check. minLength1 Link to this property username\_expression: str An expression that selects the user ID used in the credentials check. minLength1 Link to this property
Link to this property
logging: Optional\[Logging] An object configuring the rule’s logging behavior. enabled: bool Whether to generate a log when the rule matches. Link to this property
Link to this property
ratelimit: Optional\[RulesetRuleChallengeRuleRatelimit] 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. Link to this property period: int Period in seconds over which the counter is being incremented. minimum0 Link to this property 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 Link to this property mitigation\_timeout: Optional\[int] Period of time in seconds after which the action will be disabled following its first execution. Link to this property requests\_per\_period: Optional\[int] The threshold of requests per period after which the action will be executed for the first time. minimum1 Link to this property requests\_to\_origin: Optional\[bool] Whether counting is only performed when an origin is reached. Link to this property score\_per\_period: Optional\[int] The score threshold per period for which the action will be executed the first time. Link to this property 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 Link to this property
Link to this property
Link to this property
class RulesetRuleResponseCompressionRule: … id: str Link to this property action: str Link to this property enabled: bool Link to this property expression: str Link to this property ref: str Link to this property
Link to this property
class RulesetRuleDDoSDynamicRule: … id: str Link to this property action: str Link to this property enabled: bool Link to this property expression: str Link to this property ref: str Link to this property
Link to this property
class RulesetRuleExecuteRule: … id: str Link to this property action: str Link to this property enabled: bool Link to this property expression: str Link to this property ref: str Link to this property
Link to this property
class RulesetRuleForceConnectionCloseRule: … id: str Link to this property action: str Link to this property enabled: bool Link to this property expression: str Link to this property ref: str Link to this property
Link to this property
class RulesetRuleJavaScriptChallengeRule: … id: str The unique ID of the rule. Link to this property action: Literal\["js\_challenge"] The action to perform when the rule matches. Link to this property enabled: bool Whether the rule should be executed. Link to this property expression: str The expression defining which traffic will match the rule. minLength1 Link to this property last\_updated: datetime The timestamp of when the rule was last modified. formatdate-time Link to this property ref: str The reference of the rule (the rule’s ID by default). minLength1 Link to this property version: str The version of the rule. Link to this property action\_parameters: Optional\[object] The parameters configuring the rule’s action. Link to this property categories: Optional\[List\[str]] The categories of the rule. Link to this property description: Optional\[str] An informative description of the rule. Link to this property
exposed\_credential\_check: Optional\[RulesetRuleJavaScriptChallengeRuleExposedCredentialCheck] Configuration for exposed credential checking. password\_expression: str An expression that selects the password used in the credentials check. minLength1 Link to this property username\_expression: str An expression that selects the user ID used in the credentials check. minLength1 Link to this property
Link to this property
logging: Optional\[Logging] An object configuring the rule’s logging behavior. enabled: bool Whether to generate a log when the rule matches. Link to this property
Link to this property
ratelimit: Optional\[RulesetRuleJavaScriptChallengeRuleRatelimit] 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. Link to this property period: int Period in seconds over which the counter is being incremented. minimum0 Link to this property 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 Link to this property mitigation\_timeout: Optional\[int] Period of time in seconds after which the action will be disabled following its first execution. Link to this property requests\_per\_period: Optional\[int] The threshold of requests per period after which the action will be executed for the first time. minimum1 Link to this property requests\_to\_origin: Optional\[bool] Whether counting is only performed when an origin is reached. Link to this property score\_per\_period: Optional\[int] The score threshold per period for which the action will be executed the first time. Link to this property 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 Link to this property
Link to this property
Link to this property
class RulesetRuleLogRule: … id: str Link to this property action: str Link to this property enabled: bool Link to this property expression: str Link to this property ref: str Link to this property
Link to this property
class RulesetRuleLogCustomFieldRule: … id: str Link to this property action: str Link to this property enabled: bool Link to this property expression: str Link to this property ref: str Link to this property
Link to this property
class RulesetRuleManagedChallengeRule: … id: str Link to this property action: str Link to this property enabled: bool Link to this property expression: str Link to this property ref: str Link to this property
Link to this property
class RulesetRuleRedirectRule: … id: str Link to this property action: str Link to this property enabled: bool Link to this property expression: str Link to this property ref: str Link to this property
Link to this property
class RulesetRuleRewriteRule: … id: str Link to this property action: str Link to this property enabled: bool Link to this property expression: str Link to this property ref: str Link to this property
Link to this property
class RulesetRuleRouteRule: … id: str Link to this property action: str Link to this property enabled: bool Link to this property expression: str Link to this property ref: str Link to this property
Link to this property
class RulesetRuleScoreRule: … id: str Link to this property action: str Link to this property enabled: bool Link to this property expression: str Link to this property ref: str Link to this property
Link to this property
class RulesetRuleServeErrorRule: … id: str Link to this property action: str Link to this property enabled: bool Link to this property expression: str Link to this property ref: str Link to this property
Link to this property
class RulesetRuleSetCacheControlRule: … id: str The unique ID of the rule. Link to this property action: Literal\["set\_cache\_control"] The action to perform when the rule matches. Link to this property enabled: bool Link to this property expression: str The expression defining which traffic will match the rule. minLength1 Link to this property last\_updated: datetime The timestamp of when the rule was last modified. formatdate-time Link to this property ref: str The reference of the rule (the rule’s ID by default). minLength1 Link to this property version: str The version of the rule. Link to this property
action\_parameters: Optional\[RulesetRuleSetCacheControlRuleActionParameters] The parameters configuring the rule’s action.
immutable: Optional\[RulesetRuleSetCacheControlRuleActionParametersImmutable] A cache-control directive configuration. One of the following:
class RulesetRuleSetCacheControlRuleActionParametersImmutableSetDirective: … Set the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
class RulesetRuleSetCacheControlRuleActionParametersImmutableRemoveDirective: … Remove the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
Link to this property
max\_age: Optional\[RulesetRuleSetCacheControlRuleActionParametersMaxAge] A cache-control directive configuration that accepts a duration value in seconds. One of the following:
class RulesetRuleSetCacheControlRuleActionParametersMaxAgeSetDirective: … 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" Link to this property "remove" Link to this property
Link to this property value: int The duration value in seconds for the directive. minimum0 Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
class RulesetRuleSetCacheControlRuleActionParametersMaxAgeRemoveDirective: … Remove the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
Link to this property
must\_revalidate: Optional\[RulesetRuleSetCacheControlRuleActionParametersMustRevalidate] A cache-control directive configuration. One of the following:
class RulesetRuleSetCacheControlRuleActionParametersMustRevalidateSetDirective: … Set the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
class RulesetRuleSetCacheControlRuleActionParametersMustRevalidateRemoveDirective: … Remove the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
Link to this property
must\_understand: Optional\[RulesetRuleSetCacheControlRuleActionParametersMustUnderstand] A cache-control directive configuration. One of the following:
class RulesetRuleSetCacheControlRuleActionParametersMustUnderstandSetDirective: … Set the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
class RulesetRuleSetCacheControlRuleActionParametersMustUnderstandRemoveDirective: … Remove the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
Link to this property
no\_cache: Optional\[RulesetRuleSetCacheControlRuleActionParametersNoCache] A cache-control directive configuration that accepts optional qualifiers (header names). One of the following:
class RulesetRuleSetCacheControlRuleActionParametersNoCacheSetDirective: … Set the directive with optional qualifiers.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property qualifiers: Optional\[List\[str]] Optional list of header names to qualify the directive (e.g., for “private” or “no-cache” directives). Link to this property
Link to this property
class RulesetRuleSetCacheControlRuleActionParametersNoCacheRemoveDirective: … Remove the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
Link to this property
no\_store: Optional\[RulesetRuleSetCacheControlRuleActionParametersNoStore] A cache-control directive configuration. One of the following:
class RulesetRuleSetCacheControlRuleActionParametersNoStoreSetDirective: … Set the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
class RulesetRuleSetCacheControlRuleActionParametersNoStoreRemoveDirective: … Remove the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
Link to this property
no\_transform: Optional\[RulesetRuleSetCacheControlRuleActionParametersNoTransform] A cache-control directive configuration. One of the following:
class RulesetRuleSetCacheControlRuleActionParametersNoTransformSetDirective: … Set the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
class RulesetRuleSetCacheControlRuleActionParametersNoTransformRemoveDirective: … Remove the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
Link to this property
private: Optional\[RulesetRuleSetCacheControlRuleActionParametersPrivate] A cache-control directive configuration that accepts optional qualifiers (header names). One of the following:
class RulesetRuleSetCacheControlRuleActionParametersPrivateSetDirective: … Set the directive with optional qualifiers.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property qualifiers: Optional\[List\[str]] Optional list of header names to qualify the directive (e.g., for “private” or “no-cache” directives). Link to this property
Link to this property
class RulesetRuleSetCacheControlRuleActionParametersPrivateRemoveDirective: … Remove the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
Link to this property
proxy\_revalidate: Optional\[RulesetRuleSetCacheControlRuleActionParametersProxyRevalidate] A cache-control directive configuration. One of the following:
class RulesetRuleSetCacheControlRuleActionParametersProxyRevalidateSetDirective: … Set the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
class RulesetRuleSetCacheControlRuleActionParametersProxyRevalidateRemoveDirective: … Remove the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
Link to this property
public: Optional\[RulesetRuleSetCacheControlRuleActionParametersPublic] A cache-control directive configuration. One of the following:
class RulesetRuleSetCacheControlRuleActionParametersPublicSetDirective: … Set the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
class RulesetRuleSetCacheControlRuleActionParametersPublicRemoveDirective: … Remove the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
Link to this property
s\_maxage: Optional\[RulesetRuleSetCacheControlRuleActionParametersSMaxage] A cache-control directive configuration that accepts a duration value in seconds. One of the following:
class RulesetRuleSetCacheControlRuleActionParametersSMaxageSetDirective: … 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" Link to this property "remove" Link to this property
Link to this property value: int The duration value in seconds for the directive. minimum0 Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
class RulesetRuleSetCacheControlRuleActionParametersSMaxageRemoveDirective: … Remove the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
Link to this property
stale\_if\_error: Optional\[RulesetRuleSetCacheControlRuleActionParametersStaleIfError] A cache-control directive configuration that accepts a duration value in seconds. One of the following:
class RulesetRuleSetCacheControlRuleActionParametersStaleIfErrorSetDirective: … 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" Link to this property "remove" Link to this property
Link to this property value: int The duration value in seconds for the directive. minimum0 Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
class RulesetRuleSetCacheControlRuleActionParametersStaleIfErrorRemoveDirective: … Remove the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
Link to this property
stale\_while\_revalidate: Optional\[RulesetRuleSetCacheControlRuleActionParametersStaleWhileRevalidate] A cache-control directive configuration that accepts a duration value in seconds. One of the following:
class RulesetRuleSetCacheControlRuleActionParametersStaleWhileRevalidateSetDirective: … 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" Link to this property "remove" Link to this property
Link to this property value: int The duration value in seconds for the directive. minimum0 Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
class RulesetRuleSetCacheControlRuleActionParametersStaleWhileRevalidateRemoveDirective: … Remove the directive.
operation: Literal\["set", "remove"] The operation to perform on the cache-control directive. One of the following: "set" Link to this property "remove" Link to this property
Link to this property cloudflare\_only: Optional\[bool] Whether the directive should only be applied to the Cloudflare CDN cache. Link to this property
Link to this property
Link to this property
Link to this property categories: Optional\[List\[str]] The categories of the rule. Link to this property description: Optional\[str] An informative description of the rule. Link to this property
exposed\_credential\_check: Optional\[RulesetRuleSetCacheControlRuleExposedCredentialCheck] Configuration for exposed credential checking. password\_expression: str An expression that selects the password used in the credentials check. minLength1 Link to this property username\_expression: str An expression that selects the user ID used in the credentials check. minLength1 Link to this property
Link to this property
logging: Optional\[Logging] An object configuring the rule’s logging behavior. enabled: bool Whether to generate a log when the rule matches. Link to this property
Link to this property
ratelimit: Optional\[RulesetRuleSetCacheControlRuleRatelimit] 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. Link to this property period: int Period in seconds over which the counter is being incremented. minimum0 Link to this property 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 Link to this property mitigation\_timeout: Optional\[int] Period of time in seconds after which the action will be disabled following its first execution. Link to this property requests\_per\_period: Optional\[int] The threshold of requests per period after which the action will be executed for the first time. minimum1 Link to this property requests\_to\_origin: Optional\[bool] Whether counting is only performed when an origin is reached. Link to this property score\_per\_period: Optional\[int] The score threshold per period for which the action will be executed the first time. Link to this property 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 Link to this property
Link to this property
Link to this property
class RulesetRuleSetCacheSettingsRule: … id: str Link to this property action: str Link to this property enabled: bool Link to this property expression: str Link to this property ref: str Link to this property
Link to this property
class RulesetRuleSetCacheTagsRule: … id: str The unique ID of the rule. Link to this property action: Literal\["set\_cache\_tags"] The action to perform when the rule matches. Link to this property enabled: bool Link to this property expression: str The expression defining which traffic will match the rule. minLength1 Link to this property last\_updated: datetime The timestamp of when the rule was last modified. formatdate-time Link to this property ref: str The reference of the rule (the rule’s ID by default). minLength1 Link to this property version: str The version of the rule. Link to this property
action\_parameters: Optional\[RulesetRuleSetCacheTagsRuleActionParameters] The parameters configuring the rule’s action. One of the following:
class RulesetRuleSetCacheTagsRuleActionParametersAddCacheTagsValues: … 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" Link to this property "remove" Link to this property "set" Link to this property
Link to this property values: List\[str] A list of cache tag values. Link to this property
Link to this property
class RulesetRuleSetCacheTagsRuleActionParametersAddCacheTagsExpression: … Add cache tags using an expression. expression: str An expression that evaluates to an array of cache tag values. minLength1 Link to this property
operation: Literal\["add", "remove", "set"] The operation to perform on the cache tags. One of the following: "add" Link to this property "remove" Link to this property "set" Link to this property
Link to this property
Link to this property
class RulesetRuleSetCacheTagsRuleActionParametersRemoveCacheTagsValues: … 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" Link to this property "remove" Link to this property "set" Link to this property
Link to this property values: List\[str] A list of cache tag values. Link to this property
Link to this property
class RulesetRuleSetCacheTagsRuleActionParametersRemoveCacheTagsExpression: … Remove cache tags using an expression. expression: str An expression that evaluates to an array of cache tag values. minLength1 Link to this property
operation: Literal\["add", "remove", "set"] The operation to perform on the cache tags. One of the following: "add" Link to this property "remove" Link to this property "set" Link to this property
Link to this property
Link to this property
class RulesetRuleSetCacheTagsRuleActionParametersSetCacheTagsValues: … 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" Link to this property "remove" Link to this property "set" Link to this property
Link to this property values: List\[str] A list of cache tag values. Link to this property
Link to this property
class RulesetRuleSetCacheTagsRuleActionParametersSetCacheTagsExpression: … Set cache tags using an expression. expression: str An expression that evaluates to an array of cache tag values. minLength1 Link to this property
operation: Literal\["add", "remove", "set"] The operation to perform on the cache tags. One of the following: "add" Link to this property "remove" Link to this property "set" Link to this property
Link to this property
Link to this property
Link to this property categories: Optional\[List\[str]] The categories of the rule. Link to this property description: Optional\[str] An informative description of the rule. Link to this property
exposed\_credential\_check: Optional\[RulesetRuleSetCacheTagsRuleExposedCredentialCheck] Configuration for exposed credential checking. password\_expression: str An expression that selects the password used in the credentials check. minLength1 Link to this property username\_expression: str An expression that selects the user ID used in the credentials check. minLength1 Link to this property
Link to this property
logging: Optional\[Logging] An object configuring the rule’s logging behavior. enabled: bool Whether to generate a log when the rule matches. Link to this property
Link to this property
ratelimit: Optional\[RulesetRuleSetCacheTagsRuleRatelimit] 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. Link to this property period: int Period in seconds over which the counter is being incremented. minimum0 Link to this property 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 Link to this property mitigation\_timeout: Optional\[int] Period of time in seconds after which the action will be disabled following its first execution. Link to this property requests\_per\_period: Optional\[int] The threshold of requests per period after which the action will be executed for the first time. minimum1 Link to this property requests\_to\_origin: Optional\[bool] Whether counting is only performed when an origin is reached. Link to this property score\_per\_period: Optional\[int] The score threshold per period for which the action will be executed the first time. Link to this property 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 Link to this property
Link to this property
Link to this property
class RulesetRuleSetConfigurationRule: … id: str Link to this property action: str Link to this property enabled: bool Link to this property expression: str Link to this property ref: str Link to this property
Link to this property
class RulesetRuleSkipRule: … id: str Link to this property action: str Link to this property enabled: bool Link to this property expression: str Link to this property ref: str Link to this property
Link to this property
class RulesetRuleTransformResponseHTMLRule: … id: str The unique ID of the rule. Link to this property action: Literal\["transform\_response\_html"] The action to perform when the rule matches. Link to this property enabled: bool Link to this property expression: str The expression defining which traffic will match the rule. minLength1 Link to this property last\_updated: datetime The timestamp of when the rule was last modified. formatdate-time Link to this property ref: str The reference of the rule (the rule’s ID by default). minLength1 Link to this property version: str The version of the rule. Link to this property
action\_parameters: Optional\[RulesetRuleTransformResponseHTMLRuleActionParameters] The parameters configuring the rule’s action. link\_maze: object Enables the link maze transformation on the response. Link to this property
Link to this property categories: Optional\[List\[str]] The categories of the rule. Link to this property description: Optional\[str] An informative description of the rule. Link to this property
exposed\_credential\_check: Optional\[RulesetRuleTransformResponseHTMLRuleExposedCredentialCheck] Configuration for exposed credential checking. password\_expression: str An expression that selects the password used in the credentials check. minLength1 Link to this property username\_expression: str An expression that selects the user ID used in the credentials check. minLength1 Link to this property
Link to this property
logging: Optional\[Logging] An object configuring the rule’s logging behavior. enabled: bool Whether to generate a log when the rule matches. Link to this property
Link to this property
ratelimit: Optional\[RulesetRuleTransformResponseHTMLRuleRatelimit] 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. Link to this property period: int Period in seconds over which the counter is being incremented. minimum0 Link to this property 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 Link to this property mitigation\_timeout: Optional\[int] Period of time in seconds after which the action will be disabled following its first execution. Link to this property requests\_per\_period: Optional\[int] The threshold of requests per period after which the action will be executed for the first time. minimum1 Link to this property requests\_to\_origin: Optional\[bool] Whether counting is only performed when an origin is reached. Link to this property score\_per\_period: Optional\[int] The score threshold per period for which the action will be executed the first time. Link to this property 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 Link to this property
Link to this property
Link to this property
Link to this property version: str The version of the ruleset. Link to this property description: Optional\[str] An informative description of the ruleset. Link to this property
Link to this property Optional\[object] Returned when dry\_run is true. Link to this property
[Link to this property](<#(resource)%20rulesets.rules%20%3E%20(model)%20rule_create_response%20%3E%20(schema)>) ### Create an account or zone ruleset rule Python HTTPTypeScriptPythonGoTerraform ``` import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) rule = client.rulesets.rules.create( ruleset_id="2f2feab2026849078ba485f918791bdc", account_id="account_id", ) print(rule) ``` 200 example ``` { "errors": [ { "message": "something bad happened", "code": 10000, "source": { "pointer": "/rules/0/action" } } ], "messages": [ { "message": "something bad happened", "code": 10000, "source": { "pointer": "/rules/0/action" } } ], "result": { "id": "2f2feab2026849078ba485f918791bdc", "kind": "root", "last_updated": "2000-01-01T00:00:00Z", "name": "My ruleset", "phase": "http_request_firewall_custom", "rules": [ { "last_updated": "2000-01-01T00:00:00Z", "version": "1", "id": "id", "action": "action", "action_parameters": { "response": { "content": "{\n \"success\": false,\n \"error\": \"you have been blocked\"\n}", "content_type": "application/json", "status_code": 400 } }, "categories": [ "directory-traversal" ], "description": "Block the request.", "enabled": true, "exposed_credential_check": { "password_expression": "url_decode(http.request.body.form[\\\"password\\\"][0])", "username_expression": "url_decode(http.request.body.form[\\\"username\\\"][0])" }, "expression": "expression", "logging": { "enabled": true }, "ratelimit": { "characteristics": [ "cf.colo.id" ], "period": 60, "counting_expression": "http.request.body.raw eq \"abcd\"", "mitigation_timeout": 600, "requests_per_period": 1000, "requests_to_origin": true, "score_per_period": 400, "score_response_header_name": "my-score" }, "ref": "ref" } ], "version": "1", "description": "A description for my ruleset." }, "success": true } ``` ##### Returns Examples 200 example ``` { "errors": [ { "message": "something bad happened", "code": 10000, "source": { "pointer": "/rules/0/action" } } ], "messages": [ { "message": "something bad happened", "code": 10000, "source": { "pointer": "/rules/0/action" } } ], "result": { "id": "2f2feab2026849078ba485f918791bdc", "kind": "root", "last_updated": "2000-01-01T00:00:00Z", "name": "My ruleset", "phase": "http_request_firewall_custom", "rules": [ { "last_updated": "2000-01-01T00:00:00Z", "version": "1", "id": "id", "action": "action", "action_parameters": { "response": { "content": "{\n \"success\": false,\n \"error\": \"you have been blocked\"\n}", "content_type": "application/json", "status_code": 400 } }, "categories": [ "directory-traversal" ], "description": "Block the request.", "enabled": true, "exposed_credential_check": { "password_expression": "url_decode(http.request.body.form[\\\"password\\\"][0])", "username_expression": "url_decode(http.request.body.form[\\\"username\\\"][0])" }, "expression": "expression", "logging": { "enabled": true }, "ratelimit": { "characteristics": [ "cf.colo.id" ], "period": 60, "counting_expression": "http.request.body.raw eq \"abcd\"", "mitigation_timeout": 600, "requests_per_period": 1000, "requests_to_origin": true, "score_per_period": 400, "score_response_header_name": "my-score" }, "ref": "ref" } ], "version": "1", "description": "A description for my ruleset." }, "success": true } ```