Skip to content
Rules
Visit Rules on GitHub
Set theme to dark (⇧+D)

Create an HTTP Request Header Modification Rule via API

Use the Rulesets API to create HTTP Request Header Modification Rules via API. Define the header modification configuration in the action_parameters field. See Common use cases for example rule definitions.

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_parameters field according to the operation to perform (set or remove header)
  • Deploy the rule to the http_request_late_transform phase at the zone level

Create an HTTP Request Header Modification Rule

Follow this workflow to create an HTTP Request Header Modification Rule for a given zone via API:

  1. Use the List existing rulesets method to check if there is already a ruleset for the http_request_late_transform phase at the zone level.

  2. 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_request_late_transform
  3. Use the Update ruleset method to add an HTTP Request 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.

Examples

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 ruleset method:

Requestcurl -X PUT \-H "X-Auth-Email: user@cloudflare.com" \-H "X-Auth-Key: REDACTED" \"https://api.cloudflare.com/client/v4/zones/{zone-id}/rulesets/{ruleset-id}" \-d '{  "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 ruleset method:

Requestcurl -X PUT \-H "X-Auth-Email: user@cloudflare.com" \-H "X-Auth-Key: REDACTED" \"https://api.cloudflare.com/client/v4/zones/{zone-id}/rulesets/{ruleset-id}" \-d '{  "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 ruleset method:

Requestcurl -X PUT \-H "X-Auth-Email: user@cloudflare.com" \-H "X-Auth-Key: REDACTED" \"https://api.cloudflare.com/client/v4/zones/{zone-id}/rulesets/{ruleset-id}" \-d '{  "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": []}

Header modification parameters

To set an HTTP request header, set the following parameters in the action_parameters field:

  • operation: set

  • Include one of the following parameters to define a static or dynamic value:

    • value: Specifies a static value for the HTTP request header.
    • expression: Specifies the expression that defines a value for the HTTP request header.

To remove an HTTP request header, set the following parameter in the action_parameters field:

  • operation: remove

Static header value parameters

The full syntax of the action_parameters field to define a static HTTP request header value is the following:

"action_parameters": {  "headers": {    "<HEADER_NAME>": {      "operation": "set",      "value": "<URI_PATH_VALUE>"    }  }}

Dynamic header value parameters

The full syntax of the action_parameters field to define a dynamic HTTP request header value using an expression is the following:

"action_parameters": {  "headers": {    "<HEADER_NAME>": {       "operation": "set",      "expression": "<EXPRESSION>"    }  }}

Header removal parameters

The full syntax of the action_parameters field to remove an HTTP request header is the following:

"action_parameters": {  "headers": {    "<HEADER_NAME>": {       "operation": "remove"    }  }}

Different header modifications in the same rule

The same rule can modify different HTTP request headers using different operations (set or remove a header). For example, a single rule can set the value of a header and remove a different header. The syntax of such a rule could be the following:

"action_parameters": {  "headers": {    "<HEADER_NAME_1>": {       "operation": "set",      "value": "<HEADER_VALUE_1>"    },     "<HEADER_NAME_2>": {      "operation": "remove"    }  }}