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 example request creates a custom ruleset in the http_request_firewall_custom phase containing a single rule.

Request

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"
}'

Response

{
  "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 example 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.

Request

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"
}'

Response

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