Pular para o conteúdo principal

Convenções

Convenções que se aplicam a todos os endpoints — leia uma vez aqui e evite repetição em cada página de referência.

Headers de requisição​

HeaderObrigatórioDescrição
Content-Type: application/json; charset=utf-8Sim (para bodies)Formato do body.
Accept: application/jsonRecomendadoRestringe a resposta a JSON.
Authorization ou X-API-KeySim (salvo endpoints públicos)Veja Autenticação.
X-Org-IdQuando aplicávelFixa a organização do contexto para usuários com múltiplas organizações.
X-Request-IdOpcionalSeu próprio identificador. Se não enviar, o servidor gera um e devolve em X-Request-Id na resposta.
TraceparentOpcionalContexto W3C Trace Context para rastreamento distribuído.
x-localeOpcionalpt-BR ou en-US. Força o idioma das mensagens, sobrepondo Accept-Language.
Accept-LanguageOpcionalFallback de idioma caso x-locale não venha.

Headers de resposta​

Toda resposta inclui:

X-Request-Id: 8e1f2c3a4b5c6d7e8f90
X-Trace-Id: 4bf92f3577b34da6a3ce929d0e0e4736
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: no-referrer
Cache-Control: no-store

E, em rotas com rate limit (veja Limites):

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 2026-04-24T15:31:00Z

Multi-tenancy e contexto​

A maioria dos endpoints exige um contexto de organização para operar. A regra de resolução:

  1. API key → já está vinculada a uma organização. O header X-Org-Id é opcional e, se enviado, precisa bater.
  2. JWT/cookie → a organização padrão do usuário é usada. Envie X-Org-Id para alternar para outra organização da qual você é membro.
  3. Admin de plataforma → pode acessar qualquer organização; envie X-Org-Id para especificar.

Acessar um recurso que pertence a outra organização retorna 404 not_found (por privacidade — não vazamos a existência de recursos de outros tenants).

Paginação​

Endpoints de listagem aceitam dois esquemas conforme o domínio:

Offset-based (simples)​

GET /platform/projects?limit=50&offset=100

Resposta:

{
  "items": [ ... ],
  "total": 237,
  "limit": 50,
  "offset": 100
}
  • limit — número máximo de itens retornados. Default e máximo variam por endpoint; o padrão comum é 50, máximo 200.
  • offset — itens a pular. Paginações muito grandes (> 10 000) podem ficar lentas; use filtros mais restritivos nesse caso.

Cursor-based (para listas grandes ou em tempo real)​

GET /notifications?limit=50&cursor=eyJ0cyI6IjIwMjYtMDQtMjRUMTU6MzA6MDBaIn0

Resposta:

{
  "items": [ ... ],
  "next_cursor": "eyJ0cyI6IjIwMjYtMDQtMjRUMTQ6MDA6MDBaIn0",
  "has_more": true
}
  • cursor é opaco — não tente decodificar.
  • Quando has_more=false e next_cursor=null, acabou.

Endpoints que usam cursor são explicitamente marcados na referência.

Filtros e ordenação​

Filtros são passados como query params:

GET /platform/projects?status=active&owner_id=123

Ordenação usa sort e order:

GET /platform/projects/{id}/cases?sort=created_at&order=desc

Quando não especificado, a ordem padrão é a documentada no endpoint (geralmente created_at desc).

Datas e horários​

  • Sempre ISO 8601 UTC com sufixo Z: 
    2026-04-24T15:30:00Z
  • Nunca envie fusos alternativos. Converta para UTC no cliente.
  • Campos representando data sem hora usam YYYY-MM-DD.

IDs​

  • Strings opacas (UUID v4 na maioria dos casos).
  • Não garantimos estabilidade de formato entre versões — trate como black box.
  • IDs são case-sensitive.

Idempotência​

  • GET, PATCH, PUT, DELETE são idempotentes por contrato — repetir a mesma chamada com o mesmo input leva ao mesmo estado final.
  • POST que cria recursos não é idempotente — repetir cria múltiplos recursos.
  • Para operações críticas, use o header Idempotency-Key quando o endpoint documentar suporte (atualmente aplicável a POST /platform/projects/{id}/cases/run e POST /platform/projects/{id}/versions/{id}/publish). O servidor retorna o mesmo resultado para a mesma chave por 24 horas.

Internacionalização​

A API suporta mensagens em dois idiomas:

  • pt-BR (padrão, cobertura completa)
  • en-US (cobertura alta, completando)

Escolha enviando:

x-locale: en-US

ou o padrão Accept-Language. Isso afeta apenas message e hint nas respostas — os campos code, IDs, enums e dados continuam em inglês/neutro.

Campos desconhecidos​

Se o seu cliente envia um campo que o servidor não reconhece, a resposta é 422 request_validation_failed (schema strict, extra="forbid"). Isso previne typos silenciosos. Valide o payload contra a referência do endpoint antes de mandar.

Conexões SSE (Server-Sent Events)​

Dois endpoints usam SSE:

  • POST /ai/stream — respostas incrementais da IA.
  • GET /notifications/stream — contagem de notificações em tempo real.

Para conectar:

Accept: text/event-stream
Cache-Control: no-cache
X-API-Key: rfk_…

Resposta:

Content-Type: text/event-stream

event: message
data: {"type": "token", "text": "Olá"}

event: message
data: {"type": "done"}

Cada organização/usuário tem limite de conexões SSE simultâneas. Ao exceder: 429 rate_limited. Reuse a conexão aberta em vez de abrir novas.

Uploads​

Endpoints que aceitam arquivo (por exemplo, POST /platform/organizations/{id}/integrations/{id}/sync-import) usam multipart/form-data. Isso está documentado caso a caso — a grande maioria da API é JSON puro.

Versões e deprecações​

Quando um campo é depreciado:

  • a resposta inclui o campo deprecated: true em details (quando aplicável);
  • o header Warning: 299 - "Field X deprecated, use Y" é enviado;
  • um novo endpoint ou campo substituto é documentado.

Campos depreciados seguem sendo enviados durante pelo menos 6 meses antes de serem removidos, e a remoção só acontece em uma nova major.