导航|地址|刷新
Add rules to a custom ruleset

Skip to contentDocumentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/ruleset-engine/llms.txt
Use this file to discover all available pages before exploring further.

Docs Directory API SDKs Changelog

Search

Log in

Ruleset Engine

/

Overview

About

Overview

Phases

Rulesets

Rules

Basic API operations

View rulesets

Add rules to phase entry point rulesets

Deploy rulesets

Work with managed rulesets

Overview

Deploy a managed ruleset

Override a managed ruleset

Override examples

Overview

Set WordPress rules to Block

Enable only Joomla rules

Enable only selected rules

Deploy a managed ruleset with ruleset, tag, and rule overrides

Adjust the sensitivity of an HTTP DDoS rule to Low

Adjust an L3/4 DDoS rule ↗

Create an exception

Work with custom rulesets

Overview

Create a custom ruleset

Add rules to a custom ruleset

Deploy a custom ruleset

Rules language

Overview

Expressions

Overview

Edit in the dashboard

Operators and grouping symbols

Values

Actions

Fields

Overview

Fields reference

Functions

Rulesets API

Overview

JSON objects

Endpoints

List and view rulesets

Create a ruleset

Update or deploy a ruleset

Add a rule to a ruleset

Update a rule in a ruleset

Delete a rule in a ruleset

Delete a ruleset

Reference

Phases list

Agent resources

Agent setup ↗

Cloudflare Skills ↗

Code Mode MCP Server ↗

Domain-specific MCP Servers ↗MCP

Ruleset Engine llms.txt ↗

Ruleset Engine llms-full.txt ↗

Cloudflare Docs llms.txt ↗

Cloudflare Docs llms-full.txt ↗

Home

/Ruleset Engine

/Work with custom rulesets

/Add rules to a custom ruleset

Add rules to a custom ruleset

Last updated Apr 16, 2026|Copy as Markdown|View as Markdown|Agent setup

OverviewAdd rulesUpdate rules

To add rules to an existing custom ruleset, use the Update an account or zone ruleset operation and pass the rules in an array. Each rule has an expression and an action.

Choose the appropriate API method

The Update an account or zone ruleset operation replaces all the rules in the ruleset with the rules in the request. Use this API operation when you need to add or update several rules at once. This operation updates the ruleset version number only once.

Depending on the update you want to perform, consider using one of the following API operations instead:

Add a single rule to an existing custom ruleset: Use the Create an account or zone ruleset rule operation. Refer to Add a rule to a ruleset for an example.

Update a single rule in a custom ruleset: Use the Update an account or zone ruleset rule operation. Refer to Update a rule in a ruleset for an example.

If you are using Terraform, refer to WAF custom rules configuration using Terraform for examples of creating and deploying custom rulesets.

If you are using the Cloudflare dashboard, refer to Work with custom rulesets in the dashboard.

Add rules

The following request adds two rules to a custom ruleset at the account level with ID $RULESET_ID. These will be the only two rules in the ruleset.

The response will include the rule ID of the new rules in the id field.

Required API token permissions
At least one of the following token permissions is 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
Update an account rulesetbashcurl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rulesets/$RULESET_ID" \ --request PUT \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "rules": [ { "expression": "(ip.src.country in {\"GB\" \"FR\"} and cf.bot_management.score < 20 and not cf.bot_management.verified_bot)", "action": "challenge", "description": "challenge GB and FR based on bot score" }, { "expression": "not http.request.uri.path matches \"^/api/.*$\"", "action": "challenge", "description": "challenge not /api" } ] }'{ "result": { "id": "<CUSTOM_RULESET_ID>", "name": "Custom Ruleset 1", "kind": "custom", "version": "2", "rules": [ { "id": "<CUSTOM_RULE_ID_1>", "version": "1", "action": "challenge", "expression": "(ip.src.country in {\"GB\" \"FR\"} and cf.bot_management.score < 20 and not cf.bot_management.verified_bot)", "description": "challenge GB and FR based on bot score", "last_updated": "2021-03-18T18:25:08.122758Z", "ref": "<CUSTOM_RULE_REF_1>", "enabled": true }, { "id": "<CUSTOM_RULE_ID_2>", "version": "1", "action": "challenge", "expression": "not http.request.uri.path matches \"^/api/.*$\"", "description": "challenge not /api", "last_updated": "2021-03-18T18:25:08.122758Z", "ref": "<CUSTOM_RULE_REF_2>", "enabled": true } ], "last_updated": "2021-03-18T18:25:08.122758Z", "phase": "http_request_firewall_custom" }, "success": true, "errors": [], "messages": []}

Update rules

To update one or more rules in a custom ruleset, use the Update an account or zone ruleset operation. Include the ID of the rules you want to modify in the rules array and add the fields you wish to update. The request replaces the entire ruleset with a new version. Therefore, you must include the ID of all the rules you wish to keep.

The following PUT request edits one rule in a custom ruleset at the account level and updates the execution order of the rules.

The response will include the modified custom ruleset. Note that the updated rule and ruleset version number increment.

Required API token permissions
At least one of the following token permissions is 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
Update an account rulesetbashcurl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rulesets/$RULESET_ID" \ --request PUT \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "rules": [ { "id": "<CUSTOM_RULE_ID_2>", "expression": "not http.request.uri.path matches \"^/api/.*$\"", "action": "js_challenge", "description": "js_challenge when not /api" }, { "id": "<CUSTOM_RULE_ID_1>" } ] }'{ "result": { "id": "<CUSTOM_RULESET_ID>", "name": "Custom Ruleset 1", "kind": "custom", "version": "3", "rules": [ { "id": "<CUSTOM_RULE_ID_2>", "version": "2", "action": "js_challenge", "expression": "not http.request.uri.path matches \"^/api/.*$\"", "description": "js_challenge when not /api", "last_updated": "2021-03-18T18:30:08.122758Z", "ref": "<CUSTOM_RULE_ID_2>", "enabled": true }, { "id": "<CUSTOM_RULE_ID_1>", "version": "1", "action": "challenge", "expression": "(ip.src.country in {\"GB\" \"FR\"} and cf.bot_management.score < 20 and not cf.bot_management.verified_bot)", "description": "challenge GB and FR based on bot score", "last_updated": "2021-03-18T18:25:08.122758Z", "ref": "<CUSTOM_RULE_ID_1>", "enabled": true } ], "last_updated": "2021-03-18T18:30:08.122758Z", "phase": "http_request_firewall_custom" }, "success": true, "errors": [], "messages": []}

Caution

The request above completely replaces the list of rules in the ruleset. If you omit an existing rule from the rules array, it will not appear in the new version of the ruleset.

PreviousCreate a custom ruleset NextDeploy a custom ruleset

Was this helpful?

YesNo

Edit page Report issue

On this page

Overview

Add rules

Update rules

Edit pageReport issue

Getting started
PlansContact salesPartnersFind a partnerStartupsUnder attack?Domain name search

Company
AboutCareersInvestorsPressPress kitGlobal network

Public interest
Project GalileoAthenian ProjectCloudflare for CampaignsProject FairshotImpact/ESG

Compliance
Compliance resourcesTrust HubData ProtectionResponsible AITransparency reportReport abuse

Resources
App innovation reportCloudflare RadarCase studiesStatusSupportEventsBlog

Developers
DocumentationLearning centerCommunity

Solutions
SSE and SASE platformCloudflare AI CloudAI SecurityFrontend Development PlatformMulti-Tenant Platform DevelopmentWeb Security Platform

Start BuildingLog In

© 2026 Cloudflare, Inc.

Privacy policy|Report security issues|Terms of use|Trademark
|
Your privacy choices

Docs

------
导航页打开网址