retrieve

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.
`sources` · `exclude_sources`	`null`	Restrict the corpus read to given publishers (`["HAS"]`). The ids are those of `GET /v2/sources`, case-insensitive. An unknown source is refused with a 400 — never served as an empty answer.
`source_weights`	`{}`	A per-publisher score multiplier (`{"recomedicales": 1.2}`). It removes nothing: it moves things in the ranking. A weight ≠ 1 triggers over-fetching on the vector searches — without it, weighting could only reorder what cosine already let through.
`logic_answers`	`[]`	What the clinician answered on the logic units of the previous turn (see below). Without them a score is proposed; with them it is computed.
`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`.
`elicitations`	The logic units retrieved — a score, a tree — and what they need in order to be run. See below.
`source_scope`	The publisher restriction actually applied, in canonical ids. `null` = the whole corpus. A short answer under a restriction then reads as such, rather than as a gap in the corpus.
`deliberation`	Present only when `deliberate` was requested.

Logic units: scores and trees

Not every knowledge unit is a flat rule. Two shapes carry an executable logic:

a score — weighted questions, a total, interpretation bands;
a tree — nodes, branches, terminal courses of action.

The server never lets the model compute them. It enumerates bounded choices (elicitations[].steps[]), the client displays them, the clinician answers, and the next turn passes those answers back in logic_answers: the computation is then done by a deterministic engine, and it is its result (computed) that enters the synthesis context.

{
  "query": "embolic risk in this patient with AF",
  "logic_answers": [
    {
      "mku_key": "score:cha2ds2vasc",
      "checked": ["Âge ≥ 75 ans", "Hypertension"]
    }
  ]
}

A unit is addressed by mku_id (the citable identity) or by mku_key (the readable key): the latter survives a re-extraction, which matters when a form stays open across turns. Depending on the score’s shape, you answer with answers (question → option), checked (the ticked labels) or level (a band of an ordinal scale); a tree answers with answers, node to chosen branch. Each step carries a kind: question, items, niveau (a band to pick) or branchement (a tree branch). A client that ignores elicitations gets the same written answer as before — the unit is then cited without being run.

Only one unit is expanded

One answer can retrieve several logic units. A clinician fills in only one: the one they came for. So only one carries its steps — expanded: true — the best-ranked one, or the one the question names if it names any. The others stay in elicitations with expanded: false and steps: []. They keep everything else: identity, title, total_max, bands, graph. Enough to offer them without displaying them, and to open one client-side without a second call. A unit the request carried logic_answers for is always expanded, whatever its rank: an open form does not close because another score ranks higher.

A score carries its interpretation — `bands`

bands gives a score’s interpretation bands: what a total means, as the source publishes it next to the scale. The client can therefore show a conclusion as soon as the clinician ticks a box, with no round trip.

"bands": [
  { "rang": 0, "quand": [{ "op": ">", "valeur": 4 }], "pur_total": true,
    "condition": "score > 4", "libelle": "High bleeding risk" },
  { "rang": 1, "quand": [{ "op": ">", "valeur": 0 }], "pur_total": true,
    "condition": "score 1-4", "libelle": "Intermediate bleeding risk" },
  { "rang": 2, "quand": [], "pur_total": true,
    "condition": "otherwise", "libelle": "Low bleeding risk" }
]

Order is the meaning. These bands are an if / else if chain: each one is bounded by those before it. Evaluate them by ascending rang, first match wins, and stop there. Reading them as independent intervals produces gaps and overlaps — measured on 43 scores out of 85.And a pur_total: false band depends on something other than the total: the engine refuses to conclude on it. Show its condition, never a conclusion.

computed.outcome remains the only binding conclusion — it comes from the engine. bands is for displaying the scale and situating a total, not for deciding.

A tree carries its graph — `graph`

steps only contains nodes that require a decision. Pass-through nodes and terminal actions are not steps — yet the engine walks the former on its own and concludes on the latter. graph returns the whole tree and removes the asymmetry: what the engine walks, the client can see.

Field	What it is
`graph.nodes[]`	Every node: `id` (the navigation key), `label`, `forme`.
`graph.edges[]`	Every edge: `de`, `vers`, `condition`, `optionnel`.
`graph.entries[]`	Entry nodes. More than one means the start is itself a choice.
`graph.outcomes[]`	Terminal nodes: the tree’s conclusions.
`graph.cyclique`	A structural fact of the source (a titration loops back to its assessment node), not a defect.

On options, to carries the id of the destination node; leads_to carries its label. Navigate by to: two nodes can share a label, and a pass-through node appears in no steps[].key. computed.path_ids gives the walked path as ids, computed.path the same nodes as labels — one for one.

Computing without searching again

For the intermediate turns of an open form — ticking a box, picking a branch — use /v2/logic/compute rather than calling /v2/retrieve again. It is faster, and above all deterministic: the unit is designated by its key, not re-ranked.

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
400	`UNKNOWN_SOURCE`	A requested source does not exist. The body carries `known_sources`.
400	`EMPTY_SOURCE_SCOPE`	The restriction can return nothing (everything included is also excluded).
503	`GRAPH_UNAVAILABLE`	The graph is unreachable.
503	`RETRIEVAL_UNAVAILABLE`	Embeddings are unreachable.
502	`ANSWER_UNAVAILABLE`	Synthesis failed.

Get started

Capabilities

Reference

Minimal request

The fields that matter

What comes back

Logic units: scores and trees

Only one unit is expanded

A score carries its interpretation — `bands`

A tree carries its graph — `graph`

Computing without searching again

Three formats, one answer

Errors

​Minimal request

​The fields that matter

​What comes back

​Logic units: scores and trees

​Only one unit is expanded

​A score carries its interpretation — bands

​A tree carries its graph — graph

​Computing without searching again

​Three formats, one answer

​Errors

Minimal request

The fields that matter

What comes back

Logic units: scores and trees

Only one unit is expanded

A score carries its interpretation — `bands`

A tree carries its graph — `graph`

Computing without searching again

Three formats, one answer

Errors