Referência da API

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.

http

Authorization: Bearer rxk_live_...

O endpoint de contexto retorna o projeto associado à chave.

http

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:

http

GET /v1/projects/:projectId/agents?limit=20&cursor=...

Resposta:

json

{
  "data": [],
  "hasMore": false,
  "nextCursor": null
}

Eventos de session usam seq, porque a ordem do log é parte do contrato:

http

GET /v1/projects/:projectId/sessions/:id/events?afterSeq=42&limit=100

#Erros

Erros usam envelope estável:

json

{
  "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.

O envelope pode trazer um campo details, e ele só aparece em dois casos:

Caso	Conteúdo de `details`
`request.invalid` (400)	As issues do schema: caminho do campo e mensagem.
`budget.exceeded` (403)	`scope`, `meter`, `limit` e `used`.

Nos demais erros, o contexto interno fica só no log da plataforma — não conte com details para outros códigos.

#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.

#Recursos

Agents

Criar, atualizar, arquivar e listar versões.

Sessions

Criar sessions, ingerir eventos e ler histórico.

Memory

Stores e documentos versionados.

Streaming

SSE e retomada por seq.

Vaults

Cofres e credenciais.

Webhooks

Assinaturas e rotação de secret.

Deployments de canal

Agent por número e pin de versão.

Automations

Agendas, disparos e runs.

Experimentos

Datasets, scorers e tetos por caso.

Usage e orçamentos

Consumo, tetos por workspace e por agent.