HTTP API Reference

The the-brain daemon exposes a REST API on localhost:9420 (default). In remote mode, all endpoints except /api/health require Authorization: Bearer <token>.

Authentication

Authorization: Bearer mb_<token>

Required on all endpoints in remote mode except /api/health.

CORS

Endpoints are restricted to localhost origins only (security audit 2026-05-07). Requests from non-localhost origins are rejected.

`GET /api/health`

Daemon status and identity.

Auth: None (public)

Response:

{
  "status": "running",
  "pid": 12345,
  "uptime": 3600000,
  "uptimeFormatted": "1h 0m",
  "activeProject": "my-app",
  "interactionCount": 42,
  "mode": "local"
}

Field	Type	Description
`status`	string	`"running"` or `"stopped"`
`pid`	number	Process ID
`uptime`	number	Milliseconds since daemon start
`uptimeFormatted`	string	Human-readable uptime (`1h 0m`, `3d 12h`)
`activeProject`	string	Current project name or `"global"`
`interactionCount`	number	Total interactions processed
`mode`	string	`"local"` or `"remote"`

`GET /api/stats`

Memory and graph statistics.

Auth: Required in remote mode

Response:

{
  "memories": {
    "total": 150,
    "instant": 100,
    "selection": 30,
    "deep": 20
  },
  "graphNodes": 45,
  "lastConsolidation": 1714800000000,
  "lastTraining": 1714800000000,
  "lastTrainingDuration": 12.5,
  "lastTrainingLoss": 0.023,
  "interactionCount": 42
}

Field	Type	Description
`memories.total`	number	Total memory fragments
`memories.instant`	number	Layer 1 (graph memory)
`memories.selection`	number	Layer 2 (SPM curated)
`memories.deep`	number	Layer 3 (consolidated)
`graphNodes`	number	Graph memory nodes
`lastConsolidation`	number \| null	Last consolidation timestamp
`lastTraining`	number \| null	Last MLX training timestamp
`lastTrainingDuration`	number \| null	Training duration in seconds
`lastTrainingLoss`	number \| null	Final training loss
`interactionCount`	number	Total interactions processed

`POST /api/consolidate`

Force promotion of surprising memories from SELECTION to DEEP layer.

Auth: Required in remote mode

Body: None

Response:

{
  "consolidated": true,
  "memoriesProcessed": 12,
  "timestamp": 1714800000000
}

When no surprising memories:

{
  "consolidated": false,
  "reason": "No surprising memories",
  "memoriesChecked": 0
}

`POST /api/train`

Trigger MLX LoRA training on DEEP memories.

Auth: Required in remote mode

Body: None

Response:

{
  "trained": true,
  "fragmentCount": 20,
  "duration": 45.2
}

When no DEEP memories:

{
  "trained": false,
  "reason": "No DEEP memories"
}

`POST /api/ingest-file`

Ingest files (PDF, images, documents) into the brain via drag-and-drop. Files are converted to markdown using MarkItDown (Python sidecar).

Auth: Required in remote mode

Body:

{
  "path": "/absolute/path/to/file.pdf"
}

Or batch:

{
  "paths": ["/path/to/doc1.pdf", "/path/to/doc2.md"]
}

Guards:

Maximum file size: 20 MB
Path traversal blocked (..)
Content deduplication (SHA-256)
Only absolute paths accepted

Response:

{
  "ingested": 2,
  "total": 2,
  "results": [
    { "path": "/path/to/doc1.pdf", "ingested": true, "bytes": 4500 },
    { "path": "/path/to/doc2.md", "ingested": true, "bytes": 1200 }
  ]
}

Error example:

{
  "path": "/path/to/large.mp4",
  "ingested": false,
  "bytes": 0,
  "error": "File too large (35.0 MB, max 20 MB)"
}

`POST /api/ingest-interaction`

Push a raw interaction (prompt + response pair) into the brain pipeline. Used by the push agent and external integrations.

Auth: Required in remote mode

Body:

{
  "interaction": {
    "id": "optional-custom-id",
    "timestamp": 1714800000000,
    "prompt": "Write a React component",
    "response": "Here is a functional component...",
    "source": "my-custom-tool",
    "metadata": {
      "language": "TypeScript",
      "project": "my-app"
    }
  }
}

Minimum required fields: prompt, source.

Response:

{
  "ingested": true,
  "id": "ingest-1714800000000-YXBhY2hl"
}

`GET /api/timeline`

Paginated memory list, newest first.

Auth: Required in remote mode

Query Parameters:

Parameter	Type	Default	Description
`offset`	number	`0`	Pagination offset
`limit`	number	`20`	Page size (max: `100`)
`layer`	string	—	Filter: `0` (INSTANT), `1` (SELECTION), `2` (DEEP), `all`
`source`	string	—	Filter by source name (e.g. `cursor`, `claude-code`)

Response:

{
  "memories": [
    {
      "id": "m_abc123",
      "layer": 2,
      "content": "Prefer arrow functions over function declarations",
      "surpriseScore": 0.85,
      "timestamp": 1714800000000,
      "source": "cursor",
      "metadata": {}
    }
  ],
  "hasMore": true,
  "total": 150
}

`GET /timeline`

Returns an HTML single-page application showing the interactive memory timeline. Same data as the JSON API, rendered as a dark-theme infinite-scroll page.

Auth: Required in remote mode

Response: text/html

User Management (Team Mode)

All user endpoints require admin authentication via Bearer token. See Team Mode for setup.

`POST /api/users`

Create a new team member.

Auth: Admin Bearer token

Body:

{
  "name": "anna",
  "displayName": "Anna Kowalska",
  "role": "contributor",
  "permissions": [
    { "project": "cpv", "role": "contributor" }
  ]
}

Response: 201 Created

{
  "status": "ok",
  "user": {
    "id": "uuid",
    "name": "anna",
    "displayName": "Anna Kowalska",
    "role": "contributor",
    "permissions": [{ "project": "cpv", "role": "contributor" }],
    "createdAt": 1714800000000
  }
}

`GET /api/users`

List all users.

Auth: Admin Bearer token

Response:

{
  "status": "ok",
  "users": [
    {
      "id": "uuid-1",
      "name": "admin",
      "role": "admin",
      "permissions": []
    },
    {
      "id": "uuid-2",
      "name": "anna",
      "role": "contributor",
      "permissions": [{ "project": "cpv", "role": "contributor" }]
    }
  ]
}

`DELETE /api/users/:id`

Remove a user (cascades to tokens and audit entries).

Auth: Admin Bearer token

Response:

{ "status": "ok", "removed": true, "userId": "uuid" }

`POST /api/users/:id/tokens`

Generate a new API token for a user.

Auth: Admin Bearer token

Body (optional):

{ "label": "MacBook Pro" }

Response: 201 Created

{
  "status": "ok",
  "token": {
    "id": "tok-uuid",
    "userId": "user-uuid",
    "token": "mb_a1b2c3d4e5f6...",
    "label": "MacBook Pro",
    "createdAt": 1714800000000
  }
}

`GET /api/users/:id/tokens`

List all active tokens for a user.

Auth: Admin Bearer token

Response:

{
  "status": "ok",
  "tokens": [
    {
      "id": "tok-uuid-1",
      "token": "mb_xxx...",
      "label": "MacBook Pro",
      "createdAt": 1714800000000,
      "lastUsed": 1714900000000
    }
  ]
}

`DELETE /api/users/:id/tokens/:tid`

Revoke an API token.

Auth: Admin Bearer token

Response:

{ "status": "ok", "revoked": true, "tokenId": "tok-uuid", "userId": "user-uuid" }

`GET /api/audit-log`

Query the audit trail.

Auth: Admin Bearer token

Query Parameters:

Parameter	Type	Description
`userId`	string	Filter by user ID
`project`	string	Filter by project name
`limit`	number	Max entries (default: 100, max: 500)

Response:

{
  "status": "ok",
  "entries": [
    {
      "id": "audit-uuid",
      "userId": "user-uuid",
      "action": "ingest_interaction",
      "project": "cpv",
      "detail": "Pushed 3 interactions from cursor",
      "timestamp": 1714800000000
    }
  ],
  "count": 1
}

On this page