Create, update and delete redirects in bulk with the API

1. Get a token and test it#

Create a token as described in Create and manage API tokens. Each token belongs to one workspace. Keep it on your server, never in browser code.

bashexport REDIRHUB_TOKEN="your-token"

curl "https://api.redirhub.com/v1/test" \
  -H "Authorization: Bearer $REDIRHUB_TOKEN"

2. Create one redirect#

For a redirect, url is the source (a domain, or a domain and path, without https://) and destination is the full target URL. A bare domain redirects every path on it.

bashcurl -X POST "https://api.redirhub.com/v1/links" \
  -H "Authorization: Bearer $REDIRHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "handler": "redirect",
    "url": "old-site.com/pricing",
    "destination": "https://new-site.com/pricing",
    "type": "301",
    "forward_query": true,
    "tags": ["migration"]
  }'

The response returns the new link inside a data array, with its id. Use handler migration for website-migration mappings and short-url or qr (with host and alias instead of url) for branded links and QR codes.

3. Create hundreds from a file#

Loop over a CSV with the same columns as the dashboard import (source_url, destination, type) and send one request per row. Stay within the rate limits and retry on 429. For a one-off import, the CSV import in the dashboard is quicker and shows a review first.

pythonimport csv, os, time, requests

API = "https://api.redirhub.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['REDIRHUB_TOKEN']}"}

with open("redirects.csv", newline="") as f:
    for row in csv.DictReader(f):
        body = {
            "handler": "redirect",
            "url": row["source_url"],
            "destination": row["destination"],
            "type": row.get("type") or "301",
        }
        while True:
            r = requests.post(f"{API}/links", json=body, headers=HEADERS)
            if r.status_code != 429:
                break
            time.sleep(int(r.headers.get("Retry-After", 5)))
        print(row["source_url"], r.status_code, r.json().get("errors", ""))

4. Find links#

bashcurl -G "https://api.redirhub.com/v1/links" \
  -H "Authorization: Bearer $REDIRHUB_TOKEN" \
  --data-urlencode "filter[host]=old-site.com" \
  --data-urlencode "filter[handler]=redirect"

Results are cursor-paginated: follow meta.cursor.next until it is empty. Other filters include tags, destination, search, created_after and created_before; see Filtering & sorting.

5. Change one link#

bashcurl -X PUT "https://api.redirhub.com/v1/links/LINK_ID" \
  -H "Authorization: Bearer $REDIRHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"destination": "https://new-site.com/plans"}'

The source URL of a link can't be changed after it is created. To move a source, create a new link and delete the old one.

6. Change many destinations at once#

Preview first. POST /bulk/summary returns how many links the filter matches, how many had visits in the last four weeks, and the first five changes:

bashcurl -X POST "https://api.redirhub.com/v1/bulk/summary" \
  -H "Authorization: Bearer $REDIRHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"tags": "migration"},
    "destination_find": "new-site.com",
    "destination_replace": "new-brand.com"
  }'

Then send the same body to PUT /bulk to apply it. The response tells you how many links were affected. To add UTM parameters to every destination instead, send destination_params, for example {"utm_campaign": "fall-2026"}.

bashcurl -X PUT "https://api.redirhub.com/v1/bulk" \
  -H "Authorization: Bearer $REDIRHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"tags": "migration"},
    "destination_find": "new-site.com",
    "destination_replace": "new-brand.com"
  }'

7. Delete in bulk#

bashcurl -X DELETE "https://api.redirhub.com/v1/bulk" \
  -H "Authorization: Bearer $REDIRHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filter": {"tags": "summer-sale"}}'

At least one filter must have a value, so a request can't match the whole workspace by accident. The response returns affected (links deleted) and pending (links still being removed in the background).

Working from an AI assistant instead#

The RedirHub MCP server lets Claude, ChatGPT or Cursor do the same jobs in plain language, including importing up to about 5,000 rows in one call. Bulk changes through MCP always return a dry run first and apply only after you confirm.

Full reference: RedirHub API reference.