Developers

A API não é um extra. É a superfície principal.

Tudo o que o console mostra é obtido através desta API — incluindo o trace de execução e a exportação. Não existe capacidade privilegiada acessível apenas pela interface.

Base local: http://127.0.0.1:8010. Autenticação por Authorization: Bearer <token>. A especificação OpenAPI é servida em /docs e /openapi.json.

Método	Rota	Descrição
POST	/v1/auth/login	Emite um token de sessão com papel e organização.
GET	/v1/auth/me	Devolve o utilizador autenticado e a sua organização.
GET	/v1/processes	Lista processos com baseline, ordenados por potencial de automação.
POST	/v1/processes	Registra um processo. Exige papel de operador.
GET	/v1/processes/{id}/roi	Retorno calculado sobre execuções observadas, com grau de confiança.
GET	/v1/workflows	Lista definições, filtrável por processo.
POST	/v1/workflows	Cria uma versão. A especificação é validada antes de persistir.
POST	/v1/workflows/{id}/activate	Ativa uma versão e arquiva as anteriores da mesma chave.
GET	/v1/agents	Lista agentes com modelo, ferramentas e política.
POST	/v1/knowledge/documents	Ingere e indexa um documento com ACL e etiquetas.
POST	/v1/knowledge/search	Recuperação sensível a permissões, com proveniência.
GET	/v1/integrations/catalog	Conectores registados no runtime e operações suportadas.
POST	/v1/executions	Cria e executa. Devolve o trace completo ou o estado de espera.
GET	/v1/executions/{id}	Execução com todos os passos, evidência, tokens, custo e latência.
GET	/v1/approvals	Aprovações pendentes para o papel do chamador.
POST	/v1/approvals/{id}/decide	Decisão humana. Idempotente e registada em auditoria.
GET	/v1/analytics/overview	Autonomia, sucesso, custo por fornecedor e poupança estimada.
GET	/v1/audit-events	Auditoria append-only, filtrável por ação e entidade.
GET	/v1/platform/export	Exportação completa e portável. Exige papel de administrador.

Contrato de runtime

Especificação de workflow, versão 1.0

Um objeto com quatro chaves: versão, entradas declaradas, política de risco e passos. Nada mais é necessário para executar.

As expressões usam um subconjunto restrito: literais, nomes do contexto (input, risk, steps, trigger), acessos por atributo ou índice, aritmética, comparações e booleanos.

Regra deliberada de segurança: uma regra de risco malformada escala o risco em vez de o ignorar, e um passo de aprovação sem condição exige sempre aprovação. O comportamento por omissão é o mais restritivo.

Os modelos de prompt suportam interpolação com {{ steps.draft.text }}, avaliada no mesmo contexto restrito.

Resposta de execução (excerto)

O trace é a resposta, não um recurso separado que é preciso descobrir.

{
  "id": 3,
  "status": "WAITING_APPROVAL",
  "risk_level": "HIGH",
  "workflow_key": "resposta-cotacao",
  "pending_approval_id": 1,
  "tokens_in": 892,
  "tokens_out": 214,
  "cost_usd": 0.005886,
  "steps": [
    {
      "step_id": "context",
      "type": "RETRIEVE",
      "status": "COMPLETED",
      "output_json": {
        "hit_count": 4,
        "grounded": true
      },
      "evidence_json": [
        {
          "document_title": "Tabela de preços e descontos 2026",
          "chunk_index": 1,
          "score": 0.0412
        }
      ],
      "latency_ms": 6
    },
    {
      "step_id": "gate",
      "type": "APPROVAL",
      "status": "WAITING",
      "output_json": {
        "awaiting_approval": true,
        "approver_role": "REVIEWER"
      }
    }
  ]
}

Conectores

Catálogo declarado, operações fechadas.

Um conector expõe um conjunto finito de operações. Pedir uma operação fora desse conjunto falha o passo com uma mensagem que lista as disponíveis.

Conector	Operações
crm	create_note · update_deal · create_contact · log_activity
email	send_message · create_draft
accounting	create_invoice · reconcile_payment
storage	upload_document · share_link
chat	post_message · notify_channel
internal	write_record · emit_webhook

No protótipo os conectores correm em modo de simulação: o payload exato é registado no trace e nada é escrito em sistemas de produção.

Erros

Códigos estáveis, mensagens em português.

O corpo de erro tem sempre a forma { detail: { code, message } }. O código é estável e pode ser usado em lógica de cliente; a mensagem é para humanos.

Código	Significado
unauthorized	Token ausente, inválido ou expirado.
forbidden	O papel do utilizador é inferior ao exigido pela operação.
not_found	A entidade não existe na organização do chamador.
conflict	Chave duplicada ou decisão já tomada.
unsupported_spec_version	A versão da especificação de workflow não é suportada.
workflow_not_active	Apenas versões ativas podem ser executadas.
invalid_request	Especificação malformada ou parâmetros inválidos.

Exportação

Devolve organização, utilizadores sem hashes, processos, workflows com especificação, conhecimento, execuções com trace e o contrato de runtime.

GET /v1/platform/export