Create a rule via API

Use the Rulesets API to create a Cache Response Rule via API. To configure the Cloudflare API, refer to the API documentation.

When creating a Cache Response Rule via API, make sure you:

• Set the rule action to one of the available actions.
• Define the parameters in the action_parameters field according to the settings you wish to configure for matching responses.
• Deploy the rule to the http_response_cache_settings phase entry point ruleset.

1. Use the List zone rulesets method to check if a ruleset already exists for the http_response_cache_settings phase.
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_response_cache_settings
3. Use the Update a zone ruleset operation to add rules to the ruleset. Alternatively, include the rules in the Create a zone ruleset request mentioned in the previous step.

These examples demonstrate all the available actions in Cache Response Rules using request and response matching criteria. Using these examples directly will cause any existing rules in the phase to be replaced.

Example: Strip response headers from JS files before caching

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_response_cache_settings/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"rules": [
				{
						"expression": "http.request.uri.path.extension eq \"js\"",
						"description": "Strip caching headers from JS files",
						"action": "set_cache_settings",
						"action_parameters": {
								"strip_etags": true,
								"strip_set_cookie": true,
								"strip_last_modified": true
						}
				}
		]
	}'

Example: Set static cache tags on API responses

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_response_cache_settings/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"rules": [
				{
						"expression": "http.request.uri.path starts_with \"/api/\"",
						"description": "Tag API responses for targeted purging",
						"action": "set_cache_tags",
						"action_parameters": {
								"operation": "set",
								"values": [
										"api-response",
										"dynamic-content"
								]
						}
				}
		]
	}'

Example: Add cache tags from a response header using an expression

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_response_cache_settings/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"rules": [
				{
						"expression": "any(http.response.headers.names[*] == \"Surrogate-Keys\")",
						"description": "Extract cache tags from alternative CDN response header",
						"action": "set_cache_tags",
						"action_parameters": {
								"operation": "add",
								"expression": "split(http.response.headers[\"Surrogate-Keys\"][0], \",\", 1)"
						}
				}
		]
	}'

Example: Override cache-control with max-age

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_response_cache_settings/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"rules": [
				{
						"expression": "http.response.code eq 200",
						"description": "Override cache-control for successful responses",
						"action": "set_cache_control",
						"action_parameters": {
								"max-age": {
										"operation": "set",
										"value": 3600,
										"cloudflare_only": true
								}
						}
				}
		]
	}'

Example: Set private directive with qualifiers

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_response_cache_settings/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"rules": [
				{
						"expression": "http.request.uri.path starts_with \"/user/\"",
						"description": "Mark user content as private",
						"action": "set_cache_control",
						"action_parameters": {
								"private": {
										"operation": "set",
										"qualifiers": [
												"X-User-Id",
												"X-Session-Token"
										]
								},
								"no-cache": {
										"operation": "set"
								}
						}
				}
		]
	}'

Example: Set immutable for static font assets

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_response_cache_settings/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"rules": [
				{
						"expression": "http.request.uri.path.extension in {\"woff2\" \"woff\" \"ttf\"}",
						"description": "Mark fonts as immutable",
						"action": "set_cache_control",
						"action_parameters": {
								"immutable": {
										"operation": "set"
								},
								"max-age": {
										"operation": "set",
										"value": 31536000
								}
						}
				}
		]
	}'

Example: Multiple rules with strip headers, tag responses, and set cache control

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_response_cache_settings/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"rules": [
				{
						"expression": "http.response.code eq 200 and http.request.uri.path.extension eq \"html\"",
						"description": "Strip tracking headers from HTML responses",
						"action": "set_cache_settings",
						"action_parameters": {
								"strip_etags": true,
								"strip_set_cookie": true
						}
				},
				{
						"expression": "http.request.uri.path starts_with \"/products/\"",
						"description": "Tag product pages for purging",
						"action": "set_cache_tags",
						"action_parameters": {
								"operation": "add",
								"values": [
										"product-catalog",
										"storefront"
								]
						}
				},
				{
						"expression": "http.response.code eq 200",
						"description": "Set cache control for all 200 responses",
						"action": "set_cache_control",
						"action_parameters": {
								"s-maxage": {
										"operation": "set",
										"value": 86400,
										"cloudflare_only": true
								},
								"must-revalidate": {
										"operation": "set"
								}
						}
				}
		]
	}'

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

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