Skip to content
Cloudflare Docs

Create a URL rewrite rule via API

Use the Rulesets API to create URL Rewrite Rules via API. Refer to the Rules examples gallery for common use cases.

If you are using Terraform, refer to Transform Rules configuration using Terraform.

Basic rule settings

When creating a URL rewrite 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 URL rewrite 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 URL rewrite 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 URL rewrite rule — performing a static rewrite of the URI path — using the Update a zone ruleset operation. The response will contain the complete definition of the ruleset you updated.

Required API token permissions

 At least one of the following token permissions is required:
  • Response Compression Write
  • Config Settings Write
  • Dynamic URL Redirects Write
  • Cache Settings Write
  • Custom Errors Write
  • Origin Write
  • Managed headers Write
  • Zone Transform Rules Write
  • Mass URL Redirects Write
  • Magic Firewall Write
  • L4 DDoS Managed Ruleset Write
  • HTTP DDoS Managed Ruleset Write
  • Sanitize Write
  • Transform Rules Write
  • Select Configuration Write
  • Bot Management Write
  • Zone WAF Write
  • Account WAF Write
  • Account Rulesets Write
  • Logs Write
  • Logs Write
Update a zone ruleset
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID" \
  --request PUT \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "rules": [
        {
            "expression": "(http.request.uri.query contains \"eu\")",
            "description": "My first static URL rewrite rule",
            "action": "rewrite",
            "action_parameters": {
                "uri": {
                    "path": {
                        "value": "/emea.html"
                    }
                }
            }
        }
    ]
  }'
{
  "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 URL rewrite 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 URL rewrite rule — performing a dynamic rewrite of the URI path — using the Update a zone ruleset operation. The response will contain the complete definition of the ruleset you updated.

Required API token permissions

 At least one of the following token permissions is required:
  • Response Compression Write
  • Config Settings Write
  • Dynamic URL Redirects Write
  • Cache Settings Write
  • Custom Errors Write
  • Origin Write
  • Managed headers Write
  • Zone Transform Rules Write
  • Mass URL Redirects Write
  • Magic Firewall Write
  • L4 DDoS Managed Ruleset Write
  • HTTP DDoS Managed Ruleset Write
  • Sanitize Write
  • Transform Rules Write
  • Select Configuration Write
  • Bot Management Write
  • Zone WAF Write
  • Account WAF Write
  • Account Rulesets Write
  • Logs Write
  • Logs Write
Update a zone ruleset
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID" \
  --request PUT \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "rules": [
        {
            "expression": "starts_with(http.request.uri.path, \"/news/2012/\")",
            "description": "My first dynamic URL rewrite rule",
            "action": "rewrite",
            "action_parameters": {
                "uri": {
                    "path": {
                        "expression": "concat(\"/archive\", http.request.uri.path)"
                    }
                }
            }
        }
    ]
  }'
{
  "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 URL rewrite 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 URL Rewrite Rules must have at least the following permissions:

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