Create an account or zone ruleset rule
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.
Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYYAPI Email + API Key
The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.
X-Auth-Email: user@example.comThe previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.
X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194Accepted Permissions (at least one required)
Mass URL Redirects WriteMagic Firewall WriteL4 DDoS Managed Ruleset WriteTransform Rules WriteSelect Configuration WriteAccount WAF WriteAccount Rulesets WriteLogs WritePath ParametersExpand Collapse
Query ParametersExpand Collapse
Body ParametersJSONExpand Collapse
body: BlockRule { last_updated, version, id, 10 more } or object { last_updated, version, id, 11 more } or CompressResponseRule { last_updated, version, id, 10 more } or 18 more
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
ChallengeRule object { last_updated, version, id, 11 more }
exposed_credential_check: optional object { password_expression, username_expression } Configuration for exposed credential checking.
Configuration for exposed credential checking.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
ratelimit: optional object { characteristics, period, counting_expression, 5 more } An object configuring the rule’s rate limit behavior.
An object configuring the rule’s rate limit behavior.
Characteristics of the request on which the rate limit counter will be incremented.
An expression that defines when the rate limit counter should be incremented. It defaults to the same as the rule’s expression.
Period of time in seconds after which the action will be disabled following its first execution.
The threshold of requests per period after which the action will be executed for the first time.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
JavaScriptChallengeRule object { last_updated, version, id, 11 more }
exposed_credential_check: optional object { password_expression, username_expression } Configuration for exposed credential checking.
Configuration for exposed credential checking.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
ratelimit: optional object { characteristics, period, counting_expression, 5 more } An object configuring the rule’s rate limit behavior.
An object configuring the rule’s rate limit behavior.
Characteristics of the request on which the rate limit counter will be incremented.
An expression that defines when the rate limit counter should be incremented. It defaults to the same as the rule’s expression.
Period of time in seconds after which the action will be disabled following its first execution.
The threshold of requests per period after which the action will be executed for the first time.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
SetCacheControlRule object { last_updated, version, id, 11 more }
action_parameters: optional object { immutable, "max-age", "must-revalidate", 10 more } The parameters configuring the rule’s action.
The parameters configuring the rule’s action.
immutable: optional object { operation, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
"max-age": optional object { operation, value, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration that accepts a duration value in seconds.
A cache-control directive configuration that accepts a duration value in seconds.
"must-revalidate": optional object { operation, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
"must-understand": optional object { operation, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
"no-cache": optional object { operation, cloudflare_only, qualifiers } or object { operation, cloudflare_only } A cache-control directive configuration that accepts optional qualifiers (header names).
A cache-control directive configuration that accepts optional qualifiers (header names).
"no-store": optional object { operation, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
"no-transform": optional object { operation, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
private: optional object { operation, cloudflare_only, qualifiers } or object { operation, cloudflare_only } A cache-control directive configuration that accepts optional qualifiers (header names).
A cache-control directive configuration that accepts optional qualifiers (header names).
"proxy-revalidate": optional object { operation, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
public: optional object { operation, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
"s-maxage": optional object { operation, value, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration that accepts a duration value in seconds.
A cache-control directive configuration that accepts a duration value in seconds.
"stale-if-error": optional object { operation, value, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration that accepts a duration value in seconds.
A cache-control directive configuration that accepts a duration value in seconds.
"stale-while-revalidate": optional object { operation, value, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration that accepts a duration value in seconds.
A cache-control directive configuration that accepts a duration value in seconds.
exposed_credential_check: optional object { password_expression, username_expression } Configuration for exposed credential checking.
Configuration for exposed credential checking.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
ratelimit: optional object { characteristics, period, counting_expression, 5 more } An object configuring the rule’s rate limit behavior.
An object configuring the rule’s rate limit behavior.
Characteristics of the request on which the rate limit counter will be incremented.
An expression that defines when the rate limit counter should be incremented. It defaults to the same as the rule’s expression.
Period of time in seconds after which the action will be disabled following its first execution.
The threshold of requests per period after which the action will be executed for the first time.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
SetCacheTagsRule object { last_updated, version, id, 11 more }
action_parameters: optional object { operation, values } or object { expression, operation } or object { operation, values } or 3 moreThe parameters configuring the rule’s action.
The parameters configuring the rule’s action.
exposed_credential_check: optional object { password_expression, username_expression } Configuration for exposed credential checking.
Configuration for exposed credential checking.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
ratelimit: optional object { characteristics, period, counting_expression, 5 more } An object configuring the rule’s rate limit behavior.
An object configuring the rule’s rate limit behavior.
Characteristics of the request on which the rate limit counter will be incremented.
An expression that defines when the rate limit counter should be incremented. It defaults to the same as the rule’s expression.
Period of time in seconds after which the action will be disabled following its first execution.
The threshold of requests per period after which the action will be executed for the first time.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
TransformResponseHTMLRule object { last_updated, version, id, 11 more }
exposed_credential_check: optional object { password_expression, username_expression } Configuration for exposed credential checking.
Configuration for exposed credential checking.
position: optional object { before } or object { after } or object { index } An object configuring where the rule will be placed.
An object configuring where the rule will be placed.
ratelimit: optional object { characteristics, period, counting_expression, 5 more } An object configuring the rule’s rate limit behavior.
An object configuring the rule’s rate limit behavior.
Characteristics of the request on which the rate limit counter will be incremented.
An expression that defines when the rate limit counter should be incremented. It defaults to the same as the rule’s expression.
Period of time in seconds after which the action will be disabled following its first execution.
The threshold of requests per period after which the action will be executed for the first time.
ReturnsExpand Collapse
result: object { id, kind, last_updated, 5 more } or unknownA result.
A result.
Ruleset object { id, kind, last_updated, 5 more } A ruleset object.
A ruleset object.
rules: array of BlockRule { last_updated, version, id, 10 more } or object { id, action, enabled, 10 more } or CompressResponseRule { last_updated, version, id, 10 more } or 18 moreThe list of rules in the ruleset.
The list of rules in the ruleset.
ChallengeRule object { id, action, enabled, 10 more }
exposed_credential_check: optional object { password_expression, username_expression } Configuration for exposed credential checking.
Configuration for exposed credential checking.
ratelimit: optional object { characteristics, period, counting_expression, 5 more } An object configuring the rule’s rate limit behavior.
An object configuring the rule’s rate limit behavior.
Characteristics of the request on which the rate limit counter will be incremented.
An expression that defines when the rate limit counter should be incremented. It defaults to the same as the rule’s expression.
Period of time in seconds after which the action will be disabled following its first execution.
The threshold of requests per period after which the action will be executed for the first time.
JavaScriptChallengeRule object { id, action, enabled, 10 more }
exposed_credential_check: optional object { password_expression, username_expression } Configuration for exposed credential checking.
Configuration for exposed credential checking.
ratelimit: optional object { characteristics, period, counting_expression, 5 more } An object configuring the rule’s rate limit behavior.
An object configuring the rule’s rate limit behavior.
Characteristics of the request on which the rate limit counter will be incremented.
An expression that defines when the rate limit counter should be incremented. It defaults to the same as the rule’s expression.
Period of time in seconds after which the action will be disabled following its first execution.
The threshold of requests per period after which the action will be executed for the first time.
SetCacheControlRule object { id, action, enabled, 10 more }
action_parameters: optional object { immutable, "max-age", "must-revalidate", 10 more } The parameters configuring the rule’s action.
The parameters configuring the rule’s action.
immutable: optional object { operation, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
"max-age": optional object { operation, value, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration that accepts a duration value in seconds.
A cache-control directive configuration that accepts a duration value in seconds.
"must-revalidate": optional object { operation, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
"must-understand": optional object { operation, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
"no-cache": optional object { operation, cloudflare_only, qualifiers } or object { operation, cloudflare_only } A cache-control directive configuration that accepts optional qualifiers (header names).
A cache-control directive configuration that accepts optional qualifiers (header names).
"no-store": optional object { operation, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
"no-transform": optional object { operation, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
private: optional object { operation, cloudflare_only, qualifiers } or object { operation, cloudflare_only } A cache-control directive configuration that accepts optional qualifiers (header names).
A cache-control directive configuration that accepts optional qualifiers (header names).
"proxy-revalidate": optional object { operation, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
public: optional object { operation, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
"s-maxage": optional object { operation, value, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration that accepts a duration value in seconds.
A cache-control directive configuration that accepts a duration value in seconds.
"stale-if-error": optional object { operation, value, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration that accepts a duration value in seconds.
A cache-control directive configuration that accepts a duration value in seconds.
"stale-while-revalidate": optional object { operation, value, cloudflare_only } or object { operation, cloudflare_only } A cache-control directive configuration that accepts a duration value in seconds.
A cache-control directive configuration that accepts a duration value in seconds.
exposed_credential_check: optional object { password_expression, username_expression } Configuration for exposed credential checking.
Configuration for exposed credential checking.
ratelimit: optional object { characteristics, period, counting_expression, 5 more } An object configuring the rule’s rate limit behavior.
An object configuring the rule’s rate limit behavior.
Characteristics of the request on which the rate limit counter will be incremented.
An expression that defines when the rate limit counter should be incremented. It defaults to the same as the rule’s expression.
Period of time in seconds after which the action will be disabled following its first execution.
The threshold of requests per period after which the action will be executed for the first time.
SetCacheTagsRule object { id, action, enabled, 10 more }
action_parameters: optional object { operation, values } or object { expression, operation } or object { operation, values } or 3 moreThe parameters configuring the rule’s action.
The parameters configuring the rule’s action.
exposed_credential_check: optional object { password_expression, username_expression } Configuration for exposed credential checking.
Configuration for exposed credential checking.
ratelimit: optional object { characteristics, period, counting_expression, 5 more } An object configuring the rule’s rate limit behavior.
An object configuring the rule’s rate limit behavior.
Characteristics of the request on which the rate limit counter will be incremented.
An expression that defines when the rate limit counter should be incremented. It defaults to the same as the rule’s expression.
Period of time in seconds after which the action will be disabled following its first execution.
The threshold of requests per period after which the action will be executed for the first time.
TransformResponseHTMLRule object { id, action, enabled, 10 more }
exposed_credential_check: optional object { password_expression, username_expression } Configuration for exposed credential checking.
Configuration for exposed credential checking.
ratelimit: optional object { characteristics, period, counting_expression, 5 more } An object configuring the rule’s rate limit behavior.
An object configuring the rule’s rate limit behavior.
Characteristics of the request on which the rate limit counter will be incremented.
An expression that defines when the rate limit counter should be incremented. It defaults to the same as the rule’s expression.
Period of time in seconds after which the action will be disabled following its first execution.
The threshold of requests per period after which the action will be executed for the first time.
Create an account or zone ruleset rule
curl https://api.cloudflare.com/client/v4/$ACCOUNTS_OR_ZONES/$ACCOUNT_OR_ZONE_ID/rulesets/$RULESET_ID/rules \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
-d '{
"id": "3a03d665bac047339bb530ecb439a90d",
"description": "Block the request.",
"enabled": true,
"expression": "ip.src eq 1.1.1.1",
"ref": "my_ref"
}'{
"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
{
"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
}