Create Bulk Redirects via API
To create Bulk Redirects via API, you must:
- Create a Bulk Redirect List via API.
- Add items (URL redirects) to the list created in step 1.
- Create a Bulk Redirect Rule via API, which enables the list created in step 1.
1. Create a Bulk Redirect List via API
Use the
Create a list operation to create a new Bulk Redirect List. The list kind must be redirect.
Requestcurl https://api.cloudflare.com/client/v4/accounts/{account_id}/rules/lists \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{ "name": "my_redirect_list", "description": "My redirect list.", "kind": "redirect"}'
The response will be similar to the following:
Response{ "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 documentation.
2. Add items to the list
Use the Create list items operation to add URL redirect items to the list. Enter the list ID from the previous step in the endpoint URL:
Requestcurl https://api.cloudflare.com/client/v4/accounts/{account_id}/rules/lists/f848b6ccb07647749411f504d6f88794/items \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '[ { "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 } }]'
The response will be similar to the following:
Response{ "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 operation:
Requestcurl https://api.cloudflare.com/client/v4/accounts/{account_id}/rules/lists/bulk_operations/92558f8b296d4dbe9d0419e0e53f6622 \
--header "Authorization: Bearer <API_TOKEN>"
If the operation already completed successfully, the response will be similar to the following:
Response{ "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 of the http_request_redirect phase at the account level. Refer to the Rulesets API documentation for more information on creating a ruleset and supplying a list of rules for the ruleset.
A Bulk Redirect Rule must have:
actionset toredirect- An
action_parametersobject with additional configuration settings — refer to API JSON objects: Bulk Redirect Rule for details.
The following request of the
Create an account ruleset 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.
Requestcurl https://api.cloudflare.com/client/v4/accounts/{account_id}/rulesets \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{ "name": "My redirect ruleset", "kind": "root", "phase": "http_request_redirect", "rules": [ { "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" } } } ]}'
The response will be similar to the following:
Response{ "result": { "id": "528f4f03bf0da53a29907199625867be", "name": "My redirect ruleset", "kind": "root", "version": "1", "rules": [ { "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": []
}
If there is already a phase entry point ruleset for the http_request_redirect phase, use the
Update an account ruleset operation instead, like in the following example:
Requestcurl --request PUT \https://api.cloudflare.com/client/v4/accounts/{account_id}/rulesets/{ruleset_id} \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{ "name": "My redirect ruleset", "kind": "root", "phase": "http_request_redirect", "rules": [ { "expression": "http.request.full_uri in $my_redirect_list_2", "description": "Bulk Redirect rule 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_2", "description": "Bulk Redirect rule 2", "action": "redirect", "action_parameters": { "from_list": { "name": "my_redirect_list_2", "key": "http.request.full_uri" } } } ]}'
The response will be similar to the following:
Response{ "result": { "id": "67013aa153df4e5fbda92f92bc979331", "name": "default", "description": "", "kind": "root", "version": "2", "rules": [ { "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 }, { "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:
- Account > Account Rulesets > Edit
- Account > Account Filter Lists > Edit