Create an HTTP request header modification rule via API
Use the Rulesets API to create HTTP request header modification rules via API. Refer to Request header modification examples for common use cases.
Basic rule settings
When creating an HTTP request 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 or remove header). - Deploy the rule to the
http_request_late_transformphase at the zone level.
Procedure
Follow this workflow to create an HTTP request header modification rule for a given zone via API:
-
Use the List zone rulesets operation to check if there is already a ruleset for the
http_request_late_transformphase at the zone level. -
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_late_transform
- kind:
-
Use the Update a zone ruleset operation to add an HTTP request header modification 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 an HTTP request header with a static value
The following example sets the rules of an existing phase ruleset ({ruleset_id}) to a single HTTP request header modification rule — adding an HTTP request header with a static value — using the
Update a zone ruleset operation:
Requestcurl --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.path, \"/en/\"))", "description": "My first HTTP request 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 Late Transform Ruleset", "description": "Zone-level ruleset that will execute Late Transform 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 request header modification rule", "last_updated": "2021-04-14T14:42:04.219025Z", "ref": "<RULE_REF>" } ], "last_updated": "2021-04-14T14:42:04.219025Z", "phase": "http_request_late_transform" }, "success": true, "errors": [], "messages": []
}
Example: Add an HTTP request header with a dynamic value
The following example sets the rules of an existing phase ruleset ({ruleset_id}) to a single HTTP request header modification rule — adding an HTTP request header with a dynamic value — using the
Update a zone ruleset operation:
Requestcurl --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.path, \"/en/\"))", "description": "My first HTTP request 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 Late Transform Ruleset", "description": "Zone-level ruleset that will execute Late Transform 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 request header modification rule", "last_updated": "2021-04-14T14:42:04.219025Z", "ref": "<RULE_REF>" } ], "last_updated": "2021-04-14T14:42:04.219025Z", "phase": "http_request_late_transform" }, "success": true, "errors": [], "messages": []
}
Example: Remove an HTTP request header
The following example sets the rules of an existing phase ruleset ({ruleset_id}) to a single HTTP request header modification rule — removing an HTTP request header — using the
Update a zone ruleset:
Requestcurl --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.path, \"/en/\"))", "description": "My first HTTP request 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 Late Transform Ruleset", "description": "Zone-level ruleset that will execute Late Transform 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 request header modification rule", "last_updated": "2021-04-14T14:42:04.219025Z", "ref": "<RULE_REF>" } ], "last_updated": "2021-04-14T14:42:04.219025Z", "phase": "http_request_late_transform" }, "success": true, "errors": [], "messages": []
}
Required API token permissions
The API token used in API requests to manage HTTP request header modification rules must have at least the following permissions:
- Transform Rules > Edit
- Account Rulesets > Read