Migrate redirects from another host
When a site moves to Edge, its old URLs need to keep working. Search engines and old links should land on the new pages instead of a 404. This page imports a redirect list in one go, checks it, and makes it live.
Throughout, the distribution is acme-marketing (d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38), and the old host exported its rules to redirects.csv:
from,to,status
/pricing-2025,/pricing,302
/about-us,/about,302
/blog/*,/news/:splat,302Edge also reads Netlify _redirects files and JSON. The exact formats are on Redirects.
Where you can do this
Importing redirects is not available in the web console. Use an agent, the CLI or the API.
1. Check the file
An import is a dry run unless you say otherwise. It changes nothing and reports:
- the rules it would add, change and remove;
- every error, with its line number;
- loops and long redirect chains;
- off-site targets that are not allowed.
Check redirects.csv as a redirect import for acme-marketing. Do not apply it yet;
show me the errors and warnings.edge redirects import acme-marketing redirects.csvcurl -s -X POST \
https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/redirects/import \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d "$(jq -n --rawfile source redirects.csv '{source: $source, format: "csv"}')"The agent runs edge_redirect_import with dry_run left at true. A report looks like this:
{
"dry_run": true,
"valid": true,
"parsed": 3,
"rule_count": 3,
"added": [ { "from": "/pricing-2025", "to": "/pricing", "status": 302 }, … ],
"changed": [],
"removed": [],
"errors": [],
"warnings": [],
"kvs_bytes": 212
}Fix every entry in errors in the file and check again. Common ones:
| Error | Fix |
|---|---|
line 7: from must be a path starting with / | The old host exported a full URL. Keep only the path. |
redirect loop: /a -> /b -> /a | Two rules point at each other. Remove one. |
shop.acme.example is not this distribution, … | Attach or verify that domain, or add it to the distribution's redirect_hosts. |
status 200: rewrites (200) and custom error pages are not supported | Edge redirects only. Drop the line. |
The file above uses 302, so browsers do not cache the redirects while you are checking them. Use 301 once you are sure. Browsers cache a 301 with no expiry, so a wrong one is hard to take back.
By default the import merges: existing rules with the same from are updated and the rest are kept. To make the file the whole table, use mode: "replace" (CLI --replace). removed then shows what would go.
2. Apply it
Apply redirects.csv to acme-marketing. Do not promote it yet.edge redirects import acme-marketing redirects.csv --applycurl -s -X POST \
https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/redirects/import \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d "$(jq -n --rawfile source redirects.csv '{source: $source, format: "csv", dry_run: false}')"The agent runs edge_redirect_import with dry_run: false. If the file still has errors, nothing is created. Otherwise the response includes a deployment_id. That deployment carries the new redirect table. The live site has not changed yet.
3. Check the new deployment
Ask the new deployment where some old URLs go before promoting it:
On acme-marketing deployment 01M4T7B2QX9K3R5N8W0YHDVJCE, where do /blog/spring-launch
and /pricing-2025?utm_source=mail redirect?edge redirects check acme-marketing "/blog/spring-launch" --deployment 01M4T7B2QX9K3R5N8W0YHDVJCE
edge redirects check acme-marketing "/pricing-2025?utm_source=mail" --deployment 01M4T7B2QX9K3R5N8W0YHDVJCEcurl -s -G \
https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/redirect-check \
-H "Authorization: Bearer $EDGE_TOKEN" \
--data-urlencode "path=/blog/spring-launch" \
--data-urlencode "deployment_id=01M4T7B2QX9K3R5N8W0YHDVJCE"The agent runs edge_redirect_check. It uses the same matching as the edge:
{ "matched": true, "rule": { "from": "/blog/*", "to": "/news/:splat", "status": 302 }, "location": "/news/spring-launch", "status": 302 }You can also open the deployment's preview URL and follow a few old links in the browser.
4. Promote
Promote the deployment as usual. See Patch, promote, and roll back. The redirects go live with it. To cut over at a set time, for example together with a DNS change, schedule the promote instead. See Schedule a launch and a takedown.
If something is wrong after promoting, rolling back brings back the previous redirect table along with the previous deployment.
Export and edit later
To change the table later, export it, edit the file, and import it again:
Export acme-marketing's redirects as CSV.edge redirects export acme-marketing > redirects.csvcurl -s "https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/redirects/export?format=csv" \
-H "Authorization: Bearer $EDGE_TOKEN" | jq -r .contentThe agent runs edge_redirect_export.
Next
- Redirects: rule format, matching order and status codes
- Attach a custom domain
- Limits