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

# retrieve

> POST /v2/retrieve — a question in, a cited answer out.

`POST /v2/retrieve` is the main path. In one call it runs:

1. **query maker** — classifies what the last message adds (new question,
   refinement, patient fact) and reformulates it;
2. **two-path retrieval** — semantic ‖ concepts + graph, in parallel;
3. **context** — the knowledge units retained, their decision tables, their
   documents;
4. **synthesis** — a Markdown answer, cited on those units and nothing else.

No judge, no safety sweep: both are asked for explicitly (see `deliberate`).

## Minimal request

```json theme={null}
{ "query": "antibioprophylaxie chirurgie colorectale" }
```

## The fields that matter

| Field                                        | Default | What it changes                                                                                                                                                                                         |
| -------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`                                      | —       | The question. The only required field.                                                                                                                                                                  |
| `patient_ehr`                                | `null`  | The patient record, free text. This is what gets matched against the rules' criteria.                                                                                                                   |
| `history`                                    | `[]`    | Previous turns. Used **only** by the query maker. Earlier answers are never handed back to the writer: they have no rule behind them and cannot be a source.                                            |
| `deliberate`                                 | `false` | A second reading: matches criteria against the record, fetches a missing definition, and asks a question only as a last resort. Outside the reference operating point — turning it on changes the cost. |
| `app_version` · `app_build` · `app_platform` | `null`  | Carried onto the trace. `app_build` is what tells two binaries of one released version apart: without it, a bug is not replayable.                                                                      |

The retrieval knobs (`concept_k`, `chunk_k`, `mku_k`, `mku_weight`, `table_k`,
`use_cross_refs`) are exposed, but their **defaults are the measured operating
point**. Changing them steps outside what the evaluations cover. Each is
detailed in the **API Reference** tab.

## What comes back

| Field                                 | What it is                                                                                                                                                                                                                 |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `answer`                              | The written answer, in **Markdown**.                                                                                                                                                                                       |
| `answer_short`                        | The course of action in one sentence, derived from `answer`'s title.                                                                                                                                                       |
| `trace_id`                            | The id of THIS answer — the key to send to [`/v2/feedback`](/en/capabilities/feedback). Empty when trace logging is off: do not offer feedback then.                                                                       |
| `core_version`                        | The version that produced the answer: `0.2.0+a1b2c3d (r:4f9e2b71)`. Show it in a bug report.                                                                                                                               |
| `mkus` · `tables` · `chunks` · `docs` | What the answer stands on: knowledge units, decision tables, excerpts, documents with deep links.                                                                                                                          |
| `drugs`                               | Drug cards for the cited rules. A **separate** lane from citable units: an SmPC section never enters the synthesis context. Its sections are **truncated** — get the full text from [`/v2/drugs`](/en/capabilities/drugs). |
| `deliberation`                        | Present only when `deliberate` was requested.                                                                                                                                                                              |

## Three formats, one answer

Negotiation happens on `Accept` rather than a `?format=` parameter: the client
states what it can read.

| `Accept`                     | Response                                        |
| ---------------------------- | ----------------------------------------------- |
| `application/json` (default) | The full payload.                               |
| `text/markdown`              | Answer and provenance as one Markdown document. |
| `text/html`                  | The same document, rendered as a readable page. |

In JSON, `answer`'s newlines are escaped as `\n`: read it with `jq -r '.answer'`.

## Errors

| Status | Code                    | Meaning                     |
| ------ | ----------------------- | --------------------------- |
| 503    | `GRAPH_UNAVAILABLE`     | The graph is unreachable.   |
| 503    | `RETRIEVAL_UNAVAILABLE` | Embeddings are unreachable. |
| 502    | `ANSWER_UNAVAILABLE`    | Synthesis failed.           |