REST API overview

Base URL

Every documented data-plane path is relative to one of these bases and lives under /v1. Health probes are the only exception: GET /health/live (static liveness) and GET /health/ready (readiness — 200 only once Brain is reachable) sit at the root, outside /v1, and are served by the self-host binary.

Authentication

Send your API key in either header — they are equivalent:

Authorization: Bearer <key>

X-API-Key: <key>

There is no key prefix to match on and no per-request scope headers. An API key is bound to a (namespace, agent) pair when it is created; the server resolves the caller's identity, namespace, and permissions from the key alone. A missing or blank credential returns 401 unauthorized. See Authentication for the full model.

Response shape

Successful responses return the resource JSON directly — there is no { data: … } envelope. For example, POST /v1/memories returns:

{
  "memory_id": "20177564117...",
  "was_deduplicated": false,
  "salience": 0.62,
  "kind": 0,
  "created_at_unix_nanos": 1752969600000000000,
  "auto_edges_added": 2
}

List endpoints return a named collection field (items, entities, statements, relations, nodes/edges) alongside either a count or a next_cursor, depending on the resource.

Error shape

Every non-2xx response uses one envelope:

{
  "error": {
    "code": "not_found",
    "message": "memory 42 not found"
  }
}

code is the stable, machine-readable handle — branch on it, never parse message. The edge maps Brain's internal error taxonomy to a small set of HTTP-layer codes (unauthorized, forbidden, bad_request, not_found, conflict, engine.unavailable, engine.error). The full catalog, the nine underlying categories, and retry semantics live at Errors.

Identifiers

Two id shapes appear in payloads:

• Memory ids are 128-bit values rendered as a decimal string (e.g. "20177564117..."). They are used in /v1/memories, /v1/recall, /v1/links, and memory nodes in /v1/graph.
• Entity, statement, and relation ids are rendered as hyphenated UUID strings (e.g. "0a1b2c3d-…").

All timestamps are unsigned unix-nanosecond integers (*_unix_nanos). 0 means "unset".

Pagination

Two list endpoints — GET /v1/memories and GET /v1/graph — use keyset (cursor) pagination. Each page carries an opaque hex next_cursor; pass it back as ?cursor=<value> to fetch the next page. next_cursor is omitted entirely when the enumeration is exhausted.

GET /v1/memories?limit=50
GET /v1/memories?limit=50&cursor=1a2b3c…

Cursor strings are opaque — never decode or construct them. The typed-graph list endpoints (/v1/entities, /v1/statements, /v1/entities/{id}/relations) return a single bounded page with a count and no cursor; raise limit (clamped per endpoint) to widen the page.

Idempotency

Write verbs carry a request id on the wire, and Brain deduplicates replays with identical parameters inside a 24-hour window (a differing-parameter replay under the same id is a conflict). Over HTTP the edge generates this id per request; safe retries on a network error are handled by the SDKs' retry policy. See Errors for conflict semantics.

Endpoint map