导航|地址|刷新
Add a rule to a 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

/Rulesets API

/Add a rule to a ruleset

Add a rule to a ruleset

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

OverviewExampleDefine the rule position in the ruleset

Adds a single rule to an existing ruleset. Use this endpoint to add a rule without having to include all the existing ruleset rules in the request.

Use one of the following API endpoints:

Create an account ruleset rule
POST /accounts/{account_id}/rulesets/{ruleset_id}/rules

Create a zone ruleset rule
POST /zones/{zone_id}/rulesets/{ruleset_id}/rules

Include the rule definition in the request body.

By default, the rule will be added to the end of the existing list of rules in the ruleset. To define a specific position for the rule, include a position object in the request body according to the guidelines in Change the order of a rule in a ruleset.

Invoking this method creates a new version of the ruleset.

Example

The following POST request adds a rule to ruleset $RULESET_ID of zone $ZONE_ID. The ruleset ID was previously obtained using the List zone rulesets operation, and corresponds to the entry point ruleset for the http_request_firewall_custom phase.

The response will include the complete ruleset after adding the rule.

Required API token permissions
At least one of the following token permissions is required:
Response Compression Write

Config Settings Write

Dynamic URL Redirects Write

Cache Settings Write

Custom Errors Write

Origin Write

Managed headers Write

Zone Transform Rules Write

Mass URL Redirects Write

Magic Firewall Write

L4 DDoS Managed Ruleset Write

HTTP DDoS Managed Ruleset Write

Sanitize Write

Transform Rules Write

Select Configuration Write

Bot Management Write

Zone WAF Write

Account WAF Write

Account Rulesets Write

Logs Write

Logs Write
Create a zone ruleset rulebashcurl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID/rules" \ --request POST \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "action": "js_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" }'{ "result": { "id": "<RULESET_ID>", "name": "Zone Ruleset 1", "description": "My phase entry point ruleset at the zone level", "kind": "zone", "version": "11", "rules": [ { "id": "<RULE_ID_1>", "version": "1", "action": "challenge", "expression": "not http.request.uri.path matches \"^/api/.*$\"", "last_updated": "2023-11-23T11:36:24.192361Z", "ref": "<RULE_REF_1>", "enabled": true }, { "id": "<NEW_RULE_ID>", "version": "1", "action": "js_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": "2024-06-22T12:35:58.144683Z", "ref": "<NEW_RULE_REF>", "enabled": true } ], "last_updated": "2024-06-22T12:35:58.144683Z", "phase": "http_request_firewall_custom" }, "success": true, "errors": [], "messages": []}

Define the rule position in the ruleset

To define the position of the new rule in the ruleset, include a position object in the request, containing one of the following:

"before": "<RULE_ID>" — Places the rule before rule <RULE_ID>. Use this argument with an empty rule ID value ("") to set the rule as the first rule in the ruleset.

"after": "<RULE_ID>" — Places the rule after rule <RULE_ID>. Use this argument with an empty rule ID value ("") to set the rule as the last rule in the ruleset.

"index": <POSITION_NUMBER> — Places the rule in the exact position specified by the integer number <POSITION_NUMBER>. Position numbers start with 1. Existing rules in the ruleset from the specified position number onward are shifted one position (no rule is overwritten). For example, when you place a rule in position n using index, existing rules with index n, n+1, n+2, and so on, are shifted one position — their new position will be n+1, n+2, n+3, and so forth. If the index is out of range, the method returns a 400 HTTP status code.

Important

You can only use one of the before, after, and index fields at a time.

For examples of using a position object, refer to Update a rule in a ruleset.

PreviousUpdate or deploy a ruleset NextUpdate a rule in a ruleset

Was this helpful?

YesNo

Edit page Report issue

On this page

Overview

Example

Define the rule position in the ruleset

Edit page Report issue

Getting started
Plans Contact sales PartnersFind 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

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