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

# Query the ExoBrain

> Run one ExoBrain forward pass over the org's knowledge graph and return the glass-box result: the focal nodes the model settled on, the cosine top-K head for comparison, gate confidence, drift rate,.

Run one ExoBrain forward pass over the org's knowledge graph and return the glass-box result: the focal nodes the model settled on, the cosine top-K head for comparison, gate confidence, drift rate, propagation tier and any contradictions among the activated nodes.

Requires a trained brain for the org (see `POST /v1/brain/train`); returns 404 when no brain artifact exists yet, and 409 while a newly published artifact is still being picked up. This route reads the API key owner's own content, so the `X-Exo-Subject` selector is not accepted here.

## Authorization

This route requires the `read` scope.

A missing or invalid credential returns 401 [`authentication_error`](/errors/authentication_error). A valid credential without the scope returns 403 [`permission_denied`](/errors/permission_denied), and the problem body names the exact scope required.

## Headers

These are request conventions the contract does not declare as parameters, so they do not appear in the schema tables below.

| Header            | Applies      | What it does                                                                                                                                                                        |
| ----------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-Exo-API-Key`   | Required     | Your Exo API key, `exo_<env>_<token>`. `Authorization: Bearer exo_...` is accepted as an alternate.                                                                                 |
| `X-Exo-Subject`   | Refused      | This route scopes data by the key owner. Sending the header returns 400 [`subject_not_supported`](/errors/subject_not_supported), rather than silently reading the wrong partition. |
| `Idempotency-Key` | Not honoured | This route does not replay: reads have no side effect to replay.                                                                                                                    |
| `X-Request-Id`    | Response     | Returned on every response, including `204`s. Quote it in a support request.                                                                                                        |

## Success responses

| Status | Meaning                                                                 |
| ------ | ----------------------------------------------------------------------- |
| `200`  | The focal set, cosine head and cognitive signals from the forward pass. |

## Errors

| Status | Code                                                   | When                                                           |
| ------ | ------------------------------------------------------ | -------------------------------------------------------------- |
| `400`  | [`invalid_request`](/errors/invalid_request)           | Malformed request, for example an invalid cursor.              |
| `401`  | [`authentication_error`](/errors/authentication_error) | Missing or invalid credentials.                                |
| `403`  | [`permission_denied`](/errors/permission_denied)       | Missing scope, or an unprovisioned subject selector.           |
| `404`  | [`not_found`](/errors/not_found)                       | The resource does not exist, or is not visible to this caller. |
| `409`  | [`conflict`](/errors/conflict)                         | A conflict with the current state of the resource.             |
| `422`  | [`validation_error`](/errors/validation_error)         | The request was understood but failed field validation.        |
| `429`  | [`rate_limit_exceeded`](/errors/rate_limit_exceeded)   | Rate limit exceeded. Retry after the Retry-After interval.     |
| `503`  | [`service_degraded`](/errors/service_degraded)         | A dependency is temporarily unavailable. Safe to retry.        |

Every error is an RFC 9457 `application/problem+json` body carrying a stable `code`, a `requestId`, and a `suggestedAction` where Exo has one. See [Errors](/platform/errors).

## Notes

* **Requires a trained brain.** No artifact yet is 404, and a freshly published artifact that is still being picked up is 409.
* **This route reads the key owner's own content.** `X-Exo-Subject` is refused with 400 `subject_not_supported` rather than silently ignored.


## OpenAPI

````yaml openapi.json POST /v1/brain/query
openapi: 3.1.0
info:
  contact:
    name: Exo
    url: https://get-exo.com/
  description: >-
    The Exo public developer API: ingest content, retrieve identity-conditioned
    context, and read the knowledge graph. Authenticate every request with an
    Exo API key, either as the X-Exo-API-Key header or as Authorization: Bearer
    exo_... . Errors follow RFC 9457 problem+json with a stable snake_case code
    on every body.
  title: Exo API
  version: 1.0.0
servers:
  - url: https://api.get-exo.com
security:
  - ApiKeyHeader: []
  - BearerAuth: []
tags:
  - name: retrieve
    x-group: Retrieval
  - name: search
    x-group: Search
  - name: ingest
    x-group: Ingestion
  - name: jobs
    x-group: Jobs
  - name: subjects
    x-group: Subjects
  - name: recall
    x-group: Recall
  - name: graph
    x-group: Graph
  - name: insights
    x-group: Contradictions and proposals
  - name: condition
    x-group: Condition
  - name: brain
    x-group: Brain
  - name: sessions
    x-group: Coding sessions
  - name: connectors
    x-group: Connectors
  - name: events
    x-group: Events and webhooks
  - name: meta
    x-group: Identity
  - name: keys
    x-group: Keys and sandbox
  - name: usage
    x-group: Usage
  - name: settings
    x-group: Settings
  - name: exports
    x-group: Exports
  - name: team
    x-group: Team
  - name: admin
    x-group: Account and purge
paths:
  /v1/brain/query:
    post:
      tags:
        - brain
      summary: Query the ExoBrain
      description: >-
        Run one ExoBrain forward pass over the org's knowledge graph and return
        the glass-box result: the focal nodes the model settled on, the cosine
        top-K head for comparison, gate confidence, drift rate, propagation tier
        and any contradictions among the activated nodes.


        Requires a trained brain for the org (see `POST /v1/brain/train`);
        returns 404 when no brain artifact exists yet, and 409 while a newly
        published artifact is still being picked up. This route reads the API
        key owner's own content, so the `X-Exo-Subject` selector is not accepted
        here.
      operationId: postBrainQuery
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrainQueryRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrainQueryResponse'
          description: >-
            The focal set, cosine head and cognitive signals from the forward
            pass.
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: Malformed request, for example an invalid cursor.
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: Missing or invalid credentials.
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: Missing scope or unprovisioned subject.
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: The requested resource does not exist.
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: Conflict, for example a duplicate in-flight idempotent request.
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: Validation Error
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: >-
            Rate limit exceeded; retry after the interval in the Retry-After
            header.
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: A dependency is temporarily unavailable; safe to retry with backoff.
components:
  schemas:
    BrainQueryRequest:
      description: An ExoBrain forward-pass request.
      properties:
        focal_display:
          default: 5
          description: How many focal nodes to return.
          maximum: 20
          minimum: 1
          title: Focal Display
          type: integer
        question:
          description: Free-text query.
          title: Question
          type: string
        seed_k:
          default: 200
          description: Cosine top-K seed set size (controls tier).
          maximum: 2000
          minimum: 10
          title: Seed K
          type: integer
      required:
        - question
      title: BrainQueryRequest
      type: object
    BrainQueryResponse:
      description: >-
        The glass-box result of one ExoBrain forward pass.


        ``focal`` is the working-memory set the model settled on, ``cosine_top``
        is

        the plain nearest-neighbour head for comparison, and ``confidence`` /

        ``drift_rate`` / ``tier`` / ``use_system2`` are the cognitive signals
        that

        drove the propagation.
      properties:
        alias:
          title: Alias
          type: string
        confidence:
          title: Confidence
          type: number
        contradictions:
          items:
            additionalProperties: true
            type: object
          title: Contradictions
          type: array
        cosine_top:
          description: Cosine top-K head for comparison (node_id, score, snippet).
          items:
            additionalProperties: true
            type: object
          title: Cosine Top
          type: array
        drift_rate:
          default: 0
          title: Drift Rate
          type: number
        focal:
          items:
            $ref: '#/components/schemas/BrainFocalNode'
          title: Focal
          type: array
        latency_ms:
          title: Latency Ms
          type: number
        model_params:
          default: 0
          title: Model Params
          type: integer
        negative_edges_in_subgraph:
          default: 0
          title: Negative Edges In Subgraph
          type: integer
        question:
          title: Question
          type: string
        subgraph:
          additionalProperties:
            type: integer
          title: Subgraph
          type: object
        system_used:
          default: '?'
          title: System Used
          type: string
        tenant_id:
          title: Tenant Id
          type: string
        tier:
          title: Tier
          type: string
        use_system2:
          default: false
          title: Use System2
          type: boolean
      required:
        - question
        - tenant_id
        - alias
        - focal
        - confidence
        - tier
        - latency_ms
        - subgraph
      title: BrainQueryResponse
      type: object
    Problem:
      description: |-
        RFC 9457 problem+json envelope (spec D9), documented in OpenAPI.

        Invariant: ``code`` equals the tail of the ``type`` URI
        (``https://docs.get-exo.com/errors/<code>``).
      properties:
        code:
          title: Code
          type: string
        detail:
          title: Detail
          type: string
        documentationUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Documentationurl
        errors:
          anyOf:
            - items:
                $ref: '#/components/schemas/FieldViolation'
              type: array
            - type: 'null'
          title: Errors
        requestId:
          default: ''
          title: Requestid
          type: string
        status:
          title: Status
          type: integer
        suggestedAction:
          anyOf:
            - type: string
            - type: 'null'
          title: Suggestedaction
        title:
          title: Title
          type: string
        type:
          title: Type
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
      title: Problem
      type: object
    BrainFocalNode:
      description: One node the ExoBrain settled on as focal for the query.
      properties:
        cosine_in_seed:
          description: True if this focal node was in the cosine top-K head.
          title: Cosine In Seed
          type: boolean
        node_id:
          title: Node Id
          type: string
        snippet:
          title: Snippet
          type: string
      required:
        - node_id
        - snippet
        - cosine_in_seed
      title: BrainFocalNode
      type: object
    FieldViolation:
      description: A single field-level violation inside a Problem ``errors[]`` list.
      properties:
        code:
          title: Code
          type: string
        field:
          title: Field
          type: string
        message:
          title: Message
          type: string
        pointer:
          title: Pointer
          type: string
      required:
        - pointer
        - field
        - code
        - message
      title: FieldViolation
      type: object
  securitySchemes:
    ApiKeyHeader:
      description: An Exo API key (exo_...) sent as the X-Exo-API-Key header.
      in: header
      name: X-Exo-API-Key
      type: apiKey
    BearerAuth:
      description: The same Exo API key (exo_...) sent as an Authorization bearer token.
      scheme: bearer
      type: http

````