Documentação

Referência da API

Crie e gerencie redirecionamentos, caminhos personalizados e QR codes pelo seu próprio código. Uma API REST pequena, com JSON na entrada e na saída.

Visão geral

Tudo o que você faz no painel com redirecionamentos, caminhos personalizados e QR codes também pode ser feito pela API: criar um redirecionamento quando um cliente se cadastra, adicionar caminhos de campanha por um script ou gerar QR codes para impressão em lote.

URL base

https://api.redirect-301.com/v1

Formato

Corpo das requisições e respostas em JSON (Content-Type: application/json). Datas em UTC, ISO 8601.

Planos

Incluída nos planos Studio e Enterprise.

Mesmas regras

A API segue as mesmas regras do painel, como a quantidade de redirecionamentos do seu plano.

Autenticação

Toda requisição precisa de uma chave de API, enviada no cabeçalho Authorization como token Bearer.

No painel, abra Chaves de API no menu à esquerda.
Clique em Criar chave e dê um nome que diga onde ela será usada, como “Zapier” ou “CMS”.
Copie a chave na hora: por segurança, ela é mostrada só uma vez. Você pode ter até 10 chaves ativas.

Terminal

export R301_KEY="r301_…"   # your key, from the dashboard

Teste sua chave

curl https://api.redirect-301.com/v1/me \
  -H "Authorization: Bearer $R301_KEY"

Resposta

{
  "email": "you@example.com",
  "plan": "studio",
  "maxRedirects": 5
}

Trate as chaves como senhas: guarde no seu servidor, nunca em uma página ou app que outras pessoas possam inspecionar. Se uma chave vazar, revogue no painel; ela para de funcionar na hora.

Erros e limites

Chamadas bem-sucedidas retornam 200, 201 (criado) ou 204 (excluído, sem corpo). Erros têm sempre o mesmo formato: um code estável que seu código pode verificar e uma message legível.

Resposta de erro

{
  "error": {
    "code": "plan_limit_reached",
    "message": "Your plan allows 5 redirect(s)."
  }
}

Status	Código	Quando
400	`validation_error`	Um campo está faltando ou é inválido. A mensagem diz qual.
401	`invalid_api_key`	Sem chave, ou a chave está errada ou foi revogada.
403	`api_not_enabled`	Seu plano atual não inclui a API.
403	`account_inactive`	A conta está inativa (por exemplo, a assinatura foi cancelada).
404	`not_found`	O redirecionamento, caminho ou QR code não existe na sua conta.
409	`plan_limit_reached`	Você já tem tantos redirecionamentos quanto o seu plano permite.
409	`host_taken`	O domínio já está cadastrado.
409	`path_exists`	Esse caminho já existe no redirecionamento.
429	`rate_limited`	Requisições demais: aguarde os segundos do cabeçalho `Retry-After`.

Cada chave pode fazer 60 requisições por minuto.

Redirecionamentos

Um redirecionamento envia toda visita a um dos seus domínios (host) para outra URL (redirectTo). Ele é identificado pelo nome do domínio.

GET/redirectsLista seus redirecionamentos, com o maxRedirects do seu plano.

POST/redirectsCria um redirecionamento.

GET/redirects/{host}Retorna um redirecionamento.

PATCH/redirects/{host}Altera redirectTo, redirectType, followPath ou followQueryString.

DELETE/redirects/{host}Exclui o redirecionamento, com seus caminhos, QR codes e estatísticas.

GET/redirects/{host}/statusEstado do DNS e do certificado (veja abaixo).

Campo	Tipo	Descrição
`host`	string	O domínio que redireciona, como `marca-antiga.com.br`. Obrigatório na criação; não pode ser alterado.
`redirectTo`	string	URL de destino completa (`http://` ou `https://`), em outro domínio. Obrigatório na criação.
`redirectType`	number	`301` (permanente, o padrão) ou `302` (temporário).
`followPath`	boolean	Mantém o caminho visitado: `marca-antiga.com.br/sobre` → `marca-nova.com.br/sobre`. Padrão `true`.
`followQueryString`	boolean	Mantém a query string (`?utm_source=…`). Padrão `true`.
`status`	string	`not_configured` (DNS ainda não aponta), `pending` (certificado sendo emitido), `active`, `disabled` ou `error`. Somente leitura.
`dns`	object	O registro DNS a criar no seu provedor de domínio. Somente leitura.

Criar um redirecionamento

curl -X POST https://api.redirect-301.com/v1/redirects \
  -H "Authorization: Bearer $R301_KEY" \
  -H "Content-Type: application/json" \
  -d '{"host": "old-brand.com", "redirectTo": "https://new-brand.com"}'

Resposta · 201

{
  "host": "old-brand.com",
  "redirectTo": "https://new-brand.com",
  "redirectType": 301,
  "followPath": true,
  "followQueryString": true,
  "status": "not_configured",
  "dns": { "type": "A", "name": "old-brand.com", "value": "18.215.89.131" },
  "certificateExpiresAt": null,
  "errorMessage": null,
  "createdAt": "2026-09-26T14:02:11"
}

Depois crie o registro A de dns no seu provedor de domínio. Assim que o domínio aponta para nós, emitimos o certificado HTTPS e o status passa para pending e depois active. Chame o endpoint de status para verificar o DNS e já iniciar o certificado:

Verificar DNS e certificado

curl https://api.redirect-301.com/v1/redirects/old-brand.com/status \
  -H "Authorization: Bearer $R301_KEY"

Resposta

{
  "host": "old-brand.com",
  "status": "pending",
  "dns": {
    "expected": { "type": "A", "name": "old-brand.com", "value": "18.215.89.131" },
    "resolved": ["18.215.89.131"],
    "pointing": true
  },
  "certificate": { "expiresAt": null },
  "errorMessage": null
}

Alterar um redirecionamento

curl -X PATCH https://api.redirect-301.com/v1/redirects/old-brand.com \
  -H "Authorization: Bearer $R301_KEY" \
  -H "Content-Type: application/json" \
  -d '{"redirectType": 302, "followPath": false}'

Caminhos personalizados

Um caminho personalizado envia um caminho do seu domínio para um lugar específico, como marca-antiga.com.br/promo → marca-nova.com.br/liquidacao. Os outros caminhos continuam seguindo a regra principal do redirecionamento.

GET/redirects/{host}/pathsLista os caminhos do redirecionamento.

POST/redirects/{host}/pathsCria um caminho.

PATCH/redirects/{host}/paths/{id}Altera qualquer campo.

DELETE/redirects/{host}/paths/{id}Exclui o caminho e os QR codes que apontam para ele.

Campo	Tipo	Descrição
`fromPath`	string	O caminho no seu domínio, como `/promo`. A `/` inicial é adicionada se faltar; caminhos não diferenciam maiúsculas e são únicos por redirecionamento. Obrigatório.
`redirectTo`	string	Para onde vai. Um caminho no destino do redirecionamento (`/liquidacao`), ou uma URL completa quando `absolute` é `true`. Obrigatório.
`absolute`	boolean	`true` para enviar o caminho para qualquer URL, até em outro domínio. Padrão `false`.
`statusCode`	number	`301` (padrão), `302`, `307` ou `308`.

Criar um caminho

curl -X POST https://api.redirect-301.com/v1/redirects/old-brand.com/paths \
  -H "Authorization: Bearer $R301_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fromPath": "/promo", "redirectTo": "/summer-sale"}'

Resposta · 201

{
  "id": 42,
  "fromPath": "/promo",
  "redirectTo": "/summer-sale",
  "absolute": false,
  "statusCode": 301,
  "createdAt": "2026-09-26T14:05:40"
}

QR codes

Um QR code abre o domínio do redirecionamento, ou um dos seus caminhos personalizados. Cada QR code tem sua própria url com uma marca ?_qr=, então os scans dele são contados separadamente nas suas estatísticas; a marca é removida antes de o visitante ser redirecionado.

GET/redirects/{host}/qr-codesLista os QR codes do redirecionamento.

POST/redirects/{host}/qr-codesCria um QR code.

PATCH/redirects/{host}/qr-codes/{id}Altera qualquer campo. Envie "pathId": null para voltar a apontar para o domínio.

DELETE/redirects/{host}/qr-codes/{id}Exclui o QR code.

GET/redirects/{host}/qr-codes/{id}/imageA imagem: format=png (padrão) ou svg, size em pixels de 64 a 2048 (padrão 512).

Campo	Tipo	Descrição
`label`	string	O nome que você dá, como “Flyer A5”. Obrigatório.
`pathId`	number	O caminho personalizado que ele abre. Omita (ou `null`) para o próprio domínio.
`color`	string	Cor hexadecimal do código, como `#0A0E14` (o padrão).
`format`	string	Formato de download preferido no painel: `png`, `svg` ou `pdf`.
`url`	string	O que o QR code codifica. Somente leitura.

Criar um QR code

curl -X POST https://api.redirect-301.com/v1/redirects/old-brand.com/qr-codes \
  -H "Authorization: Bearer $R301_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "Flyer A5", "pathId": 42, "color": "#0A0E14"}'

Resposta · 201

{
  "id": 7,
  "label": "Flyer A5",
  "pathId": 42,
  "color": "#0A0E14",
  "format": "png",
  "url": "https://old-brand.com/promo?_qr=7",
  "imageUrl": "/v1/redirects/old-brand.com/qr-codes/7/image",
  "createdAt": "2026-09-26T14:07:02"
}

Baixar a imagem

curl -o flyer.png "https://api.redirect-301.com/v1/redirects/old-brand.com/qr-codes/7/image?format=png&size=1024" \
  -H "Authorization: Bearer $R301_KEY"

As imagens são geradas na hora e não expiram, então você pode baixar de novo quando quiser. Depois de imprimir um QR code, mantenha-o: o código impresso continua redirecionando depois de excluído, mas os scans deixam de ser contados, e se você excluir o caminho dele ele passa a abrir o destino principal do redirecionamento.

← Voltar ao início

Suporte

Precisa de ajuda?

Fique à vontade para entrar em contato com qualquer dúvida. Estamos aqui para ajudar! Escaneie o QR code ou clique no botão abaixo para entrar no nosso grupo do WhatsApp.

Abrir WhatsApp →