API HTTP
Convenções globais para autenticação, escopo de projeto, paginação, idempotência e erros.
Use o SDK TypeScript para integrações de produto sempre que possível. Use HTTP direto para automações internas, recursos ainda não cobertos pelo SDK ou integrações em outras linguagens.
#Autenticação
Envie a API key no header Authorization.
Authorization: Bearer rxk_live_...O endpoint de contexto retorna o projeto associado à chave.
GET /v1/platform/context#Escopo das rotas
| Escopo | Forma | Exemplos |
|---|---|---|
| Project | /v1/projects/:projectId/... | agents, sessions, memory stores, environments |
| Workspace | /v1/... | API keys, vaults, skills, webhooks, usage, governance |
| Platform | /v1/platform/... | contexto autenticado |
O SDK resolve o projectId uma vez e usa esse valor para recursos project-scoped.
#Paginação
Listas de recursos usam cursor opaco:
GET /v1/projects/:projectId/agents?limit=20&cursor=...Resposta:
{
"data": [],
"hasMore": false,
"nextCursor": null
}Eventos de session usam seq, porque a ordem do log é parte do contrato:
GET /v1/projects/:projectId/sessions/:id/events?afterSeq=42&limit=100#Erros
Erros usam envelope estável:
{
"error": {
"code": "session.not_found",
"message": "Session não encontrada",
"requestId": "req_..."
}
}code é o campo que seu backend deve usar para tratamento programático. message é legível para diagnóstico, mas não deve ser usado como contrato.
#Idempotência
Eventos aceitam idempotencyKey. Use uma chave estável quando reenviar mensagens, interrupções, confirmações ou resultados de custom tool após retry do seu backend.
Requests GET podem ser repetidos. Mutações devem ser repetidas apenas quando você tiver uma chave ou uma estratégia explícita de retry.