Create a rule via API

Use the Rulesets API to create configuration rules via API.

Basic rule settings

When creating a configuration rule via API, make sure you:

• Set the rule action to set_config.
• Define the parameters in the action_parameters field according to the settings you wish to override for matching requests.
• Deploy the rule to the http_config_settings phase at the zone level.

Procedure

Follow this workflow to create a configuration rule for a given zone via API:

1. Use the List zone rulesets operation to check if there is already a ruleset for the http_config_settings phase at the zone level.

2. If the phase ruleset does not exist, create it using the Create a zone ruleset operation. In the new ruleset properties, set the following values:

   • kind: zone
   • phase: http_config_settings

3. Use the Update a zone ruleset operation to add a configuration rule to the list of ruleset rules. Alternatively, include the rule in the Create a zone ruleset request mentioned in the previous step.

Make sure your API token has the required permissions to perform the API operations.

Example requests

Example: Add a rule that enables Email Obfuscation and Browser Integrity Check

The following example sets the rules of an existing phase ruleset ({ruleset_id}) to a single configuration rule — enabling Email Obfuscation and Browser Integrity Check for the contacts page — using the Update a zone ruleset operation:

Required API token permissions

At least one of the following token 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

Update a zone ruleset

curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID \
  --request PUT \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "rules": [
        {
            "expression": "starts_with(http.request.uri.path, \"/contact-us/\")",
            "description": "Obfuscates email addresses and enables BIC in contacts page",
            "action": "set_config",
            "action_parameters": {
                "email_obfuscation": true,
                "bic": true
            }
        }
    ]
  }'

Example: Add a rule that turns on Under Attack mode for the admin area

The following example sets the rules of an existing phase ruleset ({ruleset_id}) to a single configuration rule — turning on Under Attack mode for the administration area — using the Update a zone ruleset operation:

Required API token permissions

At least one of the following token 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

Update a zone ruleset

curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID \
  --request PUT \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "rules": [
        {
            "expression": "http.host eq \"admin.example.com\"",
            "description": "Turn on Under Attack mode for admin area",
            "action": "set_config",
            "action_parameters": {
                "security_level": "under_attack"
            }
        }
    ]
  }'

---

Required API token permissions

The API token used in API requests to manage configuration rules must have at least the following permission:

• Zone > Config Rules > Edit