Retrieve context

curl --request POST \
  --url https://api.get-exo.com/v1/retrieve \
  --header 'Content-Type: application/json' \
  --header 'X-Exo-API-Key: <api-key>' \
  --data '
{
  "query": "<string>"
}
'

import requests

url = "https://api.get-exo.com/v1/retrieve"

payload = { "query": "<string>" }
headers = {
    "X-Exo-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Exo-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({query: '<string>'})
};

fetch('https://api.get-exo.com/v1/retrieve', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "degraded": true,
  "latencyMs": 123,
  "query": "<string>",
  "sources": [
    {}
  ],
  "usage": {
    "brainInference": true,
    "embedTokens": 123,
    "readUnits": 123
  },
  "cognition": {
    "confidence": 123,
    "driftRate": 123,
    "tier": "<string>",
    "useSystem2": true,
    "focalNodeIds": [
      "<string>"
    ]
  },
  "contradictions": [],
  "degradationReason": "<string>",
  "traceId": ""
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

POST

retrieve

Retrieve context

curl --request POST \
  --url https://api.get-exo.com/v1/retrieve \
  --header 'Content-Type: application/json' \
  --header 'X-Exo-API-Key: <api-key>' \
  --data '
{
  "query": "<string>"
}
'

import requests

url = "https://api.get-exo.com/v1/retrieve"

payload = { "query": "<string>" }
headers = {
    "X-Exo-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Exo-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({query: '<string>'})
};

fetch('https://api.get-exo.com/v1/retrieve', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "degraded": true,
  "latencyMs": 123,
  "query": "<string>",
  "sources": [
    {}
  ],
  "usage": {
    "brainInference": true,
    "embedTokens": 123,
    "readUnits": 123
  },
  "cognition": {
    "confidence": 123,
    "driftRate": 123,
    "tier": "<string>",
    "useSystem2": true,
    "focalNodeIds": [
      "<string>"
    ]
  },
  "contradictions": [],
  "degradationReason": "<string>",
  "traceId": ""
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

Exo answers from the org’s trained ExoBrain when one is available and transparently falls back to a hybrid vector plus keyword search over your stored content otherwise; path and degraded say which engine served the call, and degraded is also true when the brain answered from a knowledge graph that has changed since it was trained (degradationReason is then brain_stale). The response carries ranked sources, any detected contradictions, a cognition block (brain path only) and a usage block. Data is scoped to the effective subject: the API key owner by default, or the subject named by the X-Exo-Subject header. Set stream to true to receive the same result as a text/event-stream carrying sources, contradictions, cognition and done events.

Authorization

This route requires the read scope. A missing or invalid credential returns 401 authentication_error. A valid credential without the scope returns 403 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`	Optional	Acts for a provisioned subject instead of the key owner. An unprovisioned id returns 403 `subject_not_provisioned`.
`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`	Ranked sources plus the contradiction, cognition and usage blocks.

Errors

Status	Code	When
`400`	`invalid_request`	Malformed request, for example an invalid cursor.
`401`	`authentication_error`	Missing or invalid credentials.
`403`	`permission_denied`	Missing scope, or an unprovisioned subject selector.
`404`	`not_found`	The resource does not exist, or is not visible to this caller.
`409`	`conflict`	A conflict with the current state of the resource.
`422`	`validation_error`	The request was understood but failed field validation.
`429`	`rate_limit_exceeded`	Rate limit exceeded. Retry after the Retry-After interval.
`503`	`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.

Notes

cognition is null on the hybrid path. The block is the brain’s reasoning trace, and the vector plus keyword fallback has no reasoning state to report. Read path before you read cognition.
degraded can be true on the brain path. It means the brain answered from a knowledge graph that has changed since it trained, and degradationReason is then brain_stale. The other two reasons, no_brain and cold_start, only ever appear with path: "hybrid".
The contradictions entries here are not the Contradiction object. GET /v1/contradictions returns the named schema with id, a, b, status and detectedAt. This route returns the retrieval-time shape instead: kind, subkind, nodeId as node_id, marker, before, after, tension, in_active_subgraph and snippet, plus from_concept and to_concept on a reversal. The schema types the field as a free-form object for exactly this reason. Treat it as advisory and read the contradictions resource when you need the stable object.
Streaming changes the content type, not the content. With stream: true the same result arrives as text/event-stream in event order sources, contradictions, cognition, done.
expand accepts one relation in v1. sources.content replaces the 280-character snippet preview with the full stored chunk text. Any other value is 422 invalid_expand.

Authorizations

X-Exo-API-Key

string

header

required

An Exo API key (exo_...) sent as the X-Exo-API-Key header.

Query Parameters

expand

string | null

Comma-separated relations to expand beyond the lean default. Valid values: sources.content (the full stored text of each source, beyond the 280-character snippet).

Body

application/json

A context-retrieval request. Field names accept camelCase or snake_case.

query

string

required

Required string length: 1 - 10000

expand

Comma-separated relations to expand beyond the lean default. Valid values: sources.content (the full stored text of each source, beyond the 280-character snippet).

includeContradictions

boolean

default:true

scope

enum<string>

default:user

Available options:

user,

org

stream

boolean

default:false

topK

integer

default:8

Required range: 1 <= x <= 50

Response

Ranked sources plus the contradiction, cognition and usage blocks.

Retrieved context for a query.

path names the engine that served the call ("brain" when the org's trained ExoBrain answered, "hybrid" on the vector plus keyword fallback). degraded is true on the fallback path, and also on the brain path when the brain is serving a knowledge graph that has changed since it trained; degradationReason says why ("no_brain", "brain_stale" or "cold_start"). cognition is present only on the brain path.

degraded

boolean

required

latencyMs

integer

required

path

enum<string>

required

Available options:

brain,

hybrid

query

string

required

sources

Sources · object[]

required

usage

RetrieveUsage · object

required

Additive per-call usage counters (spec D13).

MCP / exo-cli / plugin / dashboard read only sources, contradictions and cognition, so this extra object never breaks an existing consumer.

readUnits: number of sources returned (the billable read unit).
embedTokens: DOCUMENTED ESTIMATE of Voyage embed tokens for the query at ~3.5 chars/token (the same tokenizer-free proxy the Voyage client uses internally). The embedder's embed() return does not surface usage.total_tokens, so this is an estimate, not the metered figure.
brainInference: True when the ExoBrain served the query, False on the hybrid pgvector+BM25 fallback path.

Show child attributes

cognition

Cognition · object | null

How Exo reasoned about a query, not just what it retrieved.

Present on a retrieval only when the org's trained ExoBrain served the call; it is null on the hybrid vector plus keyword fallback, which has no reasoning state to report. focalNodeIds are the knowledge-graph nodes the brain settled on as the centre of the answer, confidence is how strongly it settled, and useSystem2 is true when the brain judged the question hard enough to warrant slow deliberate reasoning instead of a fast associative lookup. driftRate reports how far the activated region has moved from what the brain trained on, which is the early warning that the graph has outgrown the brain.

The block is versioned additively: a future reasoning tier may report extra fields, so treat unknown keys as forward compatible rather than an error.

Show child attributes

contradictions

Contradictions · object[]

degradationReason

string | null

traceId

string

default:""

Retrieval

⌘I

​Authorization

​Headers

​Success responses

​Errors

​Notes

Authorizations

Query Parameters

Body

Response

Authorization

Headers

Success responses

Errors

Notes