> ## 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.

# Knowledge Bases

> List, create, inspect, and delete company knowledge bases.

A company has one default knowledge base (provisioned lazily on first use) and may have additional named KBs. Each KB is company-scoped and stamped with an immutable provider (default `postgres`).

## List knowledge bases

`GET /v1/brain`

<RequestExample>
  ```bash theme={"theme":"css-variables"}
  curl https://api.usenaive.ai/v1/brain \
    -H "Authorization: Bearer nv_sk_live_..."
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":"css-variables"}
  {
    "knowledge_bases": [
      { "id": "kb-uuid", "name": "Default Brain", "status": "active", "is_default": true, "created_at": "2026-07-01T00:00:00.000Z" }
    ],
    "count": 1
  }
  ```
</ResponseExample>

## Create a knowledge base

`POST /v1/brain`

<ParamField body="name" type="string">
  Name for the knowledge base (1–120 chars). Defaults to "Default Brain".
</ParamField>

<ParamField body="is_default" type="boolean">
  Make this the company's default knowledge base.
</ParamField>

<RequestExample>
  ```bash theme={"theme":"css-variables"}
  curl -X POST https://api.usenaive.ai/v1/brain \
    -H "Authorization: Bearer nv_sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{ "name": "Engineering Docs", "is_default": false }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":"css-variables"}
  { "id": "kb-uuid", "name": "Engineering Docs", "status": "provisioning", "is_default": false }
  ```
</ResponseExample>

## Runtime status

`GET /v1/brain/status` — embed/answer/rerank/GBrain health plus KB/document/projection counts. Not plan-metered.

<ResponseExample>
  ```json 200 theme={"theme":"css-variables"}
  {
    "provider": "postgres",
    "semantic_engine": "gbrain",
    "embed": { "configured": true },
    "answer": { "configured": true },
    "gbrain": { "healthy": true, "mode": "engine" },
    "knowledge_bases": 2,
    "documents": 47,
    "projection": { "pending": 0, "failed": 0 }
  }
  ```
</ResponseExample>

## Delete a knowledge base

`DELETE /v1/brain/:id` — deletes the KB and all its documents (permanent). **Approval-gated** for agent callers (returns `202` pending); returns a deletion receipt on completion.

<RequestExample>
  ```bash theme={"theme":"css-variables"}
  curl -X DELETE https://api.usenaive.ai/v1/brain/kb-uuid \
    -H "Authorization: Bearer nv_sk_live_..."
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":"css-variables"}
  { "deleted": true, "receipt": { "provider": "postgres", "provider_confirmed": true, "verified": true, "deleted_at": "2026-07-09T12:00:00.000Z" } }
  ```
</ResponseExample>