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 WriteParametersExpand Collapse
RuleCreateParams = BlockRule | ChallengeRule | ResponseCompressionRule | 18 more
RuleCreateParamsBase { account_id, zone_id, dry_run, 11 more }
Path param: The Account ID to use for this endpoint. Mutually exclusive with the Zone ID.
Path param: The Zone ID to use for this endpoint. Mutually exclusive with the Account ID.
Query param: 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.
position?: BeforePosition { before } | AfterPosition { after } | IndexPosition { index } Body param: An object configuring where the rule will be placed.
Body param: An object configuring where the rule will be placed.
Body param: An object configuring the rule’s rate limit behavior.
Body param: 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
RuleCreateResponse = Ruleset { id, kind, last_updated, 5 more } | unknownA result.
A result.
Ruleset { id, kind, last_updated, 5 more } A ruleset object.
A ruleset object.
rules: Array<BlockRule { id, action, enabled, 2 more } | ChallengeRule { id, action, enabled, 10 more } | ResponseCompressionRule { id, action, enabled, 2 more } | 18 more>The list of rules in the ruleset.
The list of rules in the ruleset.
ChallengeRule { id, action, enabled, 10 more }
exposed_credential_check?: ExposedCredentialCheck { password_expression, username_expression } Configuration for exposed credential checking.
Configuration for exposed credential checking.
ratelimit?: Ratelimit { 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.
ResponseCompressionRule extends CompressResponseRule { last_updated, version, id, 10 more } { id, action, enabled, 2 more }
DDoSDynamicRule extends DDoSDynamicRule { last_updated, version, id, 10 more } { id, action, enabled, 2 more }
ExecuteRule extends ExecuteRule { last_updated, version, id, 10 more } { id, action, enabled, 2 more }
ForceConnectionCloseRule extends ForceConnectionCloseRule { last_updated, version, id, 10 more } { id, action, enabled, 2 more }
JavaScriptChallengeRule { id, action, enabled, 10 more }
exposed_credential_check?: ExposedCredentialCheck { password_expression, username_expression } Configuration for exposed credential checking.
Configuration for exposed credential checking.
ratelimit?: Ratelimit { 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.
LogCustomFieldRule extends LogCustomFieldRule { last_updated, version, id, 10 more } { id, action, enabled, 2 more }
ManagedChallengeRule extends ManagedChallengeRule { last_updated, version, id, 10 more } { id, action, enabled, 2 more }
RedirectRule extends RedirectRule { last_updated, version, id, 10 more } { id, action, enabled, 2 more }
RewriteRule extends RewriteRule { last_updated, version, id, 10 more } { id, action, enabled, 2 more }
ServeErrorRule extends ServeErrorRule { last_updated, version, id, 10 more } { id, action, enabled, 2 more }
SetCacheControlRule { id, action, enabled, 10 more }
action_parameters?: ActionParameters { immutable, max-age, must-revalidate, 10 more } The parameters configuring the rule’s action.
The parameters configuring the rule’s action.
immutable?: SetDirective { operation, cloudflare_only } | RemoveDirective { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
"max-age"?: SetDirective { operation, value, cloudflare_only } | RemoveDirective { 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"?: SetDirective { operation, cloudflare_only } | RemoveDirective { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
"must-understand"?: SetDirective { operation, cloudflare_only } | RemoveDirective { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
"no-cache"?: SetDirective { operation, cloudflare_only, qualifiers } | RemoveDirective { 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"?: SetDirective { operation, cloudflare_only } | RemoveDirective { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
"no-transform"?: SetDirective { operation, cloudflare_only } | RemoveDirective { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
private?: SetDirective { operation, cloudflare_only, qualifiers } | RemoveDirective { 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"?: SetDirective { operation, cloudflare_only } | RemoveDirective { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
public?: SetDirective { operation, cloudflare_only } | RemoveDirective { operation, cloudflare_only } A cache-control directive configuration.
A cache-control directive configuration.
"s-maxage"?: SetDirective { operation, value, cloudflare_only } | RemoveDirective { 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"?: SetDirective { operation, value, cloudflare_only } | RemoveDirective { 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"?: SetDirective { operation, value, cloudflare_only } | RemoveDirective { 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?: ExposedCredentialCheck { password_expression, username_expression } Configuration for exposed credential checking.
Configuration for exposed credential checking.
ratelimit?: Ratelimit { 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.
SetCacheSettingsRule extends SetCacheSettingsRule { last_updated, version, id, 10 more } { id, action, enabled, 2 more }
SetCacheTagsRule { id, action, enabled, 10 more }
action_parameters?: AddCacheTagsValues { operation, values } | AddCacheTagsExpression { expression, operation } | RemoveCacheTagsValues { operation, values } | 3 moreThe parameters configuring the rule’s action.
The parameters configuring the rule’s action.
exposed_credential_check?: ExposedCredentialCheck { password_expression, username_expression } Configuration for exposed credential checking.
Configuration for exposed credential checking.
ratelimit?: Ratelimit { 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.
SetConfigurationRule extends SetConfigRule { last_updated, version, id, 10 more } { id, action, enabled, 2 more }
TransformResponseHTMLRule { id, action, enabled, 10 more }
exposed_credential_check?: ExposedCredentialCheck { password_expression, username_expression } Configuration for exposed credential checking.
Configuration for exposed credential checking.
ratelimit?: Ratelimit { 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
import Cloudflare from 'cloudflare';
const client = new Cloudflare({
apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted
});
const rule = await client.rulesets.rules.create('2f2feab2026849078ba485f918791bdc', {
account_id: 'account_id',
});
console.log(rule);{
"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
}