Create an HTTP Response Header Modification Rule via API
Use the Rulesets API to create HTTP Response Header Modification Rules via API. Define the header modification configuration in the action_parameters field. Refer to Response header modification examples for examples of rule definitions.
When creating an HTTP Response Header Modification Rule via API, make sure you:
- Set the rule action to
rewrite. - Define the header modification parameters in the
action_parametersfield according to the operation to perform (set, add, or remove header). - Deploy the rule to the
http_response_headers_transformphase at the zone level.
Follow this workflow to create an HTTP Response Header Modification Rule for a given zone via API:
Use the List existing rulesets method to check if there is already a ruleset for the
http_response_headers_transformphase at the zone level.If the phase ruleset does not exist, create it using the Create ruleset method with the zone-level endpoint. In the new ruleset properties, set the following values:
- kind:
zone - phase:
http_response_headers_transform
- kind:
Use the Update ruleset method to add an HTTP Response Header Modification Rule to the list of ruleset rules (check the examples below). Alternatively, include the rule in the Create ruleset request mentioned in the previous step.
Required API token permissions
The API token used in API requests to manage HTTP Response Header Modification Rules must have at least the following permissions:
- Transform Rules: Edit
- Account Rulesets: Read
Examples
Example: Set an HTTP response header to a static value
The following example configures the rules of an existing phase ruleset (<RULESET_ID>) to a single HTTP Response Header Modification Rule — setting an HTTP response header to a static value — using the Update ruleset method:
Requestcurl -X PUT \"https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/rulesets/<RULESET_ID>" \-H "Authorization: Bearer <API_TOKEN>" \-H "Content-Type: application/json" \-d '{ "rules": [ { "expression": "(starts_with(http.request.uri.path, \"/en/\"))", "description": "My first HTTP Response Header Modification Rule", "action": "rewrite", "action_parameters": { "headers": { "X-Source": { "operation": "set", "value": "Cloudflare" } } } } ]
}'The response contains the complete definition of the ruleset you updated.
Response{ "result": { "id": "<RULESET_ID>", "name": "Zone-level Response Headers Transform Ruleset", "description": "Zone-level ruleset that will execute Response Header Modification Rules.", "kind": "zone", "version": "2", "rules": [ { "id": "<RULE_ID>", "version": "1", "action": "rewrite", "action_parameters": { "headers": { "X-Source": { "operation": "set", "value": "Cloudflare" } } }, "expression": "(starts_with(http.request.uri.path, \"/en/\"))", "description": "My first HTTP Response Header Modification Rule", "last_updated": "2021-04-14T14:42:04.219025Z", "ref": "<RULE_REF>" } ], "last_updated": "2021-04-14T14:42:04.219025Z", "phase": "http_response_headers_transform" }, "success": true, "errors": [], "messages": []
}
Example: Set an HTTP response header to a dynamic value
The following example configures the rules of an existing phase ruleset (<RULESET_ID>) to a single HTTP Response Header Modification Rule — setting an HTTP response header to a dynamic value — using the Update ruleset method:
Requestcurl -X PUT \"https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/rulesets/<RULESET_ID>" \-H "Authorization: Bearer <API_TOKEN>" \-H "Content-Type: application/json" \-d '{ "rules": [ { "expression": "(starts_with(http.request.uri.path, \"/en/\"))", "description": "My first HTTP Response Header Modification Rule", "action": "rewrite", "action_parameters": { "headers": { "X-Bot-Score": { "operation": "set", "expression": "to_string(cf.bot_management.score)" } } } } ]
}'The response contains the complete definition of the ruleset you updated.
Response{ "result": { "id": "<RULESET_ID>", "name": "Zone-level Response Headers Transform Ruleset", "description": "Zone-level ruleset that will execute Response Header Modification Rules.", "kind": "zone", "version": "2", "rules": [ { "id": "<RULE_ID>", "version": "1", "action": "rewrite", "action_parameters": { "headers": { "X-Bot-Score": { "operation": "set", "expression": "to_string(cf.bot_management.score)" } } }, "expression": "(starts_with(http.request.uri.path, \"/en/\"))", "description": "My first HTTP Response Header Modification Rule", "last_updated": "2021-04-14T14:42:04.219025Z", "ref": "<RULE_REF>" } ], "last_updated": "2021-04-14T14:42:04.219025Z", "phase": "http_response_headers_transform" }, "success": true, "errors": [], "messages": []
}
Example: Add a set-cookie HTTP response header with a static value
The following example configures the rules of an existing phase ruleset (<RULESET_ID>) to a single HTTP Response Header Modification Rule — adding a set-cookie HTTP response header with a static value — using the Update ruleset method. By configuring the rule with the add operation you will keep any existing set-cookie headers that may already exist in the response.
Requestcurl -X PUT \"https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/rulesets/<RULESET_ID>" \-H "Authorization: Bearer <API_TOKEN>" \-H "Content-Type: application/json" \-d '{ "rules": [ { "expression": "(starts_with(http.request.uri.path, \"/en/\"))", "description": "My first HTTP Response Header Modification Rule", "action": "rewrite", "action_parameters": { "headers": { "set-cookie": { "operation": "add", "value": "mycookie=custom_value" } } } } ]
}'The response contains the complete definition of the ruleset you updated.
Response{ "result": { "id": "<RULESET_ID>", "name": "Zone-level Response Headers Transform Ruleset", "description": "Zone-level ruleset that will execute Response Header Modification Rules.", "kind": "zone", "version": "2", "rules": [ { "id": "<RULE_ID>", "version": "1", "action": "rewrite", "action_parameters": { "headers": { "set-cookie": { "operation": "add", "value": "mycookie=custom_value" } } }, "expression": "(starts_with(http.request.uri.path, \"/en/\"))", "description": "My first HTTP Response Header Modification Rule", "last_updated": "2021-04-14T14:42:04.219025Z", "ref": "<RULE_REF>" } ], "last_updated": "2021-04-14T14:42:04.219025Z", "phase": "http_response_headers_transform" }, "success": true, "errors": [], "messages": []
}
Example: Remove an HTTP response header
The following example sets the rules of an existing phase ruleset (<RULESET_ID>) to a single HTTP Response Header Modification Rule — removing an HTTP response header — using the Update ruleset method:
Requestcurl -X PUT \"https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/rulesets/<RULESET_ID>" \-H "Authorization: Bearer <API_TOKEN>" \-H "Content-Type: application/json" \-d '{ "rules": [ { "expression": "(starts_with(http.request.uri.path, \"/en/\"))", "description": "My first HTTP Response Header Modification Rule", "action": "rewrite", "action_parameters": { "headers": { "cf-connecting-ip": { "operation": "remove" } } } } ]
}'The response contains the complete definition of the ruleset you updated.
Response{ "result": { "id": "<RULESET_ID>", "name": "Zone-level Response Headers Transform Ruleset", "description": "Zone-level ruleset that will execute Response Header Modification Rules.", "kind": "zone", "version": "2", "rules": [ { "id": "<RULE_ID>", "version": "1", "action": "rewrite", "action_parameters": { "headers": { "cf-connecting-ip": { "operation": "remove" } } }, "expression": "(starts_with(http.request.uri.path, \"/en/\"))", "description": "My first HTTP Response Header Modification Rule", "last_updated": "2021-04-14T14:42:04.219025Z", "ref": "<RULE_REF>" } ], "last_updated": "2021-04-14T14:42:04.219025Z", "phase": "http_response_headers_transform" }, "success": true, "errors": [], "messages": []
}