Skip to content
Cloudflare Docs

Create ruleset

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:

OperationMethod + Endpoint
Create an account rulesetPOST /accounts/{account_id}/rulesets
Create a zone rulesetPOST /zones/{zone_id}/rulesets

The following parameters are required:

  • 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 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 at the account level
      • zone: Creates a phase entry point ruleset at the zone level
  • phase String
    • The name of the phase where the ruleset will be created.
    • Check the specific Cloudflare product documentation for more information on the phases where you can create rulesets for that product.

Use the rules parameter to supply a list of rules for the ruleset. For an object definition, refer to Rulesets API: JSON Object.

Example - Create a custom ruleset

The following POST request creates a custom ruleset in the http_request_firewall_custom phase containing a single rule.

Terminal window
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/rulesets \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "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"
}'
{
  "result": {
    "id": "<RULESET_ID>",
    "name": "Example custom ruleset",
    "description": "Example ruleset description",
    "kind": "custom",
    "version": "1",
    "rules": [
      {
        "id": "<RULE_ID>",
        "version": "1",
        "action": "log",
        "expression": "cf.zone.name eq \"example.com\"",
        "last_updated": "2021-03-17T15:42:37.917815Z"
      }
    ],
    "last_updated": "2021-03-17T15:42:37.917815Z",
    "phase": "http_request_firewall_custom"
  },
  "success": true,
  "errors": [],
  "messages": []
  "result": {
    "id": "<RULESET_ID>",
    "name": "Example custom ruleset",
    "description": "Example ruleset description",
    "kind": "custom",
    "version": "1",
    "rules": [
      {
        "id": "<RULE_ID>",
        "version": "1",
        "action": "log",
        "expression": "cf.zone.name eq \"example.com\"",
        "last_updated": "2021-03-17T15:42:37.917815Z"
      }
    ],
    "last_updated": "2021-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.

Terminal window
curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "name": "Zone-level phase entry point",
  "kind": "zone",
  "description": "This ruleset executes a managed ruleset.",
  "rules": [
    {
      "action": "execute",
      "expression": "true",
      "action_parameters": {
        "id": "<MANAGED_RULESET_ID>"
      }
    }
  ],
  "phase": "http_request_firewall_managed"
}'
{
  "result": {
    "id": "<RULESET_ID>",
    "name": "Zone-level phase entry point",
    "description": "This ruleset executes a managed ruleset.",
    "kind": "zone",
    "version": "1",
    "rules": [
      {
        "id": "<RULE_ID>",
        "version": "1",
        "action": "execute",
        "expression": "true",
        "action_parameters": {
          "id": "<MANAGED_RULESET_ID>"
        },
        "last_updated": "2021-03-17T15:42:37.917815Z"
      }
    ],
    "last_updated": "2021-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.

Terminal window
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/rulesets \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "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": "<RATE_LIMITING_RULESET_ID>"
      }
    }
  ],
  "phase": "http_ratelimit"
}'
{
  "result": {
    "id": "<RULESET_ID>",
    "name": "Account-level phase entry point",
    "description": "This ruleset executes a rate limiting ruleset.",
    "kind": "root",
    "version": "1",
    "rules": [
      {
        "id": "<RULE_ID>",
        "version": "1",
        "action": "execute",
        "expression": "(cf.zone.plan eq \"ENT\")",
        "action_parameters": {
          "id": "<RATE_LIMITING_RULESET_ID>"
        },
        "last_updated": "2024-09-17T15:42:37.917815Z"
      }
    ],
    "last_updated": "2024-09-17T15:42:37.917815Z",
    "phase": "http_ratelimit"
  },
  "success": true,
  "errors": [],
  "messages": []
}