# BrainAPI API Documentation (https://brainapi.lumen-labs.ai/docs/v2/reference)

> For the complete BrainAPI documentation index, see [llms.txt](https://brainapi.lumen-labs.ai/docs/llms.txt). A markdown version of any docs page is available by appending `.md` to its URL (e.g. https://brainapi.lumen-labs.ai/docs/v2/reference.md).

Understand BrainAPI core routes, authentication, brain scope, generated contracts, and plugin boundaries

The core REST API is available through `https://brain-api.dev/api`, directly at `https://api.brain-api.dev`, or locally at `http://localhost:8000`. Download the machine-readable [BrainAPI OpenAPI 3.1 specification](https://brain-api.dev/openapi.json). This reference is generated from the current `2.17.0-dev` route and Pydantic contract, then annotated with middleware authentication and brain-scoping behavior that FastAPI cannot infer automatically.

## Common request shape

```bash
curl --fail-with-body http://localhost:8000/<path> \
  -H "BrainPAT: $BRAINPAT_TOKEN" \
  -H "X-Brain-ID: $BRAIN_ID"
```

`Authorization: Bearer <token>` is also supported. System routes require the system PAT. Most other routes require a brain selected by header, query, body, or multipart field; prefer the header.

## Core API groups

| Group | Purpose |
| --- | --- |
| [Public](https://brainapi.lumen-labs.ai/docs/v2/reference/api/public) | Check service health or search the public documentation sandbox without credentials. |
| [Ingest](https://brainapi.lumen-labs.ai/docs/v2/reference/api/ingest) | Submit text, files, or structured data. |
| [Retrieve](https://brainapi.lumen-labs.ai/docs/v2/reference/api/retrieve) | Read context, search hits, graph data, chunks, observations, and recommendations. |
| [Model](https://brainapi.lumen-labs.ai/docs/v2/reference/api/model) | Create or update entities and relationships. |
| [Metadata](https://brainapi.lumen-labs.ai/docs/v2/reference/api/meta) | Resolve PAT scope and inspect graph labels/properties. |
| [Tasks](https://brainapi.lumen-labs.ai/docs/v2/reference/api/tasks) | List and inspect asynchronous task state. |
| [System](https://brainapi.lumen-labs.ai/docs/v2/reference/api/system) | List and create brains with the system PAT. |

## Generated versus authored guidance

Generated pages are the exact field/type reference. Task guides explain why and when to use an operation, how several operations form a workflow, and which failure to diagnose. Link to generated reference instead of copying field tables into every tutorial.

## Plugin APIs

Plugins register routes dynamically at startup and are not part of the core snapshot. Their pages document installation, compatibility, health, lifecycle, and route contracts. See [Plugins overview](https://brainapi.lumen-labs.ai/docs/v2/plugins).

## Unavailable System operations

The source currently declares reset, delete, and create-backup route stubs, but each raises `NotImplementedError`. They are deliberately absent from generated usable endpoints. Do not integrate them until implementation and tests ship.

## Contract synchronization

The checked-in schema is exported from the sibling `brainapi2` source:

```bash
npm run api:sync
npm run api:generate
npm run api:check
```

`api:check` fails when the current source produces a different documented schema.