Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

API

Brain Server exposes a versioned HTTP API. Every response carries an X-Api-Version header. This page is the informational overview; the complete, machine-readable contract is at GET /openapi.yaml at runtime and openapi.yaml in the repo, with the full written contract in API_CONTRACT.md.

Core routes

MethodPathPurpose
GET/healthLiveness probe (minimal {status, version}; detail on /health/db)
GET/health/dbRead-gated detail — capacity, pool, hardening, model, otel, DPO
GET/stats, /versionCounts, model, version
GET/openapi.yamlFull API contract
POST/v1/embeddingsOpenAI-compatible embeddings endpoint
POST/ingest/memoryStructured memory ingest
POST/ingest/markdownMarkdown ingest + graph extraction
POST/ingestStructured ingest (explicit entities/relations)
POST/sources/reconcile · DELETE /sources/{id}Sweep deleted sources / retire a source
POST/recallStructured recall — the primary endpoint
GET/searchSemantic search (deprecated; use /recall)
GET/get/{id} · POST /multi-getFetch chunk(s) by id
GET/recall/{trace_id}/traceRecall-trace replay (decision-path evidence)
POST/verifySpan verification — is a claim supported by a chunk’s text? Binds the X-Brain-Domain label in SQL (an id cannot cross domains in shim mode) + the record gate.
POST/reindexRebuild indexes
GET/metricsPrometheus metrics (auth-gated)
GET/eventsSSE broadcast of memory events
POST/webhooks/{kind} · /webhooks/ghWebhook delivery receiver (HMAC-verified)

Retrieval

POST /recall takes a structured query document (QueryDoc; the query/limit fields are the /recall-specific ones — q/k are the GET /search equivalents):

{
  "query": "blueberry alternative",
  "limit": 5,
  "sources": ["memory", "vault"],
  "provenance": true,
  "graph": false
}
  • Lexical control — a LexSpec with terms, quoted phrases, exclusions (-"..."), and exact code paths.
  • Filters — source/sources (ingest kind), since (ISO timestamp), domain, min_relevance, include_decayed.
  • Provenance — per-retriever ranks, fused score, expansion terms, and per-hit source / node_kind / lawful_basis / region tags (present when stored; absorbed into the RecallHit wire shape, v1.27.12).
  • Abstention — returns {decision: "low_confidence", hits: []} rather than top-1 garbage when quality is too low.

Knowledge graph

MethodPathPurpose
GET/graph/entity/{name}Entity + 1-hop relations
GET/graph/relations?from=&to=Relations between entities
GET/graph/traverse?start=&max_depth=&explain=&kind=Bounded walk (depth ≤ 4); explain=true returns structured hop paths; kind= filters by edge type
GET/graph/relationships/{id}/history (Admin)Edge supersession lineage — every version of an edge triple (v1.27.22)

Governance & write-back

MethodPathPurpose
POST/ingest/proposal · /proposals/{id}/approve[?supersedes=N][&digest=...] · /reject · /proposals/{id}/editHuman-in-the-loop write-back (v1.14). Since v1.27.12 approve accepts an optional digest (SHA-256 of the read-canonical review form, as served by GET /proposals); any drift → 409 — the approval binds to the bytes the reviewer saw
GET/proposals?status= · /decayedApproval queue + decayed review. Each row is a ProposalView (content = read-canonical form, content_digest = SHA-256 the approve verb binds to, v1.27.12)
POST/consolidate/propose · /apply · /undoReviewable consolidation, supersession, undo
POST/suggest · /suggest/feedback · GET /suggest/metricsOpt-in anticipation + false-positive metric
POST/verifyClaim span verification
POST/classify · /decision/{id}/evaluateDeterministic categorization / decision rules
POST/procedure · GET /procedure/{id}/stepsOrdered procedures (steps bind the X-Brain-Domain label + record gate)

Profiles, roles & connectors (policy)

MethodPathPurpose
GET/profiles · GET/POST /profiles/{name}Preset system (v1.21): fetch/upsert a typed knob bundle
GET/roles · GET/POST /roles/{name}Role postures + capability sets (v1.23)
GET/connectorsRegistered connector registry (v1.24)
POST/connectors/registerValidate + register a connector against the domain’s profile gate (v1.24)

Privacy & audit

MethodPathPurpose
GET/exportPortable JSON export
POST/purgeHard, audited deletion by id or owner
DELETE/memory/{id}Hard, audited deletion of one chunk (human-only erasure; the agent tool was removed v1.20.25)
POST/dsarLocate → export → purge → deletion certificate (supports dry_run footprint preview)
GET/dsarDSAR ledger (admin, newest-first, per-row deadline)
GET/tombstones?subject=&since=Deletion registry
GET/dsar/{id}/certificateRe-fetch certificate + live chain check
GET/audit · /audit/verifyAppend-only audit log + chain integrity
GET/quarantine · /quarantine/{id}/release · /deleteInjection review
GET/retention · POST /retention · GET /art30 · GET /retention/reportPer-kind retention policy + Art 30 record + per-domain×kind retention report
GET/snapshot/statusPoint-in-time snapshot state

Domains & routing

MethodPathPurpose
POST/domainsCreate a domain pool (200 = existed, 201 = created; body {domain})
GET/domainsList known domains (single global pool when multi-db is off)
DELETE/domains/{name}?confirm=<name>Delete a domain + all its data (echo-confirm guard, global protected)
POST/domains/{name}/vacuumVACUUM one domain pool (returns {name, vacuumed: true})
GET/domains/{name}/exportConsistent SQLite snapshot download (VACUUM INTO, attachment; filename="brain-<name>.db") — Read in multi-db; Admin in shim mode (the snapshot is the whole shared pool there)
POST/domains/{name}/importRestore a snapshot into a NEW domain (raw bytes body; 201 {name, imported: true, bytes})
POST/domains/recomputeOne-shot centroid recompute sweep over every domain ({recomputed: [[domain, n], …]})
POST/domains/moveMove chunks to another domain

UMP (Universal Memory Protocol)

MethodPathPurpose
GET/ump/capabilitiesProtocol negotiation (conformance level, retrieval signals, max_recall, writable, audit)
POST/ump/remember · /ump/revise · /ump/forget · /ump/feedbackRecord / patch / soft-delete / outcome-feedback
POST/ump/recallRanked recall with per-result signals
GET/ump/memory/{id}Read one record with on-read integrity re-verification
GET/ump/subscribeSSE broadcast of memory events
POST/ump/audit · GET /ump/audit/verifyUMP-scoped audit row family + chain verification

Legal hold & breach (v1.22 / v1.25)

MethodPathPurpose
POST/legal-hold · /legal-hold/{id}/release · GET /legal-holdsPer-domain legal holds; held ids are frozen (purge/DSAR defer)
POST/breach · /breach/{id}/event · /breach/{id}/closeBreach-notification workflow (open / append event / close)
GET/breaches · /breaches/{id}Breach register + detail

Cross-border transfers (v1.26)

MethodPathPurpose
POST/transfers · GET /transfersRegister / list cross-border transfers (validated mechanism + jurisdiction)
GET/transfers/{id}/tiaTransfer-impact assessment (Schrems II, pre-filled evidence)
GET/transfers/{id}/dpaData-processing agreement (Art 28, pre-filled evidence)

Clients register (v1.27 BPO)

MethodPathPurpose
POST/clients · GET /clientsRegister / list clients (one domain per client)
GET/clients/{name}Client detail (client-auditor: row-filtered to granted domains)
POST/clients/{name}/dsarPer-client jurisdiction-aware DSAR + certificate
POST/clients/{name}/holdPer-client legal hold (resolves the client’s domain)
POST/clients/{name}/endTermination: purge-or-return + archive + certificate
GET/clients/{name}/proposals · POST /clients/{name}/proposals/{id}/coachSupervisor QA queue (same ProposalView shape as /proposals) + coaching note (v1.27.8, Admin)

Auth & discovery (JWT mode)

MethodPathPurpose
POST/auth/refresh · /logout · /revokeToken lifecycle
GET/.well-known/openid-configuration · /.well-known/jwks.jsonOIDC + JWKS

Versioning & deprecation

  • Every response carries X-Api-Version.
  • POST /add and GET /search are deprecated (migrate to /ingest + /recall) and emit an RFC 8594 Deprecation header.
  • The written contract (API_CONTRACT.md) states the stability promise and the deprecation policy.

Tooling clients

  • brain CLI — status, query, get, explain, ingest-dir, reconcile, retention, domains, ump, backup/restore, key management, and more (see CLI reference).
  • mcp binary — search/recall/ingest exposed as MCP tools for agent clients.
  • Dioxus client — the visual control surface served at /app.

Next steps