---
title: "Turn a Hebrew question into an English record query"
method: POST
path: "/v1/medical/query"
tags: ["Medical"]
---

# Turn a Hebrew question into an English record query

`POST /v1/medical/query`

## Request

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

Translate a Hebrew question into an English query for your record search and model. English terms, numbers and dates in the question are kept exactly (Hebrew day-first dates become ISO dates). Hebrew spellings of English drug names are mapped back to English, preferring the patient's own terms from `known_terms` and the account terms over the built-in lexicon.

**Quota.** Consumes the monthly character quota: the length of `text`. Refunded when the query cannot be verified (`502 unverified`) or the provider fails.

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

## Request body

- MedicalQueryRequest
  - `text` string, required: The Hebrew question, up to 2,000 characters.
  - `known_terms` string[]: English terms from the patient's record, used to map Hebrew spellings back. Up to 500. Account terms are added automatically.
  - `glossary` object: English term → Hebrew rendering, used to map the Hebrew back to English.

## Response `200`

English query

- MedicalQueryResponse
  - `query` string, required: English query for your record search.
  - `terms` object[], required: Hebrew spellings that were mapped back to English terms.
    - `hebrew` string, required
    - `english` string, required
    - `source` 'known_terms' | 'lexicon' | 'glossary', required: Where the mapping came from.
  - `usage` object, required
    - `characters` integer, required

## 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)