Brain API

The Brain API is mounted at /v1/brain (company-scoped) and /v1/users/{user_id}/brain (per-tenant). All routes require authentication (session cookie or Authorization: Bearer nv_sk_...) and the brain primitive to be enabled on the AccountKit — otherwise they return 403 primitive_disabled_by_kit.

Auth & gating

Auth: session or API key.
Entitlement: brain is an opt-in primitive (default off). Enable it in the AccountKit.
Metering: per-tenant plan quota is enforced on each call (except GET /status). Credit costs apply per operation (see below).
Idempotency: mutating routes accept an Idempotency-Key header.

Credits

Operation	Cost
`POST /query`, `POST /think`	10 credits
`POST /documents`, `PUT /documents/:id` (ingest)	5 credits
everything else	free (plan quota still applies)

Endpoint groups

Group	Routes	Reference
Knowledge bases	`GET/POST /`, `DELETE /:id`, `GET /status`	Knowledge bases
Documents	`GET/POST /documents`, `PUT/GET/DELETE /documents/:id`	Documents
Query	`POST /query`	Query
Semantic memory	`POST /remember`, `/recall`, `/think`, `/graph`, `/timeline`	Memory
Deletion	`POST /forget`	Forget & deletion
Bus	`GET/POST /bus/events`, `GET /bus/events/stream`	Brain Bus
Operations	writebacks, proposals, objects, prod-gates, bakeoff	Operations

Deletion receipts

Destructive routes (DELETE /:id, DELETE /documents/:id, POST /forget) are approval-gated for agent callers (return 202 pending) and return a deletion receipt on completion:

{
  "deleted": true,
  "receipt": {
    "provider": "postgres",
    "provider_confirmed": true,
    "verified": true,
    "deleted_at": "2026-07-09T12:00:00.000Z"
  }
}

verified: true means emptiness was confirmed post-purge; provider_confirmed alone means the purge call ran.

Overview

Endpoints

Auth & gating

Credits

Endpoint groups

Deletion receipts

​Auth & gating

​Credits

​Endpoint groups

​Deletion receipts

Auth & gating

Credits

Endpoint groups

Deletion receipts