retrieve - Locus

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

query maker — classifies what the last message adds (new question, refinement, patient fact) and reformulates it;
two-path retrieval — semantic ‖ concepts + graph, in parallel;
context — the knowledge units retained, their decision tables, their documents;
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

{ "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`. 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`.
`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.