---
title: "Translate clinical English into verified Hebrew"
method: POST
path: "/v1/medical/translate"
tags: ["Medical"]
---

# Translate clinical English into verified Hebrew

`POST /v1/medical/translate`

## Request

- Base URL: `https://hc.itsbaba.com`
- URL: `https://hc.itsbaba.com/v1/medical/translate`
- Auth: HTTP bearer

Translate a complete English clinical text into Israeli medical Hebrew for a clinician or a patient. Drug names, doses, lab values, units, ICD-10 codes, clinical abbreviations, identifiers and every number are replaced with placeholders the model cannot change, and restored afterwards. Sentences are translated in parallel and returned in order.

Every sentence is checked (placeholders, numbers, negation, laterality, length) and reviewed by an independent model for meaning changes. A rejected sentence is retried once with a stronger model; if it still fails, the English is returned with `status: "fallback"`. Unverified Hebrew is never returned. Account terms apply, with their Hebrew rendering when one is set.

**Access.** Every key, on every plan. Call it from a server (a browser `Origin` header is refused). Nothing is stored; responses carry `Cache-Control: no-store`.

**Quota.** Consumes the monthly character quota: the length of `text`. Refunded when the provider fails for every sentence.

**Limits.** `text` up to 20,000 characters.

## Request body

- MedicalTranslateRequest
  - `audience` 'clinician' | 'patient': Who reads the Hebrew. `clinician` (default) keeps shorthand such as BID and PO; `patient` writes dosing shorthand (BID, PRN) as plain words.
  - `reader_gender` 'male' | 'female': Gender of the reader, the person the text calls "you". Omit when unknown.
  - `patient_gender` 'male' | 'female': Gender of the patient in third-person references. Inferred from he/she when omitted.
  - `protected_terms` string[]: Kept verbatim. Pass the patient's medication and problem lists from the record. Up to 500, each up to 200 characters. Added to the account terms list for this request.
  - `redact_terms` string[]: Kept verbatim and never shown to the model (patient and staff names). Up to 200.
  - `glossary` object: English term → required Hebrew rendering. Up to 500 entries.
  - `date_order` 'MDY' | 'DMY': How to read ambiguous numeric dates in the source. US records are MDY.
  - `date_style` 'hebrew' | 'iso' | 'keep': `hebrew` writes "4 במרץ 2026"; `iso` writes 2026-03-04; `keep` leaves unambiguous dates as written (an ambiguous one is still rewritten). A two-digit year is kept as written.
  - `bidi` 'isolate' | 'none': `isolate` wraps English values in Unicode isolates so "5 mg" never renders as "mg 5". `none` returns plain text.
  - `text` string, required: English text, 1 to 20,000 characters. Markdown lists, headings and tables keep their structure. Counts toward the monthly character quota.

## Response `200`

Translation

- MedicalTranslateResponse
  - `id` string, required: Request identifier.
  - `text` string, required: The whole Hebrew document: every segment joined with its prefix and suffix.
  - `segments` MedicalSegment[], required: One entry per sentence, in order.
    - `index` integer, required: Position of the sentence, from 0.
    - `prefix` string, required: Markdown structure emitted before the text (list marker, heading).
    - `suffix` string, required: Whitespace or structure after the text. Join `prefix + text + suffix` for every segment to rebuild the document.
    - `source` string, required: The English sentence.
    - `text` string, required: Verified Hebrew, or the English source when status is `fallback`.
    - `status` 'ok' | 'retried' | 'fallback' | 'passthrough', required: `ok`: verified first time. `retried`: passed after one retry with a stronger model. `fallback`: no translation passed, `text` is the English. `passthrough`: structure or values only, no model needed.
    - `issues` MedicalIssue[], required: Why a sentence was retried or fell back. Empty for `ok`.
      - `code` string, required: Check that failed: `term_missing`, `date_missing`, `number_added`, `digits_added`, `negation_lost`, `laterality_lost`, `laterality_swapped`, `gender_mismatch`, `meaning`, `placeholder_missing`, `length_ratio`, `provider_error` and others.
      - `severity` 'error' | 'warning', required: `error` blocks the sentence; `warning` is informational.
      - `detail` string, required: Human-readable explanation.
    - `spans` MedicalSpan[], required: Protected values in this sentence. Redacted names and identifiers are left out.
      - `type` string, required: What was protected: `drug`, `dose`, `abbreviation`, `code`, `number`, `date`, `term`, `glossary`, `identifier`, `name` and others.
      - `value` string: The protected source value. Omitted for names and identifiers.
      - `render` string: How the value was written in the Hebrew, when it was rewritten (dates).
      - `ambiguous_date` boolean: True when a numeric date could be read two ways and `date_order` decided it.
  - `stats` MedicalStats, required
    - `segments` integer, required: Total sentences.
    - `ok` integer, required
    - `retried` integer, required
    - `fallback` integer, required: Sentences returned in English. Treat them as untranslated.
    - `passthrough` integer, required
  - `usage` object, required
    - `characters` integer, required: Characters charged.

## Other responses

- `400`: Invalid request: the body failed validation or a value is out of range.
- `401`: Missing, malformed, invalid or revoked API key.
- `402`: A new self-serve account must save a card in the console before it can use the API. Adding a card is free.
- `403`: The request came from a browser, or TLS is older than 1.2.
- `429`: Too many requests this minute (`rate_limited`), or the monthly character quota is used up (`quota_exceeded`). Retry `rate_limited` after a short wait; `quota_exceeded` lasts until the quota resets or the plan changes.
- `502`: The model provider failed for every sentence, so no Hebrew was produced. The characters are refunded. Safe to retry.
- `503`: Medical translation is not configured on this server.

---

[API](https://skmtc.dev/itsbaba/apis/hebrewcore-api.md) · [All operations](https://skmtc.dev/itsbaba/apis/hebrewcore-api/llms.txt) · [OpenAPI document](https://skmtc.dev/itsbaba/apis/hebrewcore-api/revisions/f54229695236?raw)