Skip to main content
This page explains what a public brain actually is under the hood: how its content is organised, who can read it, and what happens when you run a query. If you just want the endpoints, start with the Brains overview.

​
The data model

A brain is a graph. Versuno builds it by indexing a source, then storing the result as two kinds of objects:
  • Containers are the folders. They give the brain its shape, and a container can hold other containers.
  • Nodes are the content. Every node has a type, and the two you will see most are page (a document) and chunk (a section of a page).
Containers nest into a tree, and nodes hang off the containers: 
Brain "Next.js Docs"
├─ Container "Routing"
│  ├─ Container "App Router"
│  │  └─ Node (page) "Dynamic Routes"
│  └─ Node (page) "Linking and Navigating"
└─ Container "Data Fetching"
   └─ Node (page) "Caching"
A page-type node can sit at the root of the brain with no container above it, which is why nodes carry both a containerId (the folder they belong to) and a brainId (the brain they belong to).

​
Inside a page

A single page breaks down further when you query it. A page contains chunks, and each chunk contains chunk parts. The chunk part is the smallest retrievable unit, and it is what a query scores for relevance: 
Page "Dynamic Routes"
└─ Chunk "The params prop"
   ├─ Chunk part 1   relevancy 0.82
   └─ Chunk part 2   relevancy 0.71
You never have to assemble this yourself. A query returns the pages, chunks, and chunk parts it matched, plus a graph_tree that ties them back together in this shape.

​
Public versus private

Every brain has an isPublic flag. It controls who is allowed to read the brain and everything inside it:
  • A public brain is readable by anyone with a valid API key. The same applies to its containers and its nodes.
  • A private brain is readable only by its owner.
A “public brain” is not a separate object type. It is an ordinary brain with isPublic set to true, which opens up read access at the database level for that brain and its whole subtree.

​
Access and security

Reading a brain and querying a brain take two different paths, and they resolve different sets of brains. This is the part worth understanding before you build against the API. 
Read   GET /brains/...           your API key        →  public brains + brains you own
Query  POST /brains/{id}/query   shared service id   →  public brains
  • Read endpoints run as you. They use your API key, so row-level security lets you see any public brain plus any brain you own.
  • Query endpoints do not run as you. They run under a shared Versuno service identity, so they resolve public brains by ID regardless of who owns them. Your API key is still required and still validated at the edge, but it is not the identity that reads the data.
Two consequences fall out of this:
  1. You cannot currently query a private brain through the public API, even one you own, because the query runs as the service identity rather than as you.
  2. The brain-level query is metered. Each call to POST /brains/{id}/query counts against your usage. The container-scoped query is not metered.
Everything here is read only. There is no public endpoint to write into a brain yet.

​
How a query runs

When you call a query endpoint, this is the pipeline it goes through:
1

Embed the query

Your natural-language query is turned into a vector embedding.
2

Search the brain

A vector search ranks chunk parts across the brain by similarity. You can narrow it to a single container, bias it toward named entities, and cap the results with limit (1 to 20, default 5).
3

Assemble the graph

The matched chunk parts are rolled back up into their chunks and pages, and the relations between objects are attached as graph_context.
4

Return the result

You get the matched objects (pages, chunks, chunk parts), the graph_tree linking them, the relations, and metadata with the embedding and query latencies.
Because the query always returns HTTP 200, check the success and error fields in the envelope rather than the status code. See the Query a brain endpoint for the full request and response shape.

​
Where this is heading

Public brains are the read-only, public foundation of something larger. The roadmap is universal memory: a per-user context brain that any model, tool, or agent can both read from and write to, persisting what your AI learns across sessions and across tools. The query pipeline and graph model on this page are the groundwork that layer is being built on.