Create a custom ruleset using the API

To deploy custom rules at the account level:

1. Create a custom ruleset with one or more rules. Alternatively, identify the existing custom ruleset you want to deploy using the List account rulesets API operation.
2. Deploy the custom ruleset so that it gets executed. To deploy a custom ruleset, create a rule with the execute action.

Use the Rulesets API to work with custom rulesets using the API.

If you are using Terraform, refer to WAF custom rules configuration using Terraform.

To deploy a custom ruleset, follow these general steps:

1. Create a custom ruleset in the http_request_firewall_custom phase with one or more rules.
2. Deploy the ruleset to the entry point ruleset of the http_request_firewall_custom phase.

The following example creates a custom ruleset at the account level with a single rule in the rules array.

Required API token permissions

• Account WAF Write
• Account Rulesets Write

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rulesets" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"description": "",
		"kind": "custom",
		"name": "My custom ruleset",
		"rules": [
				{
						"description": "Challenge web traffic (not /api)",
						"expression": "not starts_with(http.request.uri.path, \"/api/\")",
						"action": "managed_challenge"
				}
		],
		"phase": "http_request_firewall_custom"
	}'

Save the ruleset ID in the response for the next step.

To deploy the custom ruleset, add a rule with "action": "execute" to the http_request_firewall_custom phase entry point ruleset.

1. Invoke the Get an account entry point ruleset operation to obtain the definition of the entry point ruleset for the http_request_firewall_custom phase. You will need the account ID for this task.

   Required API token permissions

   At least one of the following token permissions is required:
   • Account WAF Write
   • Account WAF Read
   • Account Rulesets Read
   • Account Rulesets Write
   Get an account entry point rulesetbash

   curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rulesets/phases/http_request_firewall_custom/entrypoint" \
   	--request GET \
   	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

   {
   	"result": {
   		"description": "Account-level phase entry point",
   		"id": "<RULESET_ID>",
   		"kind": "root",
   		"last_updated": "2024-03-16T15:40:08.202335Z",
   		"name": "root",
   		"phase": "http_request_firewall_custom",
   		"rules": [
   			// ...
   		],
   		"version": "9"
   	},
   	"success": true,
   	"errors": [],
   	"messages": []
   }

2. If the entry point ruleset already exists (that is, if you received a 200 OK status code and the ruleset definition), take note of the ruleset ID in the response. Then, invoke the Create an account ruleset rule operation to add an execute rule to the existing ruleset deploying the custom ruleset. By default, the rule will be added at the end of the list of rules already in the ruleset.

   The following request creates a rule that executes the custom ruleset with ID <CUSTOM_RULESET_ID> for all Enterprise zones in the account:

   Required API token permissions

   At least one of the following token permissions is required:
   • Account WAF Write
   • Account Rulesets Write
   Create an account ruleset rulebash

   curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rulesets/$RULESET_ID/rules" \
   	--request POST \
   	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
   	--json '{
   		"description": "Execute custom ruleset",
   		"expression": "(cf.zone.plan eq \"ENT\")",
   		"action": "execute",
   		"action_parameters": {
   				"id": "<CUSTOM_RULESET_ID>"
   		},
   		"enabled": true
   	}'

   Caution

   At the account level, you can only apply custom rulesets to incoming traffic of zones on an Enterprise plan. To enforce this requirement, you must include cf.zone.plan eq "ENT" in the expression of the execute rule deploying the custom ruleset.

3. If the entry point ruleset does not exist (that is, if you received a 404 Not Found status code in step 1), create it using the Create an account ruleset operation. Include a single rule in the rules array that executes the custom ruleset for all incoming requests of Enterprise zones in your account.

   Required API token permissions

   At least one of the following token permissions is required:
   • Account WAF Write
   • Account Rulesets Write
   Create an account rulesetbash

   curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rulesets" \
   	--request POST \
   	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
   	--json '{
   		"description": "",
   		"kind": "root",
   		"name": "Account-level phase entry point",
   		"rules": [
   				{
   						"action": "execute",
   						"expression": "(cf.zone.plan eq \"ENT\")",
   						"action_parameters": {
   								"id": "<CUSTOM_RULESET_ID>"
   						}
   				}
   		],
   		"phase": "http_request_firewall_custom"
   	}'

Use the different operations in the Rulesets API to work with the custom ruleset you created and deployed. The following table has a list of common tasks for working with custom rulesets at the account level:

For instructions on creating a custom ruleset at the zone level via API, refer to Custom rulesets (zone level).

For more information on working with custom rulesets, refer to Work with custom rulesets in the Ruleset Engine documentation.