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

# Overview

> A brain is a graph-based knowledge structure you can read and query over the API.

A **brain** is a knowledge structure Versuno builds when it indexes a source like a docs site or a corpus. Think of it as a graph made of two kinds of things:

* **Containers:** the folders and groups that give the brain its shape. A container can hold other containers.
* **Nodes:** the actual content, meaning the pages and the chunks inside them. Nodes live inside containers.

There are two ways to get at that content. You can walk the graph yourself, or you can run a semantic query that searches the whole brain and hands back the most relevant pages, chunks, and chunk parts. Every endpoint sits under the **Brains** group in the API Reference.

## Reading a brain

<Steps>
  <Step title="Find a brain">
    `GET /brains/public` lists the public brains. If you already have an ID, `GET /brains/{id}` fetches that one.
  </Step>

  <Step title="Walk the containers">
    `GET /brains/{id}/containers` gives you a flat list. `GET /brains/{id}/containers/tree` gives you the same containers nested in their hierarchy.
  </Step>

  <Step title="List the nodes">
    `GET /brains/{id}/containers/{containerId}/nodes` returns lightweight previews (id, summary, type) rather than full content. Use the `/nodes/tree` variant when you want them nested.
  </Step>

  <Step title="Read a node">
    `GET /brains/{id}/nodes/{nodeId}` returns a single node with its full content.
  </Step>
</Steps>

## Querying a brain

Most of the time you do not want to walk the whole graph. You want an answer. That is what query is for:

<CardGroup cols={2}>
  <Card title="Query a brain" icon="magnifying-glass">
    `POST /brains/{id}/query` searches across the whole brain.
  </Card>

  <Card title="Query a container" icon="folder-magnifying-glass">
    `POST /brains/{id}/containers/{containerId}/query` narrows the search to one container.
  </Card>
</CardGroup>

Send a natural-language `query`, and optionally a `limit` between 1 and 20 (it defaults to 5). You get back the matched `pages`, `chunks`, and `chunk_parts`, a `graph_tree` that ties them together, and the relations between them.

If a brain has `exampleQueries` set, those are AI-generated starting points. Try one of those first.

<Warning>
  `POST /brains/{id}/query` is metered. Every call counts against your brain-query usage, and that includes hitting the "Send" button in these docs. The container query is not metered.
</Warning>

<Note>
  These endpoints always return HTTP 200, even when the query fails. Read the `success` and `error` fields in the response body to find out what actually happened, rather than relying on the status code.
</Note>

## Access scope

Reading and querying do not see the same set of brains:

* **Read endpoints** use your own API key, so you can read any public brain plus any brain you own.
* **Query endpoints** run under a shared Versuno service identity instead of your personal access, so they resolve public brains by ID.