---
title: Create Bulk Redirects via API
description: Learn how to create Bulk Redirects using the Cloudflare API.
image: https://edgetunnel-b2h.pages.dev/core-services-preview.png
---

> Documentation Index  
> Fetch the complete documentation index at: https://edgetunnel-b2h.pages.dev/rules/llms.txt  
> Use this file to discover all available pages before exploring further. 

[Skip to content](#%5Ftop) 

# Create Bulk Redirects via API

To create Bulk Redirects via API, you must:

1. Create a Bulk Redirect List via API.
2. Add items (URL redirects) to the list created in step 1.
3. Create a Bulk Redirect Rule via API, which enables the list created in step 1.

Note

Bulk Redirects require that the incoming traffic for the hostname referenced in visitors' requests is [proxied by Cloudflare](https://edgetunnel-b2h.pages.dev/dns/proxy-status/).

## 1\. Create a Bulk Redirect List via API

Use the [Create a list](https://edgetunnel-b2h.pages.dev/api/resources/rules/subresources/lists/methods/create/) operation to create a new Bulk Redirect List. The list `kind` must be `redirect`.

Required API token permissions

At least one of the following [token permissions](https://edgetunnel-b2h.pages.dev/fundamentals/api/reference/permissions/) is required: 
* `Account Filter Lists Edit`

**Create a list**

```bash
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rules/lists" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "name": "my_redirect_list",
    "description": "My redirect list.",
    "kind": "redirect"
  }'
```

```json
{
  "result": {
    "id": "f848b6ccb07647749411f504d6f88794",
    "name": "my_redirect_list",
    "description": "My redirect list.",
    "kind": "redirect",
    "num_items": 0,
    "num_referencing_filters": 0,
    "created_on": "2021-10-28T09:11:42Z",
    "modified_on": "2021-10-28T09:11:42Z"
  },
  "success": true,
  "errors": [],
  "messages": []
}
```

Take note of the list ID — you will need it in the next step.

For more information on list operations, refer to the [Lists API](https://edgetunnel-b2h.pages.dev/waf/tools/lists/lists-api/) documentation.

## 2\. Add items to the list

Use the [Create list items](https://edgetunnel-b2h.pages.dev/api/resources/rules/subresources/lists/subresources/items/methods/create/) operation to add URL redirect items to the list. Enter the list ID from the previous step in the endpoint URL:

Required API token permissions

At least one of the following [token permissions](https://edgetunnel-b2h.pages.dev/fundamentals/api/reference/permissions/) is required: 
* `Account Filter Lists Edit`

**Create list items**

```bash
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rules/lists/f848b6ccb07647749411f504d6f88794/items" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '[
    {
        "redirect": {
            "source_url": "example.com/blog/",
            "target_url": "https://example.com/blog/latest"
        }
    },
    {
        "redirect": {
            "source_url": "example.net/",
            "target_url": "https://example.net/under-construction.html",
            "status_code": 307
        }
    }
  ]'
```

```json
{
  "result": {
    "operation_id": "92558f8b296d4dbe9d0419e0e53f6622"
  },
  "success": true,
  "errors": [],
  "messages": []
}
```

This is an asynchronous operation. The response will contain an `operation_id` which you will use to check if the operation completed successfully using the [Get bulk operation status](https://edgetunnel-b2h.pages.dev/api/resources/rules/subresources/lists/subresources/bulk%5Foperations/methods/get/) operation:

Required API token permissions

At least one of the following [token permissions](https://edgetunnel-b2h.pages.dev/fundamentals/api/reference/permissions/) is required: 
* `Account Filter Lists Edit`
* `Account Filter Lists Read`

**Get bulk operation status**

```bash
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rules/lists/bulk_operations/92558f8b296d4dbe9d0419e0e53f6622" \
  --request GET \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

Once the operation has completed successfully, the response will be similar to the following:

**Response**

```json
{
  "result": {
    "id": "92558f8b296d4dbe9d0419e0e53f6622",
    "status": "completed",
    "completed": "2021-10-28T09:15:42Z"
  },
  "success": true,
  "errors": [],
  "messages": []
}
```

## 3\. Create a Bulk Redirect Rule via API

Since Bulk Redirect Lists are essentially containers of URL redirects, you have to enable the URL redirects in the list by creating a Bulk Redirect Rule.

Add Bulk Redirect Rules to the [entry point ruleset](https://edgetunnel-b2h.pages.dev/ruleset-engine/about/rulesets/#entry-point-ruleset) of the `http_request_redirect` phase at the account level. Refer to the [Rulesets API](https://edgetunnel-b2h.pages.dev/ruleset-engine/rulesets-api/) documentation for more information on [creating a ruleset](https://edgetunnel-b2h.pages.dev/ruleset-engine/rulesets-api/create/) and supplying a list of rules for the ruleset.

A Bulk Redirect Rule must have:

* `action` set to `redirect`
* An `action_parameters` object with additional configuration settings — refer to [Bulk Redirects API JSON objects](https://edgetunnel-b2h.pages.dev/rules/url-forwarding/bulk-redirects/reference/json-objects/#bulk-redirect-rule) for details.

The following request of the [Create an account ruleset](https://edgetunnel-b2h.pages.dev/api/resources/rulesets/methods/create/) operation creates a phase entry point ruleset for the `http_request_redirect` phase at the account level, and defines a single redirect rule. Use this operation if you have not created a phase entry point ruleset for the `http_request_redirect` phase yet.

Required API token permissions

At least one of the following [token permissions](https://edgetunnel-b2h.pages.dev/fundamentals/api/reference/permissions/) is required: 
* `Mass URL Redirects Write`
* `Magic Firewall Write`
* `L4 DDoS Managed Ruleset Write`
* `Transform Rules Write`
* `Select Configuration Write`
* `Account WAF Write`
* `Account Rulesets Write`
* `Logs Write`

**Create an account ruleset**

```bash
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rulesets" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "name": "My redirect ruleset",
    "kind": "root",
    "phase": "http_request_redirect",
    "rules": [
        {
            "ref": "enable_my_redirect_list",
            "expression": "http.request.full_uri in $my_redirect_list",
            "description": "Bulk Redirect rule.",
            "action": "redirect",
            "action_parameters": {
                "from_list": {
                    "name": "my_redirect_list",
                    "key": "http.request.full_uri"
                }
            }
        }
    ]
  }'
```

```json
{
  "result": {
    "id": "528f4f03bf0da53a29907199625867be",
    "name": "My redirect ruleset",
    "kind": "root",
    "version": "1",
    "rules": [
      {
        "ref": "enable_my_redirect_list",
        "id": "8da312df846b4258a05bcd454ea943be",
        "version": "1",
        "expression": "http.request.full_uri in $my_redirect_list",
        "description": "Bulk Redirect rule.",
        "action": "redirect",
        "action_parameters": {
          "from_list": {
            "name": "my_redirect_list",
            "key": "http.request.full_uri"
          }
        },
        "last_updated": "2021-10-28T09:20:42Z"
      }
    ],
    "last_updated": "2021-10-28T09:20:42Z",
    "phase": "http_request_redirect"
  },
  "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](https://edgetunnel-b2h.pages.dev/terraform/troubleshooting/rule-id-changes/#how-to-keep-the-same-rule-id-between-modifications) in the Terraform documentation.

If there is already a phase entry point ruleset for the `http_request_redirect` phase, use the [Update an account ruleset](https://edgetunnel-b2h.pages.dev/api/resources/rulesets/methods/update/) operation instead, like in the following example:

Required API token permissions

At least one of the following [token permissions](https://edgetunnel-b2h.pages.dev/fundamentals/api/reference/permissions/) is required: 
* `Mass URL Redirects Write`
* `Magic Firewall Write`
* `L4 DDoS Managed Ruleset Write`
* `Transform Rules Write`
* `Select Configuration Write`
* `Account WAF Write`
* `Account Rulesets Write`
* `Logs Write`

**Update an account ruleset**

```bash
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rulesets/$RULESET_ID" \
  --request PUT \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "name": "My redirect ruleset",
    "kind": "root",
    "phase": "http_request_redirect",
    "rules": [
        {
            "ref": "eval_redirects_list_1",
            "expression": "http.request.full_uri in $my_redirect_list_1",
            "description": "Bulk Redirect rule 1",
            "action": "redirect",
            "action_parameters": {
                "from_list": {
                    "name": "my_redirect_list_1",
                    "key": "http.request.full_uri"
                }
            }
        },
        {
            "ref": "eval_redirects_list_2",
            "expression": "http.request.full_uri in $my_redirect_list_2",
            "description": "Bulk Redirect rule 2",
            "action": "redirect",
            "action_parameters": {
                "from_list": {
                    "name": "my_redirect_list_2",
                    "key": "http.request.full_uri"
                }
            }
        }
    ]
  }'
```

```json
{
  "result": {
    "id": "67013aa153df4e5fbda92f92bc979331",
    "name": "default",
    "description": "",
    "kind": "root",
    "version": "2",
    "rules": [
      {
        "ref": "eval_redirects_list_1",
        "id": "8be62ab2ef9a4a41af30c24ff8e73e41",
        "version": "1",
        "action": "redirect",
        "action_parameters": {
          "from_list": {
            "name": "my_redirect_list_1",
            "key": "http.request.full_uri"
          }
        },
        "expression": "http.request.full_uri in $my_redirect_list_1",
        "description": "Bulk Redirect rule 1",
        "last_updated": "2021-12-03T15:38:51.658387Z",
        "ref": "8be62ab2ef9a4a41af30c24ff8e73e41",
        "enabled": true
      },
      {
        "ref": "eval_redirects_list_2",
        "id": "97e38797fb2b4b22a4919800f1318a5c",
        "version": "1",
        "action": "redirect",
        "action_parameters": {
          "from_list": {
            "name": "my_redirect_list_2",
            "key": "http.request.full_uri"
          }
        },
        "expression": "http.request.full_uri in $my_redirect_list_2",
        "description": "Bulk Redirect rule 2",
        "last_updated": "2021-12-03T15:38:51.658387Z",
        "ref": "97e38797fb2b4b22a4919800f1318a5c",
        "enabled": true
      }
    ],
    "last_updated": "2021-12-03T15:38:51.658387Z",
    "phase": "http_request_redirect"
  },
  "success": true,
  "errors": [],
  "messages": []
}
```

---

## Required API token permissions

The API token used in API requests to manage Bulk Redirects objects (lists, list items, and rules) must have at least the following [permissions](https://edgetunnel-b2h.pages.dev/fundamentals/api/reference/permissions/):

* [ Dashboard ](#tab-panel-10931)
* [ API ](#tab-panel-10932)

* _Account_ \> _Bulk URL Redirects_ \> _Edit_
* _Account_ \> _Account Filter Lists_ \> _Edit_

* Mass URL Redirects Write
* Account Rule Lists Write

```json
{"@context":"https://schema.org","@type":"TechArticle","@id":"https://edgetunnel-b2h.pages.dev/rules/url-forwarding/bulk-redirects/create-api/#page","headline":"Create Bulk Redirects via API · Cloudflare Rules docs","description":"Learn how to create Bulk Redirects using the Cloudflare API.","url":"https://edgetunnel-b2h.pages.dev/rules/url-forwarding/bulk-redirects/create-api/","inLanguage":"en","image":"https://edgetunnel-b2h.pages.dev/core-services-preview.png","dateModified":"2026-05-05","publisher":{"@type":"Organization","name":"Cloudflare","url":"https://www.cloudflare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://edgetunnel-b2h.pages.dev/#website","name":"Cloudflare Docs","url":"https://edgetunnel-b2h.pages.dev/"},"keywords":["Redirects"]}
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/rules/","name":"Rules"}},{"@type":"ListItem","position":3,"item":{"@id":"/rules/url-forwarding/","name":"Redirects"}},{"@type":"ListItem","position":4,"item":{"@id":"/rules/url-forwarding/bulk-redirects/","name":"Bulk Redirects"}},{"@type":"ListItem","position":5,"item":{"@id":"/rules/url-forwarding/bulk-redirects/create-api/","name":"Create Bulk Redirects via API"}}]}
```