[REngine, WAF] Custom rulesets at zone level

Author: pedrosousa

src/content/docs/ruleset-engine/about/phases.mdx

@@ -8,16 +8,17 @@ sidebar:
 
 A phase defines a stage in the life of a request where you can execute rulesets. Phases are defined by Cloudflare and cannot be modified.
 
-Phases exist at two levels: at the **account** level and at the **zone** level. For the same phase, rules defined at the account level are evaluated **before** the rules defined at the zone level.
+Phases exist at two levels:
 
-Each phase has at most one [entry point ruleset](/ruleset-engine/about/rulesets/#entry-point-ruleset) at the account and zone level.
+- At the account level
+- At the zone level
 
-:::note
+For the same phase, rules defined at the account level are evaluated before the rules defined at the zone level.
 
+Each phase has at most one [entry point ruleset](/ruleset-engine/about/rulesets/#entry-point-ruleset) at the account and zone level.
 
+:::note
 Currently, phases at the account level are only available in Enterprise plans.
-
-
 :::
 
 The following diagram outlines the request handling process where requests go through the available phases:

src/content/docs/ruleset-engine/basic-operations/add-rule-phase-rulesets.mdx

@@ -12,7 +12,7 @@ A [phase entry point ruleset](/ruleset-engine/about/rulesets/#entry-point-rulese
 
 To add one or more rules to a phase entry point ruleset, use one of the [ruleset update operations](/ruleset-engine/rulesets-api/update/) of the [Rulesets API](/ruleset-engine/rulesets-api/). When you add a rule to an entry point ruleset, the entry point ruleset is created automatically if it does not exist. This API method requires that you include in the request all rules you want to keep in the ruleset, or else they will be removed.
 
-If you are adding a **single** rule to a ruleset, consider using one of the [rule creation operations](/ruleset-engine/rulesets-api/add-rule/) instead. In this case, the request will only include the definition of the new rule.
+If you are adding a single rule to a ruleset, consider using one of the [rule creation operations](/ruleset-engine/rulesets-api/add-rule/) instead. In this case, the request only includes the definition of the new rule.
 
 :::note[Creating an entry point ruleset]
 Instead of relying on the automatic creation of an entry point ruleset, you can also create this ruleset explicitly using one of the [ruleset creation operations](/ruleset-engine/rulesets-api/create/).

src/content/docs/ruleset-engine/basic-operations/deploy-rulesets.mdx

@@ -19,7 +19,7 @@ A rule that executes a ruleset consists of:
 The rules in the ruleset execute when a request satisfies the expression.
 
 :::note
-To apply a rule to every request in a phase at the **zone** level, set the rule expression to `true`.
+To apply a rule to every request in a phase at the zone level, set the rule expression to `true`.
 :::
 
 ## Example

src/content/docs/ruleset-engine/custom-rulesets/add-rules-ruleset.mdx

@@ -7,16 +7,16 @@ sidebar:
 
 import { APIRequest, Render } from "~/components";
 
-To add rules to an existing custom ruleset, use the [Update an account ruleset](/api/resources/rulesets/methods/update/) operation and pass the rules in an array. Each rule has an expression and an action.
+To add rules to an existing custom ruleset, use the [Update an account or zone ruleset](/api/resources/rulesets/methods/update/) operation and pass the rules in an array. Each rule has an expression and an action.
 
 :::note[Choosing the appropriate API method]
 
-When you add rules to a custom ruleset using the [Update an account ruleset](/api/resources/rulesets/methods/update/) operation, you replace all the rules in the ruleset with the rules in the request. Use this API method when adding or updating several rules at once. This method will update the ruleset version number only once.
+When you add rules to a custom ruleset using the [Update an account or zone ruleset](/api/resources/rulesets/methods/update/) operation, you replace all the rules in the ruleset with the rules in the request. Use this API method when adding or updating several rules at once. This method will update the ruleset version number only once.
 
 You can use other API operations depending on the type of operation:
 
-- Add a single rule to an existing custom ruleset: Use the [Create an account ruleset rule](/api/resources/rulesets/subresources/rules/methods/create/) operation.
-- Update a single rule in a custom ruleset: Use the [Update an account ruleset rule](/api/resources/rulesets/subresources/rules/methods/edit/) operation.
+- Add a single rule to an existing custom ruleset: Use the [Create an account or zone ruleset rule](/api/resources/rulesets/subresources/rules/methods/create/) operation.
+- Update a single rule in a custom ruleset: Use the [Update an account or zone ruleset rule](/api/resources/rulesets/subresources/rules/methods/edit/) operation.
 
 :::
 
@@ -26,7 +26,7 @@ You can use other API operations depending on the type of operation:
 
 ## Add rules
 
-The following request adds two rules to a custom ruleset with ID `$RULESET_ID`. These will be the only two rules in the ruleset.
+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.
 
@@ -90,9 +90,9 @@ The response will include the rule ID of the new rules in the `id` field.
 
 ## Update rules
 
-To update one or more rules in a custom ruleset, use the [Update an account ruleset](/api/resources/rulesets/methods/update/) 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.
+To update one or more rules in a custom ruleset, use the [Update an account or zone ruleset](/api/resources/rulesets/methods/update/) 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 and updates the execution order of the rules.
+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.
 

src/content/docs/ruleset-engine/custom-rulesets/create-custom-ruleset.mdx

@@ -7,7 +7,7 @@ sidebar:
 
 import { APIRequest, Render } from "~/components";
 
-Use the [Create an account ruleset](/api/resources/rulesets/methods/create/) operation to create a custom ruleset, making sure that you:
+Use the [Create an account or zone ruleset](/api/resources/rulesets/methods/create/) operation to create a custom ruleset, making sure that you:
 
 - Set the `kind` field to `custom`.
 - Specify the name of the [phase](/ruleset-engine/reference/phases-list/) where you want to create the custom ruleset in the `phase` field.
@@ -16,16 +16,53 @@ Use the [Create an account ruleset](/api/resources/rulesets/methods/create/) ope
 
 <Render file="custom-rulesets-dashboard" product="ruleset-engine" />
 
-## Example
+<Render file="custom-ruleset-zone-limitation" product="ruleset-engine" />
 
-The following request creates a new custom ruleset. The response will include the ID of the new custom ruleset in the `id` field.
+## Example A - Custom ruleset at the account level
+
+The following request creates a new custom ruleset at the account level. The response will include the ID of the new custom ruleset in the `id` field.
 
 <APIRequest
 	path="/accounts/{account_id}/rulesets"
 	method="POST"
 	json={{
 		name: "Custom Ruleset 1",
-		description: "My First Custom Ruleset",
+		description: "My First Custom Ruleset (account)",
+		kind: "custom",
+		phase: "http_request_firewall_custom",
+	}}
+/>
+
+```json output {3}
+{
+	"result": {
+		"id": "f82ccda3d21f4a02825d3fe45b5e1c10",
+		"name": "Custom Ruleset 1",
+		"description": "My First Custom Ruleset (account)",
+		"kind": "custom",
+		"version": "1",
+		"last_updated": "2025-08-09T10:27:30.636197Z",
+		"phase": "http_request_firewall_custom"
+	},
+	"success": true,
+	"errors": [],
+	"messages": []
+}
+```
+
+You can include a list of rules in the custom ruleset creation request. If you have not added any rules, refer to [Add rules to a custom ruleset](/ruleset-engine/custom-rulesets/add-rules-ruleset/) for more information.
+
+
+## Example B - Custom ruleset at the zone level
+
+The following request creates a new custom ruleset at the zone level. The response will include the ID of the new custom ruleset in the `id` field.
+
+<APIRequest
+	path="/zones/{zone_id}/rulesets"
+	method="POST"
+	json={{
+		name: "Custom Ruleset 1",
+		description: "My First Custom Ruleset (zone)",
 		kind: "custom",
 		phase: "http_request_firewall_custom",
 	}}
@@ -36,10 +73,10 @@ The following request creates a new custom ruleset. The response will include th
 	"result": {
 		"id": "f82ccda3d21f4a02825d3fe45b5e1c10",
 		"name": "Custom Ruleset 1",
-		"description": "My First Custom Ruleset",
+		"description": "My First Custom Ruleset (zone)",
 		"kind": "custom",
 		"version": "1",
-		"last_updated": "2021-03-09T10:27:30.636197Z",
+		"last_updated": "2025-08-09T10:27:30.636197Z",
 		"phase": "http_request_firewall_custom"
 	},
 	"success": true,
@@ -49,3 +86,6 @@ The following request creates a new custom ruleset. The response will include th
 ```
 
 You can include a list of rules in the custom ruleset creation request. If you have not added any rules, refer to [Add rules to a custom ruleset](/ruleset-engine/custom-rulesets/add-rules-ruleset/) for more information.
+
+<Render file="custom-ruleset-zone-limitation" product="ruleset-engine" />
+

src/content/docs/ruleset-engine/custom-rulesets/deploy-custom-ruleset.mdx

@@ -8,21 +8,27 @@ description: Learn how to deploy a custom ruleset to your Cloudflare account.
 
 import { APIRequest, Render } from "~/components";
 
-To deploy a custom ruleset, add a rule with `execute` action to the list of rules of a phase [entry point ruleset](/ruleset-engine/about/rulesets/#entry-point-ruleset) at the account level. The expression of the new rule will define when the custom ruleset will run.
+To deploy a custom ruleset, add a rule with `execute` action to the list of rules of a phase [entry point ruleset](/ruleset-engine/about/rulesets/#entry-point-ruleset) at the account or zone level. The expression of the new rule will define when the custom ruleset will run.
+
+You can only deploy custom rulesets in an entry point ruleset with the same scope. For example, a custom ruleset defined at the account level can only be deployed at the account level.
 
 <Render file="custom-rulesets-terraform" product="ruleset-engine" />
 
 <Render file="custom-rulesets-dashboard" product="ruleset-engine" />
 
+<Render file="custom-ruleset-zone-limitation" product="ruleset-engine" />
+
 ## Before you begin
 
 1. Obtain the name of the [phase](/ruleset-engine/reference/phases-list/) where you want to deploy the custom ruleset.
 2. [Create a custom ruleset](/ruleset-engine/custom-rulesets/create-custom-ruleset/) and keep the ID of the new custom ruleset.
 3. [Fetch the rules already present in the phase entry point ruleset](/ruleset-engine/basic-operations/view-rulesets/#view-the-rules-included-in-a-ruleset). You must include in the `PUT` request all existing rules you want to keep.
 
-## Example
+## Example A - Account-level deployment
 
-The following `PUT` request adds a rule that executes a custom ruleset when the zone name matches `example.com`. The response will include all the rules in the phase entry point ruleset.
+The following `PUT` request adds a rule that executes a custom ruleset when the zone name matches `example.com`.
+
+You must include in the `PUT` request the IDs of all existing rules you want to keep. The response will include all the rules in the phase entry point ruleset after the update.
 
 <APIRequest
 	path="/accounts/{account_id}/rulesets/phases/{ruleset_phase}/entrypoint"
@@ -110,5 +116,78 @@ The following `PUT` request adds a rule that executes a custom ruleset when the
 ```
 
 :::caution
-Regarding the expression of the rule deploying the ruleset, you must use parentheses to enclose any custom conditions and end your expression with `and cf.zone.plan eq "ENT"` or else the API operation will fail.
+When deploying the custom ruleset at the account level, you must use parentheses to enclose any custom conditions and end your expression with `and cf.zone.plan eq "ENT"` like in the example above, or else the API operation will fail.
 :::
+
+## Example B - Zone-level deployment
+
+The following `PUT` request adds a rule to a zone-level entry point ruleset that executes a custom ruleset for requests targeting the `/login` URI path.
+
+You must include in the `PUT` request the IDs of all existing rules you want to keep. The response will include all the rules in the phase entry point ruleset after the update.
+
+<APIRequest
+	path="/zones/{zone_id}/rulesets/phases/{ruleset_phase}/entrypoint"
+	method="PUT"
+	parameters={{
+		ruleset_phase: "http_request_firewall_custom",
+	}}
+	json={{
+		rules: [
+			{
+				action: "execute",
+				description: "Execute custom ruleset (zone)",
+				expression: '(http.request.uri.path eq "/login")',
+				action_parameters: {
+					id: "<CUSTOM_RULESET_ID>",
+				},
+			},
+			{
+				id: "<EXISTING_PHASE_RULE_ID_1>",
+			},
+		],
+	}}
+/>
+
+```json output
+{
+	"result": {
+		"id": "<ZONE_PHASE_RULESET_ID>",
+		"name": "http_request_firewall_custom phase entry point ruleset for my zone",
+		"description": "",
+		"kind": "zone",
+		"version": "3",
+		"rules": [
+			{
+				"id": "<PHASE_RULE_ID>",
+				"version": "1",
+				"action": "execute",
+				"description": "Execute custom ruleset (zone)",
+				"action_parameters": {
+					"id": "<CUSTOM_RULESET_ID>",
+					"version": "latest"
+				},
+				"expression": "(http.request.uri.path eq \"/login\")",
+				"last_updated": "2025-08-18T18:35:14.135697Z",
+				"ref": "<PHASE_RULE_REF>",
+				"enabled": true
+			},
+			{
+				"id": "<EXISTING_PHASE_RULE_ID_1>",
+				"version": "1",
+				"action": "managed_challenge",
+				"expression": "(cf.waf.score lt 20 and http.request.uri.path wildcard \"/admin/*\")",
+				"last_updated": "2025-08-16T15:51:49.180378Z",
+				"ref": "<EXISTING_PHASE_RULE_REF_1>",
+				"enabled": true
+			}
+		],
+		"last_updated": "2025-08-18T18:35:14.135697Z",
+		"phase": "http_request_firewall_custom"
+	},
+	"success": true,
+	"errors": [],
+	"messages": []
+}
+```
+
+<Render file="custom-ruleset-zone-limitation" product="ruleset-engine" />

src/content/docs/ruleset-engine/custom-rulesets/index.mdx

@@ -5,15 +5,15 @@ sidebar:
   order: 7
 ---
 
-Use the following workflow to deploy a custom ruleset at the account level:
+Use the following workflow to deploy a custom ruleset:
 
 1. [Create a custom ruleset](/ruleset-engine/custom-rulesets/create-custom-ruleset/).
 2. [Add rules to your custom ruleset](/ruleset-engine/custom-rulesets/add-rules-ruleset/).
-3. [Add a rule to an account-level phase entry point ruleset that executes the custom ruleset](/ruleset-engine/custom-rulesets/deploy-custom-ruleset/).
+3. [Add a rule to a phase entry point ruleset that executes the custom ruleset](/ruleset-engine/custom-rulesets/deploy-custom-ruleset/).
 
 You must create a rule with `execute` action in an entry point ruleset to execute the custom ruleset (step 3 in the previous procedure). If you skip this step, the rules of the custom ruleset will not run.
 
-Currently, custom rulesets are only supported by the [Cloudflare WAF](/waf/).
+Currently, custom rulesets are only supported by the [Cloudflare WAF](/waf/), both at the account and the zone level.
 
 :::note
 You cannot execute a custom ruleset from another custom ruleset, only from an entry point ruleset.

src/content/docs/ruleset-engine/rules-language/actions.mdx

@@ -113,6 +113,7 @@ The available actions depend on the [phase](/ruleset-engine/about/phases/) where
         <p>
           <ul>
             <li>Skip all remaining rules in the current ruleset</li>
+            <li>Skip all remaining rules in the current phase (zone-level only option)</li>
             <li>Skip rulesets</li>
             <li>Skip rules of a ruleset</li>
             <li>Skip phases</li>

src/content/docs/ruleset-engine/rulesets-api/create.mdx

@@ -39,7 +39,7 @@ Use the `rules` parameter to supply a list of rules for the ruleset. For an obje
 
 ## Example - Create a custom ruleset
 
-The following `POST` request creates a custom ruleset in the `http_request_firewall_custom` phase containing a single rule.
+The following `POST` request creates a custom ruleset in the `http_request_firewall_custom` phase at the account level containing a single rule.
 
 <APIRequest
 	path="/accounts/{account_id}/rulesets"

src/content/docs/ruleset-engine/rulesets-api/view.mdx

@@ -74,7 +74,7 @@ Use one of the following API endpoints:
   `GET /zones/{zone_id}/rulesets/phases/{phase_name}/entrypoint`
 
 :::note
-You can only use the _Get a zone ruleset_ operation for zone-level phase entry points (entry points where `kind` is set to `zone`).
+You can only use the [Get a zone ruleset](/api/resources/rulesets/methods/get/) operation for zone-level phase entry points (entry points where `kind` is set to `zone`).
 :::
 
 The API returns a `404 Not Found` HTTP status code under these conditions: