Documentação

Referência da API

Crie e gerencie redirecionamentos, caminhos personalizados, QR codes e páginas 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, QR codes e as páginas que eles mostram 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, QR code ou página 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, noDestination, 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, a menos que `noDestination` seja `true`.
`noDestination`	boolean	Quando `true`, o domínio responde 404 (não encontrado), exceto nos seus caminhos para uma URL ou página e nos QR codes. O `redirectTo` é mantido, então voltar para `false` restaura o redirecionamento. Padrão `false`.
`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",
  "noDestination": false,
  "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.

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. `/q` e os caminhos dentro dele são reservados para QR codes.
`redirectTo`	string	Para onde vai. Um caminho no destino do redirecionamento (`/liquidacao`; responde 404 quando o redirecionamento não tem destino), ou uma URL completa quando `absolute` é `true`. Obrigatório, a menos que `pageId` seja enviado; `null` nas respostas quando o caminho mostra uma página.
`pageId`	number	Uma das suas páginas (veja Páginas), mostrada no caminho em vez de redirecionar. Envie `redirectTo` ou `pageId`, não os dois. No PATCH, `pageId` troca o caminho para essa página e `redirectTo` volta para uma URL. `null` quando o caminho redireciona.
`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",
  "pageId": null,
  "absolute": false,
  "statusCode": 301,
  "createdAt": "2026-09-26T14:05:40"
}

Mostrar uma página no caminho

curl -X PATCH https://api.redirect-301.com/v1/redirects/old-brand.com/paths/42 \
  -H "Authorization: Bearer $R301_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pageId": 27}'

Resposta

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

QR codes

Um QR code é um endereço curto no domínio do redirecionamento, https://{host}/q/{code}, que envia cada scan para o seu próprio redirectTo. Mude o redirectTo quando quiser, mesmo depois de impresso: o código impresso continua o mesmo. Os scans são contados por QR code nas suas estatísticas.

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 label, redirectTo, pageId, color ou format. O code nunca muda.

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.
`redirectTo`	string	URL completa (`http://` ou `https://`) para onde os scans vão. Obrigatório na criação, a menos que `pageId` seja enviado; `null` nas respostas quando o QR code mostra uma página.
`pageId`	number	Uma das suas páginas (veja Páginas), mostrada quando o código é lido em vez de redirecionar. Envie `redirectTo` ou `pageId`, não os dois. No PATCH, `pageId` troca para essa página e `redirectTo` volta para uma URL.
`code`	string	O código curto no endereço, gerado por nós. Somente leitura.
`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", "redirectTo": "https://new-brand.com/summer-sale", "color": "#0A0E14"}'

Resposta · 201

{
  "id": 7,
  "label": "Flyer A5",
  "code": "Kp7xQm",
  "redirectTo": "https://new-brand.com/summer-sale",
  "pageId": null,
  "color": "#0A0E14",
  "format": "png",
  "url": "https://old-brand.com/q/Kp7xQm",
  "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: se você excluí-lo, o código impresso deixa de funcionar.

Páginas

Uma página é uma página de links no estilo link na bio (perfil, botões, itens de cardápio, fotos…) que você monta no painel, em Páginas. Um caminho personalizado ou um QR code pode mostrar uma página em vez de redirecionar: o visitante vê a página direto nesse endereço do seu domínio (HTTP 200, com HTTPS).

GET/pagesLista suas páginas: id, name, uses (os endereços que a mostram) e updatedAt.

Listar suas páginas

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

Resposta

{
  "data": [
    {
      "id": 27,
      "name": "Restaurant",
      "uses": ["old-brand.com/menu"],
      "updatedAt": "2026-10-13T15:35:01"
    }
  ]
}

Para mostrar uma página, envie o id dela como pageId ao criar ou alterar um caminho ou um QR code (veja acima).

Por enquanto, criar e editar o conteúdo de uma página é feito no painel; a API lista as páginas e aponta caminhos e QR codes para elas.

← 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 →