Convenções

URL base, escopo de organização e workspace, erros, paginação, correlation id e idempotência.

Todos os serviços seguem as mesmas regras de URL, erro, paginação e rastreamento. Esta página descreve essas regras uma vez, e as páginas de endpoint só registram o que foge delas.

URL e escopo

Todas as rotas são servidas pelo mesmo host, atrás de um gateway que encaminha cada caminho para o serviço dono. Você não precisa saber qual serviço responde.

A maior parte das rotas é escopada por organização e workspace:

https://<seu-host-aumo>/api/v1/org/{org_id}/workspaces/{workspace_id}/<recurso>

org_id: identificador da organização.
workspace_id: identificador do workspace dentro da organização.

Use GET /api/v1/me para descobrir as organizações e workspaces a que sua credencial tem acesso.

Erros

Respostas de erro usam um envelope comum:

{
  "error_type": "PERMISSION_DENIED",
  "message": "User is not allowed to access this resource",
  "timestamp": "2026-06-18T12:00:00Z",
  "correlation_id": "corr_3f2a9c1e8b7d4e6fa0b1c2d3e4f5a6b7"
}

Campo	Tipo	Descrição
`error_type`	`string`	Código estável em maiúsculas, como `VALIDATION_ERROR` ou `NOT_FOUND`. Use-o na lógica do cliente.
`message`	`string`	Resumo legível. Pode mudar entre versões.
`timestamp`	`string`	Momento do erro, em ISO 8601 UTC.
`correlation_id`	`string`	Identificador da requisição. Envie-o ao suporte.

Limite de plano

Atingir um limite do plano retorna 409 com error_type PLAN_LIMIT_EXCEEDED e um campo adicional limit:

{
  "error_type": "PLAN_LIMIT_EXCEEDED",
  "message": "Limite do plano FOUNDATION atingido para Usuários por Projeto Privado: 30 de 30.",
  "timestamp": "2026-08-21T12:00:00Z",
  "correlation_id": "corr_3f2a9c1e8b7d4e6fa0b1c2d3e4f5a6b7",
  "limit": {
    "limit_key": "users_per_private_workspace",
    "label": "Usuários por Projeto Privado",
    "plan": "FOUNDATION",
    "limit": 30,
    "current": 30,
    "requested": 1,
    "source": "plan",
    "scope_id": "<workspace-id>"
  }
}

source: plan quando o teto vem do plano, override quando foi ajustado para a organização.
unit: presente só em limites que não são contagem, como GB. Nesse caso limit, current e requested podem ser fracionários.

Paginação

Listagens aceitam limit e offset como query string. O valor máximo de limit é 200 em todos os serviços.

Um limit acima de 200 retorna 422 VALIDATION_ERROR. A API não corta o valor silenciosamente.

Correlation ID

Envie X-Correlation-ID para rastrear uma requisição de ponta a ponta. Se você não enviar, o gateway gera um no formato corr_<uuid>.

O mesmo valor volta no corpo de qualquer erro e acompanha a requisição por todos os serviços internos. Registre-o nos logs do seu cliente.

Idempotência

Comandos com efeito colateral aceitam o header Idempotency-Key. Exemplos: enviar mensagem, criar run de workflow, confirmar upload, copiar workflow e disparar agendamento.

Mesma chave, mesmo comando: retorna o mesmo resultado, sem repetir o efeito.
Mesma chave, comando diferente: retorna 409 IDEMPOTENCY_CONFLICT.

Gere uma chave única, como um UUID, por operação lógica e reutilize-a nas novas tentativas dessa operação.