# Clinical API

Part of the HebrewCore documentation. Web: https://hc.itsbaba.com/docs#medical · Whole docs: https://hc.itsbaba.com/docs.md · Index: https://hc.itsbaba.com/llms.txt

The `/v1/medical` endpoints serve health products that work in English and speak to people in Hebrew: patient portals, care-team tools, clinical assistants and record viewers. Records, search and your own model stay in English. HebrewCore turns a Hebrew question into an English query, then turns the English answer into Hebrew as it streams, one verified sentence at a time.

Real patient data goes only from your server, with an API key. The [playground](https://hc.itsbaba.com/docs#playground) runs in the browser, so use synthetic data only there.

```text
Hebrew question ──► POST /v1/medical/query ──► English query ──► your record search + model
                                                                          │ English answer, streamed
Hebrew answer ◄── verified sentences ◄── WebSocket /v1/medical/stream ◄──┘
```

Every sentence goes through the same steps before it is returned:

| Step | What happens |
| --- | --- |
| Protect | Drug names (US generics and brands, plus unknown drugs by their name stem), doses and concentrations, lab values, units, ICD-10 codes, clinical abbreviations, identifiers and every number are replaced with placeholders the model cannot change. Your `protected_terms`, `redact_terms` and [account terms](https://hc.itsbaba.com/docs#terms) come first. |
| Translate | The model translates the words around the placeholders into Israeli medical Hebrew for a clinician or a patient. |
| Check | Every placeholder must appear exactly once, every number in the English must appear in the Hebrew and no number may be invented, negations and left/right must survive, and the length must be plausible. |
| Review | An independent model checks every sentence for meaning changes: certainty, timing, dosing wording, who is being described, omissions and additions. |
| Retry or fall back | A rejected sentence is retried once with a stronger model, told what was wrong. If it still fails, the English sentence is returned with `status: "fallback"`. Unverified Hebrew is never returned. |
| Restore | The original values are put back, wrapped in Unicode isolates so `5 mg` never renders as `mg 5`. Dates are rewritten unambiguously (`03/04/2026` → `4 במרץ 2026`). |

## Segment Status

| Status | Meaning |
| --- | --- |
| `ok` | Translated and verified on the first attempt. |
| `retried` | The first attempt was rejected; the retry passed every check. |
| `fallback` | No translation passed. `text` is the English source; `issues` says why. Show it as English, or ask the user to rephrase. |
| `passthrough` | Structure or values only (a blank line, a rule, a date on its own). No model was needed. |