Criar, atualizar e excluir redirecionamentos em massa com a API

1. Obtenha um token e teste-o#

Crie um token conforme descrito em Crie e gerencie tokens de API. Cada token pertence a um workspace. Mantenha-o no seu servidor, nunca no código do navegador.

bashexport REDIRHUB_TOKEN="your-token"

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

2. Crie um redirecionamento#

Para um redirecionamento, url é a origem (um domínio, ou um domínio e um caminho, sem https://) e destination é a URL de destino completa. Um domínio sem caminho redireciona todos os caminhos nele.

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"]
  }'

A resposta retorna o novo link dentro de um array data, com seu id. Use handler migration para mapeamentos de migração de site e short-url ou qr (com host e alias em vez de url) para links de marca e códigos QR.

3. Crie centenas a partir de um arquivo#

Percorra um CSV com as mesmas colunas da importação do painel (source_url, destination, type) e envie uma solicitação por linha. Mantenha-se dentro dos limites de taxa e tente novamente em caso de 429. Para uma importação única, a importação de CSV no painel é mais rápida e mostra uma revisão antes.

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. Encontrar 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"

Os resultados são paginados por cursor: siga meta.cursor.next até ficar vazio. Outros filtros incluem tags, destination, search, created_after e created_before; veja Filtragem e ordenação.

5. Alterar um 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"}'

A URL de origem de um link não pode ser alterada após sua criação. Para mover uma origem, crie um novo link e exclua o antigo.

6. Alterar vários destinos de uma só vez#

Pré-visualize primeiro. POST /bulk/summary retorna quantos links o filtro corresponde, quantos tiveram visitas nas últimas quatro semanas e as cinco primeiras alterações:

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"
  }'

Em seguida, envie o mesmo corpo para PUT /bulk para aplicá-lo. A resposta informa quantos links foram afetados. Para adicionar parâmetros UTM a cada destino, em vez disso, envie destination_params, por exemplo {"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. Excluir em massa#

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

Pelo menos um filtro deve ter um valor, para que uma solicitação não corresponda por engano ao workspace inteiro. A resposta retorna affected (links excluídos) e pending (links que ainda estão sendo removidos em segundo plano).

Trabalhando a partir de um assistente de IA em vez disso#

O servidor MCP da RedirHub permite que Claude, ChatGPT ou Cursor façam as mesmas tarefas em linguagem simples, incluindo importar até cerca de 5.000 linhas em uma única chamada. Alterações em massa via MCP sempre retornam primeiro uma execução de teste e só são aplicadas depois que você confirmar.

Referência completa: referência da API da RedirHub.