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:

Operation	Method + Endpoint
Create an account ruleset	POST /accounts/{account_id}/rulesets
Create a zone ruleset	POST /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.

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.

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 for more information.

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.

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 for more information.

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": []
}

Warning

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.