--- description: Create a new ruleset using the Rulesets API. title: Create a ruleset image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation 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. # Create a ruleset Last updated Aug 24, 2026|Copy as Markdown|[View as Markdown](https://mchen-ai-models-sync.previews.developers.cloudflare.com/ruleset-engine/rulesets-api/create/index.md)|[Agent setup](https://mchen-ai-models-sync.previews.developers.cloudflare.com/agent-setup/) Creates a ruleset of a given kind in the specified phase. Allows you to create phase entry point rulesets. Use one of the following API endpoints: * [Create an account ruleset](https://mchen-ai-models-sync.previews.developers.cloudflare.com/api/resources/rulesets/methods/create/) `POST /accounts/{account_id}/rulesets` * [Create a zone ruleset](https://mchen-ai-models-sync.previews.developers.cloudflare.com/api/resources/rulesets/methods/create/) `POST /zones/{zone_id}/rulesets` ## Parameters A `POST` request to create a ruleset supports the following parameters in the request body: * `name` `String` * A human-readable name for the ruleset. * The name is immutable. You cannot change it over the lifetime of the ruleset. * `description` `String`Optional * Optional description for the ruleset. * You can change the description over the lifetime of the ruleset. * `kind` `String` * The kind of ruleset the JSON object represents. * Allowed values: * `custom`: Creates a custom ruleset * `root`: Creates a phase [entry point ruleset](https://mchen-ai-models-sync.previews.developers.cloudflare.com/ruleset-engine/about/rulesets/#entry-point-ruleset) at the account level * `zone`: Creates a phase entry point ruleset at the zone level * `phase` `String` * The name of the [phase](https://mchen-ai-models-sync.previews.developers.cloudflare.com/ruleset-engine/about/phases/) where the ruleset will be created. * Check the [phases list](https://mchen-ai-models-sync.previews.developers.cloudflare.com/ruleset-engine/reference/phases-list/) or the specific Cloudflare product documentation for more information on the phases where you can create rulesets for that product. * `rules` `Array`Optional * A list of [rules](https://mchen-ai-models-sync.previews.developers.cloudflare.com/ruleset-engine/rulesets-api/json-object/#rule-object-structure-and-properties) to include in the ruleset. For additional details on these parameters, refer to [JSON objects](https://mchen-ai-models-sync.previews.developers.cloudflare.com/ruleset-engine/rulesets-api/json-object/). ## Example - Create a custom ruleset The following `POST` request creates a custom ruleset in the `http_request_firewall_custom` phase at the account level containing a single rule. Required API token permissions At least one of the following [token permissions](https://mchen-ai-models-sync.previews.developers.cloudflare.com/fundamentals/api/reference/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` ```bash curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rulesets" \ --request POST \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "name": "Example custom ruleset", "kind": "custom", "description": "Example ruleset description", "rules": [ { "action": "log", "expression": "cf.zone.name eq \"example.com\"" } ], "phase": "http_request_firewall_custom" }' ``` ```json { "result": { "id": "", "name": "Example custom ruleset", "description": "Example ruleset description", "kind": "custom", "version": "1", "rules": [ { "id": "", "version": "1", "action": "log", "expression": "cf.zone.name eq \"example.com\"", "last_updated": "2025-03-17T15:42:37.917815Z" } ], "last_updated": "2025-03-17T15:42:37.917815Z", "phase": "http_request_firewall_custom" }, "success": true, "errors": [], "messages": [] } ``` ## Example - Create a zone-level phase entry point ruleset The following `POST` request creates a zone-level phase entry point ruleset at the `http_request_firewall_managed` phase with a single rule that executes a managed ruleset. Note You do not have to use this method to create a phase entry point ruleset. Cloudflare automatically creates the entry point ruleset when you add a rule to it, if it does not exist. Refer to [Add rules to phase entry point rulesets](https://mchen-ai-models-sync.previews.developers.cloudflare.com/ruleset-engine/basic-operations/add-rule-phase-rulesets/) for more information. Required API token permissions At least one of the following [token permissions](https://mchen-ai-models-sync.previews.developers.cloudflare.com/fundamentals/api/reference/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` ```bash curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets" \ --request POST \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "name": "Zone-level phase entry point", "kind": "zone", "description": "This ruleset executes a managed ruleset.", "rules": [ { "action": "execute", "expression": "true", "action_parameters": { "id": "" } } ], "phase": "http_request_firewall_managed" }' ``` ```json { "result": { "id": "", "name": "Zone-level phase entry point", "description": "This ruleset executes a managed ruleset.", "kind": "zone", "version": "1", "rules": [ { "id": "", "version": "1", "action": "execute", "expression": "true", "action_parameters": { "id": "" }, "last_updated": "2025-03-17T15:42:37.917815Z" } ], "last_updated": "2025-03-17T15:42:37.917815Z", "phase": "http_request_firewall_managed" }, "success": true, "errors": [], "messages": [] } ``` ## Example - Create an account-level phase entry point ruleset The following `POST` request creates an account-level phase entry point ruleset for the `http_ratelimit` phase with a single rule that executes a rate limiting ruleset for all Enterprise zones in the account. Note You do not have to use this method to create a phase entry point ruleset. Cloudflare automatically creates the entry point ruleset when you add a rule to it, if it does not exist. Refer to [Add rules to phase entry point rulesets](https://mchen-ai-models-sync.previews.developers.cloudflare.com/ruleset-engine/basic-operations/add-rule-phase-rulesets/) for more information. Required API token permissions At least one of the following [token permissions](https://mchen-ai-models-sync.previews.developers.cloudflare.com/fundamentals/api/reference/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` ```bash curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rulesets" \ --request POST \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "name": "Account-level phase entry point", "kind": "root", "description": "This ruleset executes a rate limiting ruleset.", "rules": [ { "action": "execute", "expression": "(cf.zone.plan eq \"ENT\")", "action_parameters": { "id": "" } } ], "phase": "http_ratelimit" }' ``` ```json { "result": { "id": "", "name": "Account-level phase entry point", "description": "This ruleset executes a rate limiting ruleset.", "kind": "root", "version": "1", "rules": [ { "id": "", "version": "1", "action": "execute", "expression": "(cf.zone.plan eq \"ENT\")", "action_parameters": { "id": "" }, "last_updated": "2024-09-17T15:42:37.917815Z" } ], "last_updated": "2024-09-17T15:42:37.917815Z", "phase": "http_ratelimit" }, "success": true, "errors": [], "messages": [] } ``` Caution You can only apply rate limiting 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 rate limiting ruleset. Was this helpful? YesNo ## On this page [![](https://mchen-ai-models-sync.previews.developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://mchen-ai-models-sync.previews.developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/ruleset-engine/rulesets-api/create/#page","headline":"Create a ruleset ยท Cloudflare Ruleset Engine docs","description":"Create a new ruleset using the Rulesets API.","url":"https://developers.cloudflare.com/ruleset-engine/rulesets-api/create/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-08-24","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ```