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:
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
- kind:
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:
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": "(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:
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, \"/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