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

# Retrieval

> One call that returns what a person knows, where their beliefs conflict, and how the answer was reached.

## 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`](/api-reference/retrieve/post-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](/api-reference/subjects).

## The shape of a call

Ask a question.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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}'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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"])
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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();
  ```
</CodeGroup>

The response:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "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.

## Related

<Columns cols={2}>
  <Card title="API reference" icon="book-open" href="/api-reference/overview">
    Base URL, authentication, and the conventions every route shares.
  </Card>

  <Card title="Errors" icon="circle-alert" href="/platform/errors">
    The problem envelope and the full code catalogue.
  </Card>
</Columns>