retrieve/stream

POST /v2/retrieve/stream takes the same request body as /v2/retrieve and returns the same payload — but as it happens, one JSON line per step that actually completed. This is what lets a UI show the real progress of a retrieval instead of a bar that invents it. An answer chains several heavy calls; a step that stays silent through them is indistinguishable from a step that is stuck.

Content-Type: application/x-ndjson

Each line is a complete JSON object, separated by \n. There is no reconnection to handle: fetch plus a stream reader is enough.

The lines

`step`	Emitted when
`query_maker`	The question is classified and reformulated.
`retrieval`	Both paths have returned their units.
`deliberation`	The second reading finished (full trace).
`answer`	The answer is written.
`drugs`	Drug cards are attached.
`done`	Terminal line. `payload` carries the full body, identical to `/v2/retrieve`.
`error`	Terminal line. `detail` says what gave out.

With deliberate: true, the reflexive loop also streams each of its rounds without waiting for its verdict:

`step`	What it carries
`deliberation_judge`	`index`, `saw` (what the judge had in front of it), `sufficient`, `checks`, `gaps`, the `probe` it decided on, `asked`.
`deliberation_probe`	`index`, `modality`, `query`, `seeds`, `rationale`, `gained`, `gained_ids`.

Without them, the step stays silent through three heavy calls and two retrievals.

A dependency failure can no longer raise an HTTP error here: the stream has already started, so it arrives as a terminal error line. The status is 200 from the first line — read the stream’s content, not the code.

Reading the stream

const resp = await fetch("https://core.locusmedical.fr/v2/retrieve/stream", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LOCUS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "antibioprophylaxie chirurgie colorectale" }),
});

const reader = resp.body!.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });

  // A complete line is one object. The last one may be partial: keep it.
  const lines = buffer.split("\n");
  buffer = lines.pop() ?? "";

  for (const line of lines) {
    if (!line.trim()) continue;
    const event = JSON.parse(line);
    if (event.step === "done") console.log(event.payload.answer);
    else if (event.step === "error") throw new Error(event.detail);
    else showProgress(event.step);
  }
}

import httpx, json

with httpx.stream(
    "POST",
    "https://core.locusmedical.fr/v2/retrieve/stream",
    headers={"Authorization": f"Bearer {LOCUS_API_KEY}"},
    json={"query": "antibioprophylaxie chirurgie colorectale"},
    timeout=180,
) as r:
    r.raise_for_status()
    for line in r.iter_lines():
        if not line:
            continue
        event = json.loads(line)
        if event["step"] == "done":
            print(event["payload"]["answer"])
        elif event["step"] == "error":
            raise RuntimeError(event["detail"])
        else:
            print("…", event["step"])

curl -N -X POST https://core.locusmedical.fr/v2/retrieve/stream \
  -H "Authorization: Bearer $LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "antibioprophylaxie chirurgie colorectale"}'

Buffer the tail. A network chunk does not land on a line boundary: naively splitting on \n without keeping the remainder cuts a JSON object in half and fails the parse at the mercy of the load.

Get started

Capabilities

Reference

retrieve/stream

The lines

Reading the stream

​The lines

​Reading the stream

The lines

Reading the stream