Docs / API reference

API reference

Every method, parameter, request, and response schema.

Sourced history for changing facts — cited or honestly absent.

Two calls are the whole product:

const brain = await client.brains.create({ id, self });
await brain.remember(anything);
const ctx = await brain.context(question);

Four layers, and no layer silently acquires the authority of the layer after it:

Record  = what entered the system
Memory  = what the system inferred
Object  = what the application accepted
Context = what is eligible for this task

Every returned assertion carries provenance to a source Record. A miss means no eligible result was found — never that the fact is false. Unknowns are explicit. Conflicts are preserved. Attribution is enforced by default: nothing is returned as the subject's own unless ownership is established.

The simplicity budget#

Not a preference — scripts/check_api_simplicity.py parses this contract and fails the build on a sixth resource, an eighth read knob, or a query parameter that declares neither x-brain-knob nor x-brain-view-param. The counts below are read out of the contract by this generator, the same way the gate reads them.

No knob may change what is TRUE. A knob may only change what is RETURNED.

Operations#

Operation guide#

Every section below is generated from the same OpenAPI document as the clients. The examples use environment variables, contain no credential, and open the same-origin playground without sending a request until you choose to run it.

{
  "id": "ada"
}

curl -sS -X POST \
  "$BRAIN/brains" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: docs-example-1" \
  -H "Content-Type: application/json" \
  --data '{"id":"ada"}'

curl -sS -X GET \
  "$BRAIN/brains/ada" \
  -H "Authorization: Bearer $KEY"

curl -sS -X DELETE \
  "$BRAIN/brains/ada" \
  -H "Authorization: Bearer $KEY"

curl -sS -X GET \
  "$BRAIN/brains/ada/profile" \
  -H "Authorization: Bearer $KEY"

curl -sS -X GET \
  "$BRAIN/brains/ada/census" \
  -H "Authorization: Bearer $KEY"

curl -sS -X GET \
  "$BRAIN/brains/ada/traces" \
  -H "Authorization: Bearer $KEY"

curl -sS -X GET \
  "$BRAIN/brains/ada/traces/ctx_01K7QEXAMPLE" \
  -H "Authorization: Bearer $KEY"

{
  "content": "The customer prefers annual billing."
}

curl -sS -X POST \
  "$BRAIN/brains/ada/records" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: docs-example-1" \
  -H "Content-Type: application/json" \
  --data '{"content":"The customer prefers annual billing."}'

curl -sS -X GET \
  "$BRAIN/brains/ada/records/rec_01K7QEXAMPLE" \
  -H "Authorization: Bearer $KEY"

curl -sS -X DELETE \
  "$BRAIN/brains/ada/records/rec_01K7QEXAMPLE" \
  -H "Authorization: Bearer $KEY"

curl -sS -X GET \
  "$BRAIN/brains/ada/memories" \
  -H "Authorization: Bearer $KEY"

curl -sS -X GET \
  "$BRAIN/brains/ada/memories/mem_01K7QEXAMPLE" \
  -H "Authorization: Bearer $KEY"

{
  "type": "preference",
  "key": "billing",
  "value": {
    "plan": "annual"
  }
}

curl -sS -X POST \
  "$BRAIN/brains/ada/objects" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: docs-example-1" \
  -H "Content-Type: application/json" \
  --data '{"type":"preference","key":"billing","value":{"plan":"annual"}}'

curl -sS -X GET \
  "$BRAIN/brains/ada/objects/preference/billing" \
  -H "Authorization: Bearer $KEY"

{
  "query": "What should the agent know right now?"
}

curl -sS -X POST \
  "$BRAIN/brains/ada/context" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  --data '{"query":"What should the agent know right now?"}'

The five resources#

Servers#

The raw contract is published beside this page: openapi.yaml — the same bytes both SDKs are generated from, and the file the conformance fuzzer checks every response against.

# Brain Memory API reference

Contract version: `0.1.0`. The binding machine contract is [openapi.yaml](/openapi.yaml).

Set `BRAIN` to the API base ending in `/v1` and keep `KEY` in the runtime environment.

## `createBrain`

`POST /brains` — Create a Brain

[Try this operation](playground.html?operation=createBrain)

### Parameters

- `Idempotency-Key` (header, optional) — `string` — Plumbing, not a knob. Replays return the original response body.


### Request

Schema: `BrainCreate`

```json

{
  "id": "ada"
}

```


Fields:

- `id` (required) — `Slug` — No description.

- `name` (optional) — `string` — No description.

- `self` (optional) — `SelfEntity` — No description.

- `self.type` (required) — `string` — No description.

- `self.name` (required) — `string` — No description.


### Responses

- `201` — `Brain` — Created

- `default` — `Error` — No description.


### Errors

All errors use the shared `Error` schema. See [Errors](errors.md).


### cURL

```bash

curl -sS -X POST \
  "$BRAIN/brains" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: docs-example-1" \
  -H "Content-Type: application/json" \
  --data '{"id":"ada"}'

```

## `getBrain`

`GET /brains/{brain_id}` — Inspect a Brain

[Try this operation](playground.html?operation=getBrain)

### Parameters

- `brain_id` (path, required) — `Slug` — No description.


### Request

No request body.


### Responses

- `200` — `Brain` — OK

- `default` — `Error` — No description.


### Errors

All errors use the shared `Error` schema. See [Errors](errors.md).


### cURL

```bash

curl -sS -X GET \
  "$BRAIN/brains/ada" \
  -H "Authorization: Bearer $KEY"

```

## `forgetBrain`

`DELETE /brains/{brain_id}` — Delete a Brain and everything derived from it

[Try this operation](playground.html?operation=forgetBrain)

### Parameters

- `brain_id` (path, required) — `Slug` — No description.


### Request

No request body.


### Responses

- `200` — `DeletionReceipt` — Deleted, with a receipt

- `default` — `Error` — No description.


### Errors

All errors use the shared `Error` schema. See [Errors](errors.md).


### cURL

```bash

curl -sS -X DELETE \
  "$BRAIN/brains/ada" \
  -H "Authorization: Bearer $KEY"

```

## `getProfile`

`GET /brains/{brain_id}/profile` — The always-fresh self card — who this Brain is, every line cited

[Try this operation](playground.html?operation=getProfile)

### Parameters

- `brain_id` (path, required) — `Slug` — No description.

- `limit` (query, optional) — `integer` — No description.


### Request

No request body.


### Responses

- `200` — `Profile` — OK

- `default` — `Error` — No description.


### Errors

All errors use the shared `Error` schema. See [Errors](errors.md).


### cURL

```bash

curl -sS -X GET \
  "$BRAIN/brains/ada/profile" \
  -H "Authorization: Bearer $KEY"

```

## `getCensus`

`GET /brains/{brain_id}/census` — What is noisy in THIS Brain's own data

[Try this operation](playground.html?operation=getCensus)

### Parameters

- `brain_id` (path, required) — `Slug` — No description.


### Request

No request body.


### Responses

- `200` — `Census` — OK

- `default` — `Error` — No description.


### Errors

All errors use the shared `Error` schema. See [Errors](errors.md).


### cURL

```bash

curl -sS -X GET \
  "$BRAIN/brains/ada/census" \
  -H "Authorization: Bearer $KEY"

```

## `listTraces`

`GET /brains/{brain_id}/traces` — Every Context request this Brain served, newest first

[Try this operation](playground.html?operation=listTraces)

### Parameters

- `brain_id` (path, required) — `Slug` — No description.

- `limit` (query, optional) — `integer` — No description.


### Request

No request body.


### Responses

- `200` — `TracePage` — OK

- `default` — `Error` — No description.


### Errors

All errors use the shared `Error` schema. See [Errors](errors.md).


### cURL

```bash

curl -sS -X GET \
  "$BRAIN/brains/ada/traces" \
  -H "Authorization: Bearer $KEY"

```

## `getTrace`

`GET /brains/{brain_id}/traces/{trace_id}` — Inspect one Context request — its lanes, scores, citations, budget and cost

[Try this operation](playground.html?operation=getTrace)

### Parameters

- `brain_id` (path, required) — `Slug` — No description.

- `trace_id` (path, required) — `string` — The `id` of the Context being explained, or the `trc_…` id of a failed request.


### Request

No request body.


### Responses

- `200` — `Trace` — OK

- `default` — `Error` — No description.


### Errors

All errors use the shared `Error` schema. See [Errors](errors.md).


### cURL

```bash

curl -sS -X GET \
  "$BRAIN/brains/ada/traces/ctx_01K7QEXAMPLE" \
  -H "Authorization: Bearer $KEY"

```

## `rememberRecord`

`POST /brains/{brain_id}/records` — Remember anything

[Try this operation](playground.html?operation=rememberRecord)

### Parameters

- `brain_id` (path, required) — `Slug` — No description.

- `Idempotency-Key` (header, optional) — `string` — Plumbing, not a knob. Replays return the original response body.


### Request

Schema: `RecordCreate`

```json

{
  "content": "The customer prefers annual billing."
}

```


Fields:

- `content` (required) — `string | MessageContent | DocumentContent | EventContent | FactContent | CorrectionContent` — Plain text, or ONE typed shape tagged by `kind`. Text is the two-call quickstart and stays first-class; a typed shape is how structure that already exists survives the trip, because a speaker is a person, a thread is an episode and a participant is an edge — and none of that is…

- `source` (optional) — `Source` — No description.

- `source.name` (optional) — `string` — No description.

- `source.external_id` (optional) — `string` — No description.

- `source.trust` (optional) — `string` — No description.

- `visibility` (optional) — `Visibility` — No description.

- `occurred_at` (optional) — `string` — When it happened. Defaults to now; wrong for anything historical.


### Responses

- `202` — `Record` — Accepted and durably queued

- `default` — `Error` — No description.


### Errors

All errors use the shared `Error` schema. See [Errors](errors.md).


### cURL

```bash

curl -sS -X POST \
  "$BRAIN/brains/ada/records" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: docs-example-1" \
  -H "Content-Type: application/json" \
  --data '{"content":"The customer prefers annual billing."}'

```

## `getRecord`

`GET /brains/{brain_id}/records/{record_id}` — Inspect a Record and its processing state

[Try this operation](playground.html?operation=getRecord)

### Parameters

- `brain_id` (path, required) — `Slug` — No description.

- `record_id` (path, required) — `string` — No description.


### Request

No request body.


### Responses

- `200` — `Record` — OK

- `default` — `Error` — No description.


### Errors

All errors use the shared `Error` schema. See [Errors](errors.md).


### cURL

```bash

curl -sS -X GET \
  "$BRAIN/brains/ada/records/rec_01K7QEXAMPLE" \
  -H "Authorization: Bearer $KEY"

```

## `forgetRecord`

`DELETE /brains/{brain_id}/records/{record_id}` — Delete a Record and cascade to everything derived from it

[Try this operation](playground.html?operation=forgetRecord)

### Parameters

- `brain_id` (path, required) — `Slug` — No description.

- `record_id` (path, required) — `string` — No description.


### Request

No request body.


### Responses

- `200` — `DeletionReceipt` — Deleted, with a receipt

- `default` — `Error` — No description.


### Errors

All errors use the shared `Error` schema. See [Errors](errors.md).


### cURL

```bash

curl -sS -X DELETE \
  "$BRAIN/brains/ada/records/rec_01K7QEXAMPLE" \
  -H "Authorization: Bearer $KEY"

```

## `listMemories`

`GET /brains/{brain_id}/memories` — Inspect what the system inferred

[Try this operation](playground.html?operation=listMemories)

### Parameters

- `brain_id` (path, required) — `Slug` — No description.

- `subject` (query, optional) — `string` — No description.

- `owner` (query, optional) — `string` — No description.

- `as_of` (query, optional) — `string` — No description.

- `since_watermark` (query, optional) — `string` — Delta read. Returns only Memories that changed after this boundary, oldest change first — the incremental-sync loop is: read a page, apply it, send its `watermark` back, repeat while `has_more`. CHANGED means TRANSACTION time — when this Brain learned or revised the Memory — not…

- `cursor` (query, optional) — `string` — No description.

- `limit` (query, optional) — `integer` — No description.


### Request

No request body.


### Responses

- `200` — `MemoryPage` — OK

- `default` — `Error` — No description.


### Errors

All errors use the shared `Error` schema. See [Errors](errors.md).


### cURL

```bash

curl -sS -X GET \
  "$BRAIN/brains/ada/memories" \
  -H "Authorization: Bearer $KEY"

```

## `getMemory`

`GET /brains/{brain_id}/memories/{memory_id}` — Inspect one Memory, its revisions, and its evidence

[Try this operation](playground.html?operation=getMemory)

### Parameters

- `brain_id` (path, required) — `Slug` — No description.

- `memory_id` (path, required) — `string` — No description.


### Request

No request body.


### Responses

- `200` — `Memory` — OK

- `default` — `Error` — No description.


### Errors

All errors use the shared `Error` schema. See [Errors](errors.md).


### cURL

```bash

curl -sS -X GET \
  "$BRAIN/brains/ada/memories/mem_01K7QEXAMPLE" \
  -H "Authorization: Bearer $KEY"

```

## `acceptObject`

`POST /brains/{brain_id}/objects` — Accept application truth

[Try this operation](playground.html?operation=acceptObject)

### Parameters

- `brain_id` (path, required) — `Slug` — No description.

- `Idempotency-Key` (header, optional) — `string` — Plumbing, not a knob. Replays return the original response body.


### Request

Schema: `ObjectAccept`

```json

{
  "type": "preference",
  "key": "billing",
  "value": {
    "plan": "annual"
  }
}

```


Fields:

- `type` (required) — `Slug` — No description.

- `key` (required) — `Slug` — No description.

- `value` (required) — `—` — No description.

- `if_version` (optional) — `integer | null` — Optimistic concurrency. Stale writes fail with the current version.


### Responses

- `201` — `Object` — Accepted

- `default` — `Error` — No description.


### Errors

All errors use the shared `Error` schema. See [Errors](errors.md).


### cURL

```bash

curl -sS -X POST \
  "$BRAIN/brains/ada/objects" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: docs-example-1" \
  -H "Content-Type: application/json" \
  --data '{"type":"preference","key":"billing","value":{"plan":"annual"}}'

```

## `getObject`

`GET /brains/{brain_id}/objects/{object_type}/{object_key}` — Inspect the accepted Object

[Try this operation](playground.html?operation=getObject)

### Parameters

- `brain_id` (path, required) — `Slug` — No description.

- `object_type` (path, required) — `Slug` — No description.

- `object_key` (path, required) — `Slug` — No description.


### Request

No request body.


### Responses

- `200` — `Object` — OK

- `default` — `Error` — No description.


### Errors

All errors use the shared `Error` schema. See [Errors](errors.md).


### cURL

```bash

curl -sS -X GET \
  "$BRAIN/brains/ada/objects/preference/billing" \
  -H "Authorization: Bearer $KEY"

```

## `createContext`

`POST /brains/{brain_id}/context` — Get task-ready context — cited, budgeted, honest

[Try this operation](playground.html?operation=createContext)

### Parameters

- `brain_id` (path, required) — `Slug` — No description.

- `Brain-Watermark` (header, optional) — `string` — Plumbing, not a knob. Guarantees the Context is at or after this boundary.


### Request

Schema: `ContextRequest`

```json

{
  "query": "What should the agent know right now?"
}

```


Fields:

- `query` (required) — `string` — No description.

- `purpose` (optional) — `string` — One word sets policy, sensitivity, and eligibility for a class of task.

- `as_of` (optional) — `string` — Applies world-time eligibility to returned Memory components. The evidence text is a selected chunk projection and records this boundary but does not yet reconstruct a historical chunk index.

- `budget` (optional) — `object` — No description.

- `budget.tokens` (optional) — `integer` — No description.

- `budget.ms` (optional) — `integer` — No description.

- `include` (optional) — `array` — Select response components. `memories` are cited, temporally eligible Memory atoms whose complete Record lineage is contained in the selected evidence window.

- `schema` (optional) — `object` — Request structured context. Invalid means unavailable, never malformed.

- `filter` (optional) — `object` — Narrow what is eligible. `since`, `until` and `sources` are enforced. `subjects`, `owner` and `sensitivity_lte` are recorded on the receipt and NOT enforced on Context — use `listMemories` for subject and owner filtering, where those fields exist.

- `filter.subjects` (optional) — `array` — No description.

- `filter.owner` (optional) — `string` — No description.

- `filter.sources` (optional) — `array` — No description.

- `filter.since` (optional) — `string` — No description.

- `filter.until` (optional) — `string` — No description.

- `filter.sensitivity_lte` (optional) — `string | null` — No description.

- `mode` (optional) — `string` — `fast` never composes an answer — it assembles cited evidence and asserts nothing, which is what makes it unable to fabricate. A ready `fast` Context on the hosted spine spends ONE model call — a query embedding — and `cost.generative_calls` is therefore `0`, with `embedding_cal…


### Responses

- `200` — `Context` — OK — a single Context, or an SSE stream when `Accept: text/event-stream` met `mode: thorough`

- `202` — `Context` — Not yet assemblable at the requested watermark, or `thorough` exceeded the synchronous budget

- `default` — `Error` — No description.


### Errors

All errors use the shared `Error` schema. See [Errors](errors.md).


### cURL

```bash

curl -sS -X POST \
  "$BRAIN/brains/ada/context" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  --data '{"query":"What should the agent know right now?"}'

```