Skip to content
Cloudflare Docs

Create a rule via API

Use the Rulesets API ↗ to create a cache rule via API. To configure Cloudflare’s API refer to the API documentation.

Basic rule settings

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

  • Set the rule action to set_cache_settings.
  • 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_request_cache_settings phase entry point ruleset.

Procedure

  1. Use the List zone rulesets method to obtain the list of rules already present in the http_request_cache_settings phase entry point ruleset.
  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_request_cache_settings
  3. Use the Update a zone ruleset operation to add a cache rule to the list of ruleset rules. Alternatively, include the rule in the Create a zone ruleset request mentioned in the previous step.
  4. (Optional) To update an existing cache rule, use the Update a zone ruleset rule operation. For an example, refer to the section below.

Example requests

These examples are setting all the Cache Rules of a zone to a single rule, since using these examples directly will cause any existing rules to be deleted.

Example: Cache everything for example.com
Request
curl --request PUT \
https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id} \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "rules": [
    {
      "expression": "(http.host eq \"example.com\")",
      "description": "cache everything for example.com",
      "action": "set_cache_settings",
      "action_parameters": {
        "cache": true
      }
    }
  ]
}'

Example: Extend read timeout for Android clients
Request
curl --request PUT \
https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id} \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "rules": [
    {
      "expression": "(http.user_agent contains \"Android\")",
      "description": "extend read timeout for android clients",
      "action": "set_cache_settings",
      "action_parameters": {
        "cache": true,
        "read_timeout": 300
      }
    }
  ]
}'

Example: Disable Cache Reserve for frequently updated assets
Request
curl --request PUT \
https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id} \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "rules": [
    {
      "expression": "(starts_with(http.request.uri, \"/feed/\"))",
      "description": "disable cache reserve for frequently updated assets",
      "action": "set_cache_settings",
      "action_parameters": {
        "cache": true,
        "cache_reserve": {
          "enabled": false
        }
      }
    }
  ]
}'

Example: Turn off default cache TTLs
Request
curl --request PUT \
https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id} \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "rules": [
    {
      "expression": "(http.host eq \"example.com\")",
      "description": "turn off default cache ttls",
      "action": "set_cache_settings",
      "action_parameters": {
        "cache": true,
        "edge_ttl": {
          "mode": "bypass_by_default"
        }
      }
    }
  ]
}'

Example: Update the position of an existing rule
Request
curl --request PATCH \
https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id}/rules/{rule_id} \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
      "expression": "(http.host eq \"example.com\")",
      "description": "cache everything for example.com",
      "action": "set_cache_settings",
      "action_parameters": {
        "cache": true
      }
      "enabled": true,
      "position": {
        "before": "da5e8e506c8e7877fe06cdf4c41add54"
      }
}'

Required API token permissions

The API token used in API requests to manage Cache Rules must have the following permissions:

  • Zone > Cache Rules > Edit
  • Account Rulesets > Edit
  • Account Filter Lists > Edit