Use the [Rulesets API](https://developers.cloudflare.com/ruleset-engine/rulesets-api/) to create a redirect rule via API.

Add redirect rules to the entry point ruleset of the `http_request_dynamic_redirect` phase at the zone level. Refer to the [Rulesets API](https://developers.cloudflare.com/ruleset-engine/rulesets-api/) documentation for more information on [creating a ruleset](https://developers.cloudflare.com/ruleset-engine/rulesets-api/create/) and supplying a list of rules for the ruleset.

Note

Single Redirects require that the incoming traffic for the hostname referenced in visitors' requests is [proxied by Cloudflare](https://developers.cloudflare.com/dns/proxy-status/).

## Basic rule settings

A redirect rule must have:

* `action` set to `redirect`
* An `action_parameters` object with additional configuration settings — refer to [Available settings](https://developers.cloudflare.com/rules/url-forwarding/single-redirects/settings/) for details.

## Example requests

The following request of the [Create a zone ruleset](https://developers.cloudflare.com/api/resources/rulesets/methods/create/) operation creates a phase entry point ruleset for the `http_request_dynamic_redirect` phase at the zone level, and defines a single redirect rule with a dynamic URL redirect. Use this operation if you have not created a phase entry point ruleset for the `http_request_dynamic_redirect` phase yet.

```bash
curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "name": "Redirect rules ruleset",
    "kind": "zone",
    "phase": "http_request_dynamic_redirect",
    "rules": [
        {
            "expression": "(ip.src.country eq \"GB\" or ip.src.country eq \"FR\") and http.request.uri.path eq \"/\"",
            "description": "Redirect GB and FR users in home page to localized site.",
            "action": "redirect",
            "action_parameters": {
                "from_value": {
                    "target_url": {
                        "expression": "lower(concat(\"https://\", ip.src.country, \".example.com\"))"
                    },
                    "status_code": 307,
                    "preserve_query_string": true
                }
            }
        }
    ]
  }'
```

If there is already a phase entry point ruleset for the `http_request_dynamic_redirect` phase, use the [Update a zone ruleset](https://developers.cloudflare.com/api/resources/rulesets/methods/update/) operation instead, like in the following example:

```bash
curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID \
  --request PUT \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "name": "Redirect rules ruleset",
    "kind": "zone",
    "phase": "http_request_dynamic_redirect",
    "rules": [
        {
            "expression": "(ip.src.country eq \"GB\" or ip.src.country eq \"FR\") and http.request.uri.path eq \"/\"",
            "description": "Redirect GB and FR users in home page to localized site.",
            "action": "redirect",
            "action_parameters": {
                "from_value": {
                    "target_url": {
                        "expression": "lower(concat(\"https://\", ip.src.country, \".example.com\"))"
                    },
                    "status_code": 307,
                    "preserve_query_string": true
                }
            }
        },
        {
            "expression": "http.request.uri.path eq \"/contacts.html\"",
            "description": "Redirect to new contacts page.",
            "action": "redirect",
            "action_parameters": {
                "from_value": {
                    "target_url": {
                        "value": "https://example.com/contact-us/"
                    },
                    "status_code": 308
                }
            }
        }
    ]
  }'
```

***

## Required API token permissions

The API token used in API requests to manage redirect rules must have at least the following permission:

* *Zone* > *Single Redirect* > *Edit*
