# BrainAPI V2 (https://brainapi.lumen-labs.ai/docs/v2)

> 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.md).

Build, operate, and extend applications on a traceable knowledge graph

BrainAPI turns text, files, and structured events into a shared knowledge base for context retrieval, ranked search, recommendations, and agent tools. You choose how much structure and ranking you need; BrainAPI keeps every request scoped to a brain.

<Callout type="info" title="Current documentation">
These pages describe BrainAPI `2.17.0-dev`. V1 remains available as **Legacy**, but start with V2 for new systems.
</Callout>

## Choose your path

<Cards>
  <Card title="Build an application" href="/v2/quickstart">
    Start BrainAPI, ingest one document, wait for the asynchronous task, and retrieve grounded context.
  </Card>
  <Card title="Operate BrainAPI" href="/v2/installation">
    Deploy the services, configure providers and storage, inspect health, and diagnose failures.
  </Card>
  <Card title="Extend BrainAPI" href="/v2/plugins">
    Connect agents through MCP or add routes, lifecycle hooks, retrievers, rerankers, and recommendation models.
  </Card>
</Cards>

## The product in one minute

1. **Ingest** text, files, or explicit graph facts into a named brain.
2. **Process** the input asynchronously with deterministic logic and, when configured, specialized extraction agents.
3. **Store** passages, entities, relationships, events, observations, and vectors in the configured backends.
4. **Retrieve** the representation suited to your application: context packs, ranked hits, recommendations, graph facts, or agent tools.

The brain is the isolation boundary. A request normally carries a `BrainPAT` token and an `X-Brain-ID` header; BrainAPI validates both before reading or writing data.

## What you can build

| Goal | Start with | Why |
| --- | --- | --- |
| Ground an assistant | [Context](https://brainapi.lumen-labs.ai/docs/v2/retrieval/context) | Returns passages and graph context ready for an LLM prompt. |
| Search documentation or support data | [Search](https://brainapi.lumen-labs.ai/docs/v2/retrieval/search) | Returns ranked, inspectable hits with optional graph and plugin stages. |
| Suggest related content or next actions | [Recommendations](https://brainapi.lumen-labs.ai/docs/v2/retrieval/recommendations) | Starts from a user or item rather than a text query. |
| Investigate connected events | [Graph retrieval](https://brainapi.lumen-labs.ai/docs/v2/retrieval/entities/synergies) | Exposes relationships and traversal signals directly. |
| Give an agent tools | [MCP](https://brainapi.lumen-labs.ai/docs/v2/agentic/MCP) | Lets compatible runtimes call BrainAPI without embedding REST details in prompts. |

## What BrainAPI is not

BrainAPI is not a replacement for ordinary CRUD when rows and foreign keys already answer the problem. It is most useful when information arrives as changing language or events, multiple representations must coexist, or a caller needs traceable relationships behind an answer.

## First successful request

The [Quickstart](https://brainapi.lumen-labs.ai/docs/v2/quickstart) takes you from an empty machine to a completed ingest-and-retrieve flow. If BrainAPI is already running, go directly to [Authentication and brains](https://brainapi.lumen-labs.ai/docs/v2/brains-and-auth), then choose [how to ingest](https://brainapi.lumen-labs.ai/docs/v2/ingestion) and [how to retrieve](https://brainapi.lumen-labs.ai/docs/v2/retrieval).

## Help and machine-readable docs

- [Health and troubleshooting](https://brainapi.lumen-labs.ai/docs/v2/troubleshooting)
- [API reference](https://brainapi.lumen-labs.ai/docs/v2/reference)
- [What's new](https://brainapi.lumen-labs.ai/docs/v2/changelog)
- [GitHub](https://github.com/Lumen-Labs/brainapi2)
- [Discord](https://discord.gg/VTngQTaeDf)
- [llms.txt](https://brainapi.lumen-labs.ai/docs/llms.txt) and [Docs MCP](https://brainapi.lumen-labs.ai/docs/v2/agentic/docs-mcp)