Referência da API

A API da Routa é REST sobre HTTPS, com requisições e respostas em JSON e autenticação por chave de API no formato Bearer. Esta página reúne as regras comuns a todos os endpoints. Cada endpoint tem a sua própria página, com parâmetros, exemplos e um playground para testar chamadas. A especificação OpenAPI completa está em openapi.json.

URL base

https://api.routa.chat

Todos os endpoints públicos ficam sob o prefixo /v1. O ambiente (produção ou teste) é definido pela chave de API, não pela URL. Veja Ambientes.

A API não define headers CORS. Chame-a sempre a partir do seu servidor e nunca de um navegador ou de um app, para não expor sua chave.

Autenticação

Envie sua chave de API no header Authorization:

curl https://api.routa.chat/v1/whoami \
  -H "Authorization: Bearer rt_live_..."

Cada chave pertence a um projeto e carrega escopos. Uma rota que exige um escopo ausente na chave responde 403 insufficient_scope. Veja Chaves de API.

O que a chave de API alcança

Grupo	Rotas principais	Página
Mensagens	`POST /v1/messages`, `GET /v1/messages`, `GET /v1/messages/{id}`, `POST /v1/messages/{id}/read`	Mensagens
Eventos	`GET /v1/events`	Eventos
Webhooks	`/v1/webhook_endpoints` e sub-rotas (segredo, ativação, entregas, reenvio)	Webhooks
Templates	`POST /v1/templates`, `GET /v1/templates`, `GET /v1/templates/{id}`, `POST /v1/templates/media`	Templates
Mídia	`POST /v1/media`, `GET /v1/media/{id}`	Mídia
Uso	`GET /v1/usage`	Uso
Identidade	`GET /v1/whoami`	Identidade

Organizações, projetos, chaves de API, canais, membros e cobrança são gerenciados no painel, com sessão de usuário. Essas rotas não aceitam chave de API e não fazem parte desta referência.

Formato de resposta

Objeto único

Um recurso é retornado diretamente, sem envelope:

{
  "id": "msg_01J8ZK9M3Q7X...",
  "channel": "chan_01J8...",
  "direction": "outbound",
  "status": "accepted"
}

Listas

Coleções vêm dentro de um envelope com metadados de paginação:

{
  "data": [{ "id": "msg_01J8..." }],
  "has_more": true,
  "next_cursor": "eyJ..."
}

Erro

{
  "error": {
    "type": "invalid_request_error",
    "code": "channel_inactive",
    "message": "Channel chan_01J8... is not active and cannot send messages.",
    "param": "channel",
    "request_id": "req_01J8..."
  }
}

Veja todos os campos em Erros.

Algumas respostas não seguem o envelope de lista: GET /v1/usage devolve { from_date, to_date, data } sem paginação, e GET /v1/webhook_endpoints devolve todos os endpoints de uma vez, com has_more sempre false. Confira o formato na página de cada endpoint.

Toda resposta traz o header Routa-Request-Id. Informe-o ao falar com o suporte.

Paginação

As listas usam paginação por cursor. Não há page nem offset.

Parâmetro	Descrição
`limit`	Itens por página, de 1 a 100. O padrão é 20.
`cursor`	O `next_cursor` da página anterior.

curl "https://api.routa.chat/v1/messages?limit=50" \
  -H "Authorization: Bearer $ROUTA_API_KEY"

GET /v1/events usa after (o id do último evento) no lugar de cursor. Veja Paginação.

Idempotência

POST /v1/messages aceita o header Idempotency-Key. Repetir a requisição com a mesma chave e o mesmo corpo devolve a resposta original, com Idempotent-Replay: true, sem criar outra mensagem.

Situação	Resultado
Chave nova	A mensagem é criada.
Mesma chave e mesmo corpo	Resposta original, com `Idempotent-Replay: true`.
Mesma chave, requisição ainda em andamento	`409 idempotency_in_progress`, com `Retry-After`.
Mesma chave, corpo diferente	`409 idempotency_key_reuse`.

As chaves são mantidas por 24 horas. Veja Idempotência.

Limites de taxa

Os limites são por projeto, por classe de endpoint.

Classe	Taxa sustentada	Rajada
Envios (`POST /v1/messages`)	50 req/s	100
Escritas	20 req/s	40
Leituras	100 req/s	200

Os headers RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset vêm em toda resposta. Um 429 traz Retry-After:

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 50
RateLimit-Remaining: 0
RateLimit-Reset: 1
Retry-After: 1

Veja Limites de taxa.

Status HTTP

Status	Significado
`200`	Sucesso.
`201`	Recurso criado.
`202`	`POST /v1/messages`: aceito, o envio é assíncrono.
`401`	Chave de API ausente ou inválida.
`402`	Franquia ou limite do plano esgotado.
`403`	A chave não tem o escopo necessário.
`404`	Recurso inexistente ou de outro projeto.
`409`	Conflito de idempotência ou de estado.
`422`	Requisição inválida.
`429`	Limite de taxa excedido.
`503`	A Routa não consegue processar agora. Tente de novo.

Convenções

Telefone

Use o formato E.164, como +5581999999999. O + inicial é opcional na entrada. As respostas trazem o número em E.164.

IDs

Os identificadores são strings opacas com um prefixo que indica o tipo.

Prefixo	Recurso
`msg_`	Mensagem
`chan_`	Canal
`evt_`	Evento
`tmpl_`	Template
`med_`	Mídia
`tmedia_`	Mídia de cabeçalho de template
`whe_`	Endpoint de webhook
`whd_`	Entrega de webhook
`req_`	Requisição

Datas

Todas as datas e horários seguem o formato ISO 8601 em UTC, como 2026-09-04T13:22:41.031Z. Parâmetros de data simples usam YYYY-MM-DD.

Enums

Os valores de campos como status e direction são strings minúsculas. Em campos documentados como abertos, novos valores podem aparecer. Trate valores desconhecidos de forma segura.

Versionamento

A versão está na URL (/v1). Dentro da v1, as mudanças são apenas aditivas: novos endpoints, novos campos opcionais de requisição e novos campos de resposta. Qualquer outra mudança vira v2. Ignore campos desconhecidos nas respostas.

Próximos passos

Início rápido

Envie sua primeira mensagem.

Enviar mensagem

O endpoint principal da API.

Webhooks

Receba eventos de entrega e mensagens recebidas.

SDK para Node.js

Use o cliente oficial em TypeScript.

​URL base

​Autenticação

​O que a chave de API alcança

​Formato de resposta

​Objeto único

​Listas

​Erro

​Paginação

​Idempotência

​Limites de taxa

​Status HTTP

​Convenções

​Telefone

​IDs

​Datas

​Enums

​Versionamento

​Próximos passos

Início rápido

Enviar mensagem

Webhooks

SDK para Node.js

URL base

Autenticação

O que a chave de API alcança

Formato de resposta

Objeto único

Listas

Erro

Paginação

Idempotência

Limites de taxa

Status HTTP

Convenções

Telefone

IDs

Datas

Enums

Versionamento

Próximos passos