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

# Answer with brain conditioning

> Generate a written answer from retrieved content, optionally conditioned by ExoBrain signals.

With `arm` set to `baseline` the answer comes from cosine retrieval and the persona prompt alone. With `arm` set to `brain` the forward pass runs first: omit `tercile_boundaries` and the call returns the raw signals and skips generation (`answer` is an empty string), so a caller can collect signals across a batch of questions before computing boundaries; supply `tercile_boundaries` and those signals are rendered into the prompt before the answer is generated.

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 generated answer, the prompt that produced it, and the brain signals when the brain arm ran. |

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


## OpenAPI

````yaml openapi.json POST /v1/brain/answer
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/answer:
    post:
      tags:
        - brain
      summary: Answer with brain conditioning
      description: >-
        Generate a written answer from retrieved content, optionally conditioned
        by ExoBrain signals.


        With `arm` set to `baseline` the answer comes from cosine retrieval and
        the persona prompt alone. With `arm` set to `brain` the forward pass
        runs first: omit `tercile_boundaries` and the call returns the raw
        signals and skips generation (`answer` is an empty string), so a caller
        can collect signals across a batch of questions before computing
        boundaries; supply `tercile_boundaries` and those signals are rendered
        into the prompt before the answer is generated.


        Reads the API key owner's own content, so the `X-Exo-Subject` selector
        is not accepted here.
      operationId: postBrainAnswer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrainAnswerRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrainAnswerResponse'
          description: >-
            The generated answer, the prompt that produced it, and the brain
            signals when the brain arm ran.
        '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:
    BrainAnswerRequest:
      description: Request for /v1/brain/answer.
      properties:
        arm:
          enum:
            - baseline
            - brain
          title: Arm
          type: string
        k:
          default: 8
          maximum: 50
          minimum: 1
          title: K
          type: integer
        question:
          minLength: 3
          title: Question
          type: string
        tercile_boundaries:
          anyOf:
            - $ref: '#/components/schemas/TercileBoundaries'
            - type: 'null'
      required:
        - question
        - arm
      title: BrainAnswerRequest
      type: object
    BrainAnswerResponse:
      description: Response for /v1/brain/answer.
      properties:
        answer:
          title: Answer
          type: string
        brain_signals:
          anyOf:
            - $ref: '#/components/schemas/BrainSignalsOut'
            - type: 'null'
        prompt_used:
          additionalProperties: true
          title: Prompt Used
          type: object
        retrieval_chunk_ids:
          items:
            type: string
          title: Retrieval Chunk Ids
          type: array
      required:
        - answer
        - prompt_used
        - retrieval_chunk_ids
      title: BrainAnswerResponse
      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
    TercileBoundaries:
      description: >-
        Corpus-relative cut points that turn raw ExoBrain signals into prose.


        Confidence and drift saturate in absolute terms, so /v1/brain/answer
        bands

        them against the caller's own corpus instead of fixed thresholds.
        Collect

        the raw signals first (call /v1/brain/answer with `arm` set to `brain`
        and

        no boundaries), compute the terciles across that batch, then send them
        back

        on the generating call.


        Doc-only note: each field is a fixed-length pair, which Pydantic renders
        as

        JSON Schema 2020-12 `prefixItems`. The `json_schema_extra` sibling
        `items`

        is a documentation aid for OpenAPI tooling that predates `prefixItems`

        (Spectral's `array-items` rule); it is accurate (every element is a
        number)

        and has no effect on validation.
      properties:
        confidence:
          description: Confidence cut points as [lowMax, midMax].
          items:
            type: number
          maxItems: 2
          minItems: 2
          prefixItems:
            - type: number
            - type: number
          title: Confidence
          type: array
        drift_rate:
          description: Drift-rate cut points as [lowMax, midMax].
          items:
            type: number
          maxItems: 2
          minItems: 2
          prefixItems:
            - type: number
            - type: number
          title: Drift Rate
          type: array
      required:
        - confidence
        - drift_rate
      title: TercileBoundaries
      type: object
    BrainSignalsOut:
      description: Raw + rendered ExoBrain signals (brain arm only).
      properties:
        appendix_lines:
          items:
            type: string
          title: Appendix Lines
          type: array
        confidence:
          title: Confidence
          type: number
        contradictions:
          items:
            additionalProperties: true
            type: object
          title: Contradictions
          type: array
        drift_rate:
          title: Drift Rate
          type: number
        tier:
          title: Tier
          type: string
        use_system2:
          title: Use System2
          type: boolean
      required:
        - confidence
        - drift_rate
        - use_system2
        - tier
        - contradictions
        - appendix_lines
      title: BrainSignalsOut
      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

````