Skip to main content
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

1

Find a brain

GET /brains/public lists the public brains. If you already have an ID, GET /brains/{id} fetches that one.
2

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

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

Read a node

GET /brains/{id}/nodes/{nodeId} returns a single node with its full content.

​
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:

Query a brain

POST /brains/{id}/query searches across the whole brain.

Query a container

POST /brains/{id}/containers/{containerId}/query narrows the search to one container.
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.
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.
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.

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