Retrieval

What this family does

Retrieval is the flagship. You send a question and Exo answers from the organization’s trained ExoBrain when one is available, and from a hybrid vector plus keyword search over your stored content when it is not. Either way you get ranked sources with provenance, any contradictions it noticed, and a usage block you can reconcile against your own billing. What makes the response different from a vector store’s is the last three fields. cognition is the brain’s reasoning trace. path names the engine that served the call. degraded and degradationReason say plainly when you are on the fallback, instead of quietly returning worse results.

Routes

Method	Path	Scope	What it does
`POST`	`/v1/retrieve`	`read`	Retrieve context

Headers that apply here

Neither header is declared as an OpenAPI parameter, so neither appears in the generated schema tables.

X-Exo-Subject selects which subject the call acts for on the subject-aware routes above. Omit it to act as the key owner. See Subjects.

The shape of a call

Ask a question.

curl -X POST https://api.get-exo.com/v1/retrieve \
  -H "X-Exo-API-Key: $EXO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Where did we land on the pricing model?", "topK": 8}'

import httpx

response = httpx.post(
    "https://api.get-exo.com/v1/retrieve",
    headers={"X-Exo-API-Key": EXO_KEY},
    json={"query": "Where did we land on the pricing model?", "topK": 8},
)
result = response.json()
print(result["path"], result["degraded"])

const response = await fetch("https://api.get-exo.com/v1/retrieve", {
  method: "POST",
  headers: {
    "X-Exo-API-Key": process.env.EXO_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "Where did we land on the pricing model?", topK: 8 }),
});
const result = await response.json();

The response:

{
  "query": "Where did we land on the pricing model?",
  "sources": [
    {
      "chunkId": "chk_9d21f0",
      "nodeId": "ingest:4a1e88f0-9c2d-4f31-b7a0-5e6c1d820b93:7d3c9b1e04a2",
      "title": "Pricing working session",
      "snippet": "We agreed to drop the freemium tier and price on usage.",
      "score": 0.912431,
      "cosineInSeed": true
    }
  ],
  "contradictions": [],
  "cognition": {
    "confidence": 0.83,
    "driftRate": 0.02,
    "tier": "system1",
    "useSystem2": false,
    "focalNodeIds": ["ingest:4a1e88f0-9c2d-4f31-b7a0-5e6c1d820b93:7d3c9b1e04a2"]
  },
  "path": "brain",
  "degraded": false,
  "degradationReason": null,
  "latencyMs": 412,
  "traceId": "",
  "usage": { "readUnits": 8, "embedTokens": 12, "brainInference": true }
}

Traps

cognition is null whenever path is hybrid. The block is the brain’s reasoning state, and the fallback path has none. Branch on path, not on the presence of cognition. degraded is not the same as path: "hybrid". A brain that answers from a knowledge graph which has changed since it trained returns path: "brain", degraded: true and degradationReason: "brain_stale". The contradictions on a retrieval are not the Contradiction object. GET /v1/contradictions returns the stable named schema. POST /v1/retrieve returns a retrieval-time shape with different keys. See the endpoint page for the field list.

API reference

Base URL, authentication, and the conventions every route shares.

Errors

The problem envelope and the full code catalogue.

​What this family does

​Routes

​Headers that apply here

​The shape of a call

​Traps

​Related