REST

URL base: https://valorbrain-api.valor.digital

curl -sS https://valorbrain-api.valor.digital/health

Auth: Authorization: Bearer <vbm_…> (o token do cliente) ou a chave legada vb_agent_… do signup.

O tenant vem sempre da credencial: não envie X-Tenant-ID. Quais credenciais valem onde: Tokens.

Busca

curl -sS -X POST https://valorbrain-api.valor.digital/search \
  -H "Authorization: Bearer $VALORBRAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"deploy key","limit":5}'

Opcional: "profile": "speed" para o caminho rápido (híbrido/FTS, sem cross-encoder). O padrão é balanced. "timing": true ou o header x-search-timing: 1 adiciona hybrid_ms / rerank_ms / graph_ms / total_ms.

POST /retrieve é a gêmea multiestratégia da busca (memory_retrieve no MCP roteia sozinho; esta é a forma explícita REST).

Ingestão

curl -sS -X POST https://valorbrain-api.valor.digital/documents \
  -H "Authorization: Bearer $VALORBRAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "decisions",
    "path": "ADR-001.md",
    "title": "We chose PostgreSQL",
    "content": "## Decision\nPostgreSQL is the primary store."
  }'

É isso que o add da CLI chama.

Ingestão SaaS (chave de API do workspace)

Para sistemas que já falam com o app, não com o engine:

curl -sS -X POST https://valorbrain.valor.digital/api/v1/ingest \
  -H "Authorization: Bearer fk_<id>.sk_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "decisions",
    "path": "ADR-001.md",
    "title": "We chose PostgreSQL",
    "content": "## Decision\nPostgreSQL is the primary store."
  }'

Chaves fk_ autenticam a ingestão no host SaaS. Elas não substituem a busca no engine em valorbrain-api.

Leitura / curadoria

O OpenAPI público do engine (valorbrain-api.valor.digital/openapi.json) lista as rotas de cliente; as rotas de admin e operação ficam fora dele. O JSON em valorbrain.valor.digital/openapi.json é servido pelo app, não é a spec do engine. Este site de docs publica a superfície pública de integração; veja a Referência de API.

Cadastro de agente (REST)

curl -sS -X POST https://valorbrain-api.valor.digital/api/v1/agents/signup \
  -H "Content-Type: application/json" \
  -d '{"agent_name":"my-agent","agent_caller":"claude-code"}'

Precisa acertar o valorbrain-api. O mesmo path no mcpbrain é engolido pelo transporte MCP.

Tabela completa: Referência REST.