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

# Query a brain

> Runs a semantic (RAG) search over a brain and returns the most relevant pages, chunks, and chunk parts, plus the graph relations between them.

**This query runs under a shared Versuno service identity, not your API key's personal scope.** It can therefore resolve any **public** brain by ID. (The read endpoints, by contrast, use your own access and can also see your private brains.)

**This endpoint is metered** — each call counts against your brain-query usage. Running the interactive example below will consume quota.

Always returns HTTP `200`; inspect `success` and `error` in the response envelope to detect failures.


<Warning>Sending this request runs the live, **metered** query endpoint and consumes your brain-query quota.</Warning>


## OpenAPI

````yaml /openapi.yaml post /brains/{id}/query
openapi: 3.1.0
info:
  title: Versuno Public API
  description: >
    The Versuno Public API lets you manage AI assets, projects, and version
    history programmatically.


    All endpoints except key management require a Bearer API key in the
    `Authorization` header.

    API keys are formatted as
    `uk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`.
  version: 1.0.0
  contact:
    email: support@versuno.ai
servers:
  - url: https://versuno.ai/api/public
    description: Production
  - url: http://localhost:3000/api/public
    description: Local development
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: Verify API key validity and retrieve the caller's identity.
  - name: Teams
    description: Teams the authenticated user owns or is an active member of.
  - name: Assets
    description: AI assets — prompts, personas, contexts, system prompts, and skills.
  - name: Asset Trash
    description: Single-asset soft-delete, restore, and permanent delete lifecycle.
  - name: Bulk Asset Trash
    description: Bulk trash operations across multiple assets at once.
  - name: Projects
    description: Project folders for organising assets and teams.
  - name: Project Trash
    description: Project trash lifecycle — trashing deletes the entire subtree.
  - name: Versioning
    description: Full-snapshot version history with non-destructive revert support.
  - name: Public Brains
    description: >-
      Graph-based knowledge structures composed of containers (folders/groups)
      and nodes (content items). Read the graph, or run semantic RAG queries
      against it.
  - name: Memory
    description: >-
      The universal agent-memory layer. Capture coding-agent memory, recall it
      semantically, and resolve contradictions. Capture-only, scoped to your API
      key's account.
  - name: Key Management
    description: >-
      Create, update, and delete API keys. These endpoints do not require a
      Bearer token.
paths:
  /brains/{id}/query:
    post:
      tags:
        - Public Brains
      summary: Query a brain
      description: >
        Runs a semantic (RAG) search over a brain and returns the most relevant
        pages, chunks, and chunk parts, plus the graph relations between them.


        **This query runs under a shared Versuno service identity, not your API
        key's personal scope.** It can therefore resolve any **public** brain by
        ID. (The read endpoints, by contrast, use your own access and can also
        see your private brains.)


        **This endpoint is metered** — each call counts against your brain-query
        usage. Running the interactive example below will consume quota.


        Always returns HTTP `200`; inspect `success` and `error` in the response
        envelope to detect failures.
      operationId: queryBrain
      parameters:
        - name: id
          in: path
          required: true
          description: ID of the brain to query.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  minLength: 1
                  maxLength: 4000
                  description: The natural-language query to search the brain with.
                  example: How do I set up dynamic routes?
                entities:
                  type: array
                  items:
                    type: string
                  description: Optional list of entity names to bias the search toward.
                  example:
                    - routing
                    - app-router
                limit:
                  type: integer
                  minimum: 1
                  maximum: 20
                  default: 5
                  description: Maximum number of results to return (1–20, default 5).
                  example: 5
      responses:
        '200':
          description: >-
            Query result envelope. Check `success` to determine if the query
            actually succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrainQueryResponse'
        '400':
          description: Invalid request parameters (bad brain ID or invalid body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
components:
  schemas:
    BrainQueryResponse:
      type: object
      description: >-
        Result envelope for a brain query. Always returned with HTTP 200; check
        `success` and `error`.
      properties:
        success:
          type: boolean
          description: >-
            Whether the query succeeded. Inspect this rather than the HTTP
            status.
          example: true
        data:
          anyOf:
            - type: object
              properties:
                objects:
                  type: object
                  properties:
                    chunks:
                      type: array
                      items:
                        $ref: '#/components/schemas/BrainChunk'
                    chunk_parts:
                      type: array
                      items:
                        $ref: '#/components/schemas/BrainChunkPart'
                    pages:
                      type: array
                      items:
                        $ref: '#/components/schemas/BrainPage'
                graph_tree:
                  type: array
                  description: Hierarchical tree of matched pages, chunks, and chunk parts.
                  items:
                    $ref: '#/components/schemas/BrainGraphTreeElement'
                graph_context:
                  type: object
                  properties:
                    relations:
                      type: object
                      description: Map of object ID to its outgoing relations.
                      additionalProperties:
                        type: array
                        items:
                          $ref: '#/components/schemas/BrainRelation'
            - type: 'null'
          description: Query result payload, or null when `success` is false.
        error:
          anyOf:
            - type: string
            - type: 'null'
          description: Error message when `success` is false, otherwise null.
          example: null
        metadata:
          type: object
          properties:
            query_latency_ms:
              type: number
              description: Time spent running the vector query, in milliseconds.
              example: 142
            embedding_latency_ms:
              type: number
              description: Time spent embedding the query string, in milliseconds.
              example: 88
    Error400:
      type: object
      properties:
        error:
          type: string
          example: 'Wrong data: assetType is required'
    Error401:
      type: object
      properties:
        error:
          type: string
          example: Invalid API key
    BrainChunk:
      type: object
      description: A matched chunk of content within a page.
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - chunk
        parent_id:
          type: string
          format: uuid
        container_id:
          type: string
          format: uuid
        brain_id:
          type: string
          format: uuid
        page_id:
          type: string
          format: uuid
        canonical:
          type: string
        created_at:
          type: string
        updated_at:
          type: string
    BrainChunkPart:
      type: object
      description: A scored sub-part of a chunk — the smallest retrievable unit.
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - chunk_part
        parent_id:
          type: string
          format: uuid
        container_id:
          type: string
          format: uuid
        brain_id:
          type: string
          format: uuid
        content:
          type: string
          description: The text content of this part.
          example: Dynamic segments are passed as the params prop...
        relevancy_score:
          type: number
          minimum: 0
          maximum: 1
          description: Similarity score against the query, 0–1.
          example: 0.82
        metadata:
          type: object
          properties:
            num:
              type: integer
              description: Ordinal position of this part within its chunk.
              example: 2
        created_at:
          type: string
        updated_at:
          type: string
    BrainPage:
      type: object
      description: A matched page within the brain.
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - page
        parent_id:
          type: string
          format: uuid
        container_id:
          type: string
          format: uuid
        brain_id:
          type: string
          format: uuid
        canonical:
          type: string
        metadata:
          type: object
          properties:
            urlGroup:
              type: array
              items:
                type: string
        created_at:
          type: string
        updated_at:
          type: string
    BrainGraphTreeElement:
      type: object
      description: A node in the result tree, linking pages → chunks → chunk parts.
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - page
            - chunk
            - chunk_part
        children:
          type: array
          items:
            $ref: '#/components/schemas/BrainGraphTreeElement'
    BrainRelation:
      type: object
      description: A typed, weighted relation between two objects in the brain graph.
      properties:
        to_id:
          type: string
          format: uuid
        relation:
          type: string
          enum:
            - mention
            - reference
            - relevant
            - link
        weight:
          type: number
          minimum: 0
          maximum: 1
          description: Strength of the relation, 0–1.
          example: 0.6
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Versuno API key. Must be prefixed with `Bearer`. Format: `Bearer
        uk_live_...`
      x-default: Bearer uk_live_your_api_key_here

````