导航|地址|刷新
Create a URL rewrite rule via API

Skip to contentDocumentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/rules/llms.txt
Use this file to discover all available pages before exploring further.

Docs Directory API SDKs Changelog

Search

Log in

Rules

/

Overview

Examples

Configuration Rules

Overview

Create a rule in the dashboard

Create a rule via API

Available settings

Examples

Overview

Define a single configuration rule using Terraform

Snippets

Overview

How it works

Create in the dashboard

Configure via API

Configure using Terraform

Examples

Troubleshooting

When to use Snippets vs Workers

Transform Rules

Overview

Rewrite URLs

Overview

Create a rule in the dashboard

Create a rule via API

Create a rule using Terraform ↗

Reference

URL rewrite parameters

Available fields and functions

Modify request headers

Overview

Create a rule in the dashboard

Create a rule via API

Create a rule using Terraform ↗

Reference

Format of header names and values

Available fields and functions

API parameter reference

Modify response headers

Overview

Create a rule in the dashboard

Create a rule via API

Create a rule using Terraform ↗

Reference

Format of header names and values

Available fields and functions

API parameter reference

Managed Transforms

Overview

Configure Managed Transforms

Available Managed Transforms

Troubleshooting

Examples

Overview

Add a request header for subrequests from other zones

Add a request header with the current bot score

Add a response header with a static value

Add a wildcard CORS response header

Add request header with a static value

Normalize encoded slashes in URL path

Remove a request header

Remove a response header

Rewrite blog archive URLs

Rewrite image paths with several URL segments

Rewrite page path for visitors in specific countries

Rewrite path for object storage bucket

Rewrite path of archived blog posts

Rewrite path of moved section of a website

Rewrite URL query string

Set a response header with the current bot score

Set response header with a static value

Redirects

Overview

Single Redirects

Overview

Create rule in the dashboard

Create rule via API

Create rule using Terraform

Available settings

Bulk Redirects

Overview

Concepts

How it works

Create in the dashboard

Create via API

Configure using Terraform

Reference

URL redirect parameters

Supported URL components

Available fields and functions

CSV file format

API JSON objects

FAQ

Examples

Overview

Perform mobile redirects

Redirect admin area requests to HTTPS

Redirect from root to WWW

Redirect from WWW to root

Redirect local visitors to specific subdomains

Redirect requests for a domain to a new domain

Redirect requests from one country to a domain

Redirect requests from one domain to another

Redirect requests to a different hostname

Redirect visitors to a new page URL

Remove locale from URL path

Origin Rules

Overview

Create a rule in the dashboard

Create a rule via API

Examples

Overview

Change the destination port

Change the HTTP Host header and DNS record

Define a single origin rule using Terraform

Tutorials

Overview

Change URI path and Host header

Point to Pages with a custom domain

Point to R2 bucket with a custom domain

Available settings

API parameter reference

FAQ

Cache Rules ↗

Cloud ConnectorBeta

Overview

Configure a rule in the dashboard

Configure a rule via API

Configure rules using Terraform

Supported cloud providers

Examples

Overview

Route /images to an S3 Bucket

Route /images to an S3 Bucket using Terraform

Send EU visitors to a Google Cloud Storage bucket

Serve /static-assets from Azure Blob Storage

Custom Errors

Overview

Edit Error Pages

Create custom error rules

Example rules

Common API calls

Reference

Parameters

Error tokens

Error page types

Troubleshooting

Compression Rules

Overview

Create a rule in the dashboard

Create a rule via API

Available settings

Examples

Overview

Disable Brotli compression

Disable compression for AVIF images

Enable Zstandard compression for default content types

Use Gzip compression for CSV files

Use only Brotli compression for a specific path

Page Rules

Overview

Manage

How to

URL forwarding

Reference

Settings

Additional reference

Wildcard matching

Recommended rules

Troubleshooting

General

Billing and subscription

URL normalization

Overview

How it works

Configure in the dashboard

Settings

Examples

Trace a requestBeta

Overview

Use Cloudflare Trace

Limitations

Changelog

Reference

Rules language ↗

Troubleshooting

Page Rules migration guide

Changelog

Agent resources

Agent setup ↗

Cloudflare Skills ↗

Code Mode MCP Server ↗

Domain-specific MCP Servers ↗MCP

Rules llms.txt ↗

Rules llms-full.txt ↗

Cloudflare Docs llms.txt ↗

Cloudflare Docs llms-full.txt ↗

Home

/Rules

/…
Transform Rules

/Rewrite URLs

/Create a rule via API

Create a URL rewrite rule via API

Last updated May 5, 2026|Copy as Markdown|View as Markdown|Agent setup

OverviewBasic rule settingsProcedureExample requestsRequired API token permissions

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:

Use the List zone rulesets operation to check if there is already a ruleset for the http_request_transform phase 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_transform

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 rulesetbashcurl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID" \ --request PUT \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "rules": [ { "ref": "rewrite_eu_to_emea", "expression": "(http.request.uri.query contains \"eu\")", "description": "My first static URL rewrite rule", "action": "rewrite", "action_parameters": { "uri": { "path": { "value": "/emea.html" } } } } ] }'{ "result": { "ref": "rewrite_eu_to_emea", "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": []}
Use the ref field to get stable rule IDs across updates when using Terraform. Adding this field prevents Terraform from recreating the rule on changes. For more information, refer to Troubleshooting in the Terraform documentation.

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 rulesetbashcurl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID" \ --request PUT \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "rules": [ { "ref": "rewrite_2012_to_archive", "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": [ { "ref": "rewrite_2012_to_archive", "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": []}
Use the ref field to get stable rule IDs across updates when using Terraform. Adding this field prevents Terraform from recreating the rule on changes. For more information, refer to Troubleshooting in the Terraform documentation.

------

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

PreviousCreate a rule in the dashboardNextCreate a rule using Terraform ↗

Was this helpful?

YesNo

Edit pageReport issue

On this page

Overview

Basic rule settings

Procedure

Example requests

Required API token permissions

Edit pageReport issue

Getting started
PlansContact salesPartnersFind a partnerStartupsUnder attack?Domain name search

Company
AboutCareersInvestorsPressPress kitGlobal network

Public interest
Project GalileoAthenian ProjectCloudflare for CampaignsProject FairshotImpact/ESG

Compliance
Compliance resourcesTrust HubData ProtectionResponsible AITransparency reportReport abuse

Resources
App innovation reportCloudflare RadarCase studiesStatusSupportEventsBlog

Developers
DocumentationLearning centerCommunity

Solutions
SSE and SASE platformCloudflare AI CloudAI SecurityFrontend Development PlatformMulti-Tenant Platform DevelopmentWeb Security Platform

Start BuildingLog In

…(内容过长已截断)

------
导航页打开网址