Documentação

Autenticação

Todas as rotas de /api/v1/* exigem header:

Authorization: Bearer sk-railter-XXXXXXXXXXXXXXXX

Crie keys no dashboard em Projetos → [seu projeto] → API Keys.

POST /api/v1/llm/chat

Chat completion via Claude, GPT-4o e outros. Suporta streaming SSE.

{
  "model": "claude-sonnet-4-6",
  "messages": [
    {"role": "system", "content": "Você é útil."},
    {"role": "user", "content": "Olá!"}
  ],
  "stream": true,
  "temperature": 0.7,
  "max_tokens": 1024
}

GET /api/v1/llm/models

Lista os modelos disponíveis.

POST /api/v1/mail/send

Envia email transacional via Mailder.

{
  "from": "[email protected]",
  "to": ["[email protected]"],
  "subject": "Assunto",
  "html": "<p>Mensagem</p>"
}

GET /api/v1/usage

Consumo da API key atual: resumo do período, série por dia, quebra por modelo e as últimas requisições (com request_id pra reconciliar linha a linha com o corpo do /llm/chat).

GET /api/v1/usage?from=2026-07-01&to=2026-07-31&scope=key&include=series,models,recent&limit=100

from/to (padrão: últimos 30 dias, máximo 92), scope = key (padrão) ou project, include escolhe as seções, limit corta o recent (1 a 1000, padrão 100). O dia da série é cortado no fuso America/Sao_Paulo (o mesmo que volta em period.timezone), não em UTC. billed_cost_usd é o que você paga; base_cost_usd é o custo do provider antes do markup — são números diferentes.

recent continua sendo "as últimas N requisições, de qualquer idade" enquanto você não mandar from/to; mandando, ela respeita o recorte junto com o resto. O modo em vigor vem em period.recent_window (todo_o_historico ou periodo). Parâmetro com valor inválido devolve 400 com error.code = invalid_request — nada é ajustado em silêncio.

base_cost_usd, margin_usd e markup_percent podem vir null: é o que acontece quando o recorte inclui requisições gravadas antes de o custo do provider passar a ser registrado por linha. cost_breakdown_status diz qual é o caso (completo, parcial, sem_dado) e cost_breakdown_missing_requests diz quantas linhas faltam. billed_cost_usd é sempre confiável.

As suas chamadas a este endpoint não entram no seu consumo: ler o medidor não gasta token nem custa nada, e um painel com polling se contaria sozinho.

GET /api/v1/keys/me

Info da API key sendo usada (scopes, limites, consumo do dia, projeto, organização).

Limites

Cada API key tem um teto de requisições por minuto e de tokens por dia (o dia vira à meia-noite em America/Campo_Grande). Toda resposta traz X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset e os equivalentes X-RateLimit-Tokens-* — dá pra se regular sem precisar bater no teto.

Estourou, a API devolve 429 com Retry-After e um corpo com error.code (rate_limit_exceeded ou daily_token_limit_exceeded), limit e retry_after. Limite zero = sem teto.

Durante a transição os limites rodam em modo observação: os headers já saem, mas nada é barrado. O modo em vigor vem em rate_limit_mode no GET /api/v1/keys/me — enquanto ele disser shadow, nenhuma requisição sua leva 429; quando virar enforce, o teto passa a valer. Trate os headers desde já.