---
description: Create account-level custom rulesets using the Rulesets API.
title: Create a custom ruleset using the API
image: https://developers.cloudflare.com/waf/account/custom-rulesets/create-api/og.png?v=860593a02884bff1
---
[Skip to content](#main-content)
> Documentation Index
> Fetch the complete documentation index at: https://developers.cloudflare.com/waf/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a custom ruleset using the API
Last updated Sep 8, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/waf/account/custom-rulesets/create-api/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/)
Note
This feature requires an Enterprise plan.
## Quota limits
Account-level custom rulesets have the following quota limits:
- **Maximum rulesets:** 10
- **Maximum rules per ruleset:** 100
- **Total rule quota:** 1,000 rules across all rulesets on the request path
The total rule quota of 1,000 rules is a hard limit that applies to all plans and cannot be increased. This limit applies across all rulesets that a request traverses, not just account-level custom rulesets.
### Redistribute rules across rulesets
If you need to change the distribution of rules across your rulesets (for example, to create fewer rulesets with more rules per ruleset), contact Cloudflare Support. Only Cloudflare Support can update account-level entitlements to change the ruleset and rule distribution.
Before contacting Support, consider the following optimizations:
- **Consolidate rules:** Combine rules with similar conditions or actions into a single rule with broader matching criteria.
- **Remove unused rules:** Audit your rulesets and remove rules that are no longer triggering or are duplicating functionality.
- **Use IP lists:** Instead of creating multiple rules for individual IP addresses, use [IP lists](https://developers.cloudflare.com/waf/tools/lists/) to group IPs and reference them in a single rule.
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](https://developers.cloudflare.com/api/resources/rulesets/methods/list/) 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](https://developers.cloudflare.com/ruleset-engine/rulesets-api/) to work with custom rulesets using the API.
If you are using Terraform, refer to [WAF custom rules configuration using Terraform](https://developers.cloudflare.com/terraform/additional-configurations/waf-custom-rules/#create-and-deploy-a-custom-ruleset).
## Procedure
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](https://developers.cloudflare.com/ruleset-engine/about/rulesets/#entry-point-ruleset) of the `http_request_firewall_custom` phase.
### 1. Create a custom ruleset
The following example creates a custom ruleset at the account level with a single rule in the `rules` array.
Required API token permissions
At least one of the following token permissions is required:
- Account WAF Write
- Account Rulesets Write
*Create an account rulesetbash*
```bash
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.
### 2. Deploy the custom ruleset
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](https://developers.cloudflare.com/api/resources/rulesets/subresources/phases/methods/get/) operation to obtain the definition of the entry point ruleset for the `http_request_firewall_custom` phase. You will need the [account ID](https://developers.cloudflare.com/fundamentals/account/find-account-and-zone-ids/) 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
Required API token permissions
At least one of the following token permissions is required:
- Account WAF Write
- Account Rulesets Write
Required API token permissions
At least one of the following token permissions is required:
- Account WAF Write
- Account Rulesets Write