> ## Documentation Index
> Fetch the complete documentation index at: https://usenaive.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Brain API

> Company knowledge base + memory over /v1/brain — document RAG, semantic memory, and governance.

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](/docs/api-reference/brain/knowledge-bases) |
| Documents       | `GET/POST /documents`, `PUT/GET/DELETE /documents/:id`       | [Documents](/docs/api-reference/brain/documents)             |
| Query           | `POST /query`                                                | [Query](/docs/api-reference/brain/query)                     |
| Semantic memory | `POST /remember`, `/recall`, `/think`, `/graph`, `/timeline` | [Memory](/docs/api-reference/brain/memory)                   |
| Deletion        | `POST /forget`                                               | [Forget & deletion](/docs/api-reference/brain/forget)        |
| Bus             | `GET/POST /bus/events`, `GET /bus/events/stream`             | [Brain Bus](/docs/api-reference/brain/bus)                   |
| Operations      | writebacks, proposals, objects, prod-gates, bakeoff          | [Operations](/docs/api-reference/brain/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:

```json theme={"theme":"css-variables"}
{
  "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.