Cloudflare Docs
Rules
Rules
Edit this page on GitHub
Set theme to dark (⇧+D)

Create a rewrite URL rule via API

Use the Rulesets API to create rewrite URL rules via API. Refer to URL rewrite examples for common use cases.

​​ Basic rule settings

When creating a rewrite URL rule via API, make sure you:

  • Set the rule action to rewrite.
  • Define the URL rewrite parameters in the action_parameters field according to the type of URL rewrite (static or dynamic).
  • Deploy the rule to the http_request_transform phase at the zone level.

​​ Procedure

Follow this workflow to create a rewrite URL rule for a given zone via API:

  1. Use the List zone rulesets operation to check if there is already a ruleset for the http_request_transform phase at the zone level.

  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_transform
  3. Use the Update a zone ruleset operation to add a rewrite URL 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 a rule that performs a static URL rewrite

The following example sets the rules of an existing phase ruleset ({ruleset_id}) to a single rewrite URL rule — performing a static rewrite of the URI path — using the Update a zone ruleset operation:

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.request.uri.query contains \"eu\")",
"description": "My first static rewrite URL rule",
"action": "rewrite",
"action_parameters": {
"uri": {
"path": {
"value": "/emea.html"
}
}
}
}
]
}'

The response contains the complete definition of the ruleset you updated.

Response
{
"result": {
"id": "<RULESET_ID>",
"name": "Zone-level Transform Ruleset",
"description": "Zone-level ruleset that will execute Transform Rules.",
"kind": "zone",
"version": "2",
"rules": [
{
"id": "<RULE_ID>",
"version": "1",
"action": "rewrite",
"action_parameters": {
"uri": {
"path": {
"value": "/emea.html"
}
}
},
"expression": "(http.request.uri.query contains \"eu\")",
"description": "My first static rewrite URL rule",
"last_updated": "2021-04-14T14:42:04.219025Z",
"ref": "<RULE_REF>"
}
],
"last_updated": "2021-04-14T14:42:04.219025Z",
"phase": "http_request_transform"
},
"success": true,
"errors": [],
"messages": []
}
Example: Add a rule that performs a dynamic URL rewrite

The following example sets the rules of an existing phase ruleset ({ruleset_id}) to a single rewrite URL rule — performing a dynamic rewrite of the URI path — using the Update a zone ruleset operation:

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.path, \"/news/2012/\")",
"description": "My first dynamic rewrite URL rule",
"action": "rewrite",
"action_parameters": {
"uri": {
"path": {
"expression": "concat(\"/archive\", http.request.uri.path)"
}
}
}
}
]
}'

The response contains the complete definition of the ruleset you updated.

Response
{
"result": {
"id": "<RULESET_ID>",
"name": "Zone-level Transform Ruleset",
"description": "Zone-level ruleset that will execute Transform Rules.",
"kind": "zone",
"version": "2",
"rules": [
{
"id": "<RULE_ID>",
"version": "1",
"action": "rewrite",
"action_parameters": {
"uri": {
"path": {
"expression": "concat(\"/archive\", http.request.uri.path)"
}
}
},
"expression": "starts_with(http.request.uri.path, \"/news/2012/\")",
"description": "My first dynamic rewrite URL rule",
"last_updated": "2021-04-14T14:42:04.219025Z",
"ref": "<RULE_REF>"
}
],
"last_updated": "2021-04-14T14:42:04.219025Z",
"phase": "http_request_transform"
},
"success": true,
"errors": [],
"messages": []
}

​​ Required API token permissions

The API token used in API requests to manage rewrite URL rules must have at least the following permissions:

  • Account > Transform Rules > Edit
  • Account > Account Rulesets > Read