Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: HebrewCore Account Terms API
version: 1.0.0
description: 'HebrewCore by baba Hebrew is the language layer for products that work in Hebrew. One REST API for:
- **Translation** between Hebrew, English, Russian and more, with RTL/LTR metadata on both sides.
- **Protected translation** that keeps prices, quantities, dates, codes, product names and interface variables exactly as written, and verifies every sentence.
- **Account terms**: a list of names (drugs, products, brands) kept exactly in every protected translation.
- **Render-ready display** of mixed Hebrew and English lines, and **language detection** for code-switched input.
- **Transliteration** and **nikud** (vowel points) for display and speech.
- The **Clinical API** for health products: verified clinical translation, streaming, record-search queries and verification.
## Quick start
1. Sign up free, save a card (no charge on the Free plan), and create an API key.
2. Send it as a bearer token.
3. Call an endpoint:
```bash
curl https://hc.itsbaba.com/v1/translate \
-H "Authorization: Bearer hc_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d ''{ "text": "Welcome to your account", "target_lang": "he" }''
```
## Authentication
Every endpoint except `GET /v1/health` needs `Authorization: Bearer `. Keys are `hc_live_…` (production) or `hc_test_…` (sandbox), are shown once, and are stored only as a hash. Use them from your server only. TLS 1.2 or newer.
## Limits
| Limit | Default |
|---|---|
| Requests | 600 per minute per account, across all its keys, on every plan. `429 rate_limited` with `Retry-After`. |
| Characters | Monthly characters set by your plan. Protected balanced counts 2×, nikud and the Clinical API 3×, smartest up to 5×; direction, detection and wrap are free. `429 quota_exceeded`. |
| Request size | 20,000 characters (5,000 for transliterate, 10,000 for nikud). |
Responses carry `X-Usage-Chars-Used`, `X-Usage-Chars-Limit`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-Content-Stored` and `Server-Timing`. Errors use one envelope: `{ "error": { "type", "message", "code" } }`.
## Docs for people and for AI
- Documentation with guides
- docs.md: the whole documentation as Markdown
- llms.txt and llms-full.txt: an index and the complete docs plus this reference, for language models
- openapi.json: this spec
- API catalog (RFC 9727) and apis.json: machine-readable discovery'
contact:
name: baba HebrewCore (baba Hebrew)
url: https://www.itsbaba.com/hebrewcore
email: admin@itsbaba.com
servers:
- url: https://hc.itsbaba.com
description: Production
tags:
- name: Account Terms
description: 'A persistent list of names that must never change in translation: drug names, product names, brand names. Applied to every protected translation by placeholder masking.'
paths:
/v1/terms:
get:
operationId: listTerms
tags:
- Account Terms
summary: List the account's protected terms
description: 'Every account term, sorted by term, with the account limit. Account terms are names that must never change in translation (drug, product and brand names). Every protected translation on the account keeps them exactly as written, or uses `translations[target]` when it is set: /v1/translate, /v1/translate/batch and the Clinical API. They are applied by placeholder masking, so the model never sees them and cannot alter them, and they switch protection on automatically for Hebrew, English and Russian pairs.
**Quota.** Does not consume the character quota.'
security:
- ApiKeyAuth: []
responses:
'200':
description: Terms
headers:
X-RateLimit-Limit:
description: 'Requests allowed per minute for this key: 60 on Standard, 600 on Scale.'
schema:
type: integer
example: 60
X-RateLimit-Remaining:
description: Requests left in the current minute.
schema:
type: integer
example: 59
Server-Timing:
description: 'Time spent on our side, in milliseconds: `auth` (with the key lookup source), `ratelimit` and `total`. Compare `total` with your measured latency to separate network time.'
schema:
type: string
example: auth;desc="memory";dur=0, ratelimit;dur=0, total;dur=842
content:
application/json:
schema:
$ref: '#/components/schemas/AccountTermList'
examples:
list:
summary: Two terms
value:
terms:
- id: 3f2c1a9e-8b7d-4c6e-9f10-2a3b4c5d6e7f
term: Optalgin
translations:
he: אופטלגין
ru: Оптальгин
note: brand name
created_at: '2026-01-15T09:30:00.000Z'
- id: 7a1d2e3f-4b5c-4d6e-8f90-1a2b3c4d5e6f
term: Wireless Earbuds Pro
translations: {}
note: null
created_at: '2026-01-15T09:30:00.000Z'
limit: 2000
'400':
description: Invalid body, a term that is empty or too long, an unsupported language in `translations`, or the account limit reached.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_request:
summary: Empty term
value:
error:
type: invalid_request
message: Each term needs a non-empty "term".
code: invalid_request
unsupported_language:
summary: Unsupported rendering language
value:
error:
type: invalid_request
message: 'translations: unsupported language "fr". Use he, en or ru.'
code: invalid_request
terms_limit:
summary: Account limit
value:
error:
type: invalid_request
message: An account may hold at most 2000 terms.
code: terms_limit
'401':
description: Missing, malformed, invalid or revoked API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missing_key:
summary: No API key
value:
error:
type: unauthorized
message: 'Missing or malformed API key. Use header: Authorization: Bearer hc_live_…'
code: unauthorized
revoked_key:
summary: Invalid or revoked key
value:
error:
type: unauthorized
message: Invalid or revoked API key.
code: unauthorized
'402':
description: A new self-serve account must save a card in the console before it can use the API. Adding a card is free.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
payment_method_required:
summary: No card saved yet
value:
error:
type: payment_required
message: 'Add a card in the console to start using the API: https://hc.itsbaba.com/dashboard/plans'
code: payment_method_required
'403':
description: The connection used TLS older than 1.2.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
tls_version:
summary: TLS older than 1.2
value:
error:
type: forbidden
message: TLS 1.2 or newer is required.
code: tls_version
'429':
description: Too many requests this minute. Retry after a short wait.
headers:
X-RateLimit-Limit:
description: 'Requests allowed per minute for this key: 60 on Standard, 600 on Scale.'
schema:
type: integer
example: 60
X-RateLimit-Remaining:
description: Requests left in the current minute.
schema:
type: integer
example: 59
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
rate_limited:
summary: Per-minute rate limit
value:
error:
type: rate_limited
message: Rate limit of 600/min exceeded. Slow down and retry.
code: rate_limited
'500':
description: Unexpected server error. Safe to retry.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
internal:
summary: Unexpected error
value:
error:
type: internal
message: Internal error.
code: internal
post:
operationId: upsertTerms
tags:
- Account Terms
summary: Add or update protected terms (upsert by exact term)
description: 'Add terms, or update existing ones. Terms are matched by exact text after trimming and collapsing spaces: sending an existing term replaces its `translations` and `note`. When one request names the same term twice, the later entry wins. Returns the stored terms.
`translations` accepts `he`, `en` and `ru`. Leave it out to keep the term exactly as written in every language.
**Limits.** 2,000 terms per account. A term or rendering is up to 200 characters and may not contain ⟦ or ⟧; a note is up to 500 characters. Changes reach new requests within 30 seconds. Idempotent: repeating a request leaves the same list.'
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccountTermsUpsert'
examples:
products:
summary: Product and brand names kept as written
value:
terms:
- term: Wireless Earbuds Pro
- term: Galaxy S25
note: product line
drugs:
summary: Drug names with fixed renderings
value:
terms:
- term: Optalgin
translations:
he: אופטלגין
ru: Оптальгин
note: brand name
- term: Eliquis
translations:
he: אליקוויס
responses:
'200':
description: Stored terms
headers:
X-RateLimit-Limit:
description: 'Requests allowed per minute for this key: 60 on Standard, 600 on Scale.'
schema:
type: integer
example: 60
X-RateLimit-Remaining:
description: Requests left in the current minute.
schema:
type: integer
example: 59
Server-Timing:
description: 'Time spent on our side, in milliseconds: `auth` (with the key lookup source), `ratelimit` and `total`. Compare `total` with your measured latency to separate network time.'
schema:
type: string
example: auth;desc="memory";dur=0, ratelimit;dur=0, total;dur=842
content:
application/json:
schema:
$ref: '#/components/schemas/AccountTermsUpserted'
examples:
products:
summary: Stored
value:
terms:
- id: 9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
term: Galaxy S25
translations: {}
note: product line
created_at: '2026-01-15T09:30:00.000Z'
- id: 7a1d2e3f-4b5c-4d6e-8f90-1a2b3c4d5e6f
term: Wireless Earbuds Pro
translations: {}
note: null
created_at: '2026-01-15T09:30:00.000Z'
count: 2
'400':
description: Invalid body, a term that is empty or too long, an unsupported language in `translations`, or the account limit reached.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_request:
summary: Empty term
value:
error:
type: invalid_request
message: Each term needs a non-empty "term".
code: invalid_request
unsupported_language:
summary: Unsupported rendering language
value:
error:
type: invalid_request
message: 'translations: unsupported language "fr". Use he, en or ru.'
code: invalid_request
terms_limit:
summary: Account limit
value:
error:
type: invalid_request
message: An account may hold at most 2000 terms.
code: terms_limit
'401':
description: Missing, malformed, invalid or revoked API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missing_key:
summary: No API key
value:
error:
type: unauthorized
message: 'Missing or malformed API key. Use header: Authorization: Bearer hc_live_…'
code: unauthorized
revoked_key:
summary: Invalid or revoked key
value:
error:
type: unauthorized
message: Invalid or revoked API key.
code: unauthorized
'402':
description: A new self-serve account must save a card in the console before it can use the API. Adding a card is free.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
payment_method_required:
summary: No card saved yet
value:
error:
type: payment_required
message: 'Add a card in the console to start using the API: https://hc.itsbaba.com/dashboard/plans'
code: payment_method_required
'403':
description: The connection used TLS older than 1.2.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
tls_version:
summary: TLS older than 1.2
value:
error:
type: forbidden
message: TLS 1.2 or newer is required.
code: tls_version
'429':
description: Too many requests this minute. Retry after a short wait.
headers:
X-RateLimit-Limit:
description: 'Requests allowed per minute for this key: 60 on Standard, 600 on Scale.'
schema:
type: integer
example: 60
X-RateLimit-Remaining:
description: Requests left in the current minute.
schema:
type: integer
example: 59
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
rate_limited:
summary: Per-minute rate limit
value:
error:
type: rate_limited
message: Rate limit of 600/min exceeded. Slow down and retry.
code: rate_limited
'500':
description: Unexpected server error. Safe to retry.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
internal:
summary: Unexpected error
value:
error:
type: internal
message: Internal error.
code: internal
/v1/terms/{id}:
delete:
operationId: deleteTerm
tags:
- Account Terms
summary: Delete one protected term
description: Remove one term by id. New requests stop using it within 30 seconds.
security:
- ApiKeyAuth: []
parameters:
- schema:
type: string
example: 3f2c1a9e-8b7d-4c6e-9f10-2a3b4c5d6e7f
required: true
name: id
in: path
responses:
'200':
description: Deleted
headers:
X-RateLimit-Limit:
description: 'Requests allowed per minute for this key: 60 on Standard, 600 on Scale.'
schema:
type: integer
example: 60
X-RateLimit-Remaining:
description: Requests left in the current minute.
schema:
type: integer
example: 59
Server-Timing:
description: 'Time spent on our side, in milliseconds: `auth` (with the key lookup source), `ratelimit` and `total`. Compare `total` with your measured latency to separate network time.'
schema:
type: string
example: auth;desc="memory";dur=0, ratelimit;dur=0, total;dur=842
content:
application/json:
schema:
type: object
properties:
deleted:
type: boolean
required:
- deleted
examples:
deleted:
summary: Deleted
value:
deleted: true
'400':
description: Invalid body, a term that is empty or too long, an unsupported language in `translations`, or the account limit reached.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_request:
summary: Empty term
value:
error:
type: invalid_request
message: Each term needs a non-empty "term".
code: invalid_request
unsupported_language:
summary: Unsupported rendering language
value:
error:
type: invalid_request
message: 'translations: unsupported language "fr". Use he, en or ru.'
code: invalid_request
terms_limit:
summary: Account limit
value:
error:
type: invalid_request
message: An account may hold at most 2000 terms.
code: terms_limit
'401':
description: Missing, malformed, invalid or revoked API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missing_key:
summary: No API key
value:
error:
type: unauthorized
message: 'Missing or malformed API key. Use header: Authorization: Bearer hc_live_…'
code: unauthorized
revoked_key:
summary: Invalid or revoked key
value:
error:
type: unauthorized
message: Invalid or revoked API key.
code: unauthorized
'402':
description: A new self-serve account must save a card in the console before it can use the API. Adding a card is free.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
payment_method_required:
summary: No card saved yet
value:
error:
type: payment_required
message: 'Add a card in the console to start using the API: https://hc.itsbaba.com/dashboard/plans'
code: payment_method_required
'403':
description: The connection used TLS older than 1.2.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
tls_version:
summary: TLS older than 1.2
value:
error:
type: forbidden
message: TLS 1.2 or newer is required.
code: tls_version
'404':
description: No term with this id on the account.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
not_found:
summary: Unknown id
value:
error:
type: not_found
message: No such term.
code: not_found
'429':
description: Too many requests this minute. Retry after a short wait.
headers:
X-RateLimit-Limit:
description: 'Requests allowed per minute for this key: 60 on Standard, 600 on Scale.'
schema:
type: integer
example: 60
X-RateLimit-Remaining:
description: Requests left in the current minute.
schema:
type: integer
example: 59
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
rate_limited:
summary: Per-minute rate limit
value:
error:
type: rate_limited
message: Rate limit of 600/min exceeded. Slow down and retry.
code: rate_limited
'500':
description: Unexpected server error. Safe to retry.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
internal:
summary: Unexpected error
value:
error:
type: internal
message: Internal error.
code: internal
components:
schemas:
AccountTermsUpserted:
type: object
properties:
terms:
type: array
items:
$ref: '#/components/schemas/AccountTerm'
count:
type: integer
required:
- terms
- count
AccountTerm:
type: object
properties:
id:
type: string
example: 3f2c1a9e-8b7d-4c6e-9f10-2a3b4c5d6e7f
term:
type: string
example: Acamol
description: Kept exactly as written in every protected translation.
translations:
type: object
properties:
he:
type: string
en:
type: string
ru:
type: string
example:
he: אקמול
description: Optional required rendering per target language. When set for the target, it replaces the term; otherwise the term is kept verbatim.
note:
type:
- string
- 'null'
example: paracetamol 500 mg brand
description: Your own note, up to 500 characters.
created_at:
type: string
example: '2026-01-15T09:30:00.000Z'
description: ISO 8601 timestamp.
required:
- id
- term
- translations
- note
- created_at
Error:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: 'Stable error class: `invalid_request`, `unauthorized`, `payment_required`, `forbidden`, `not_found`, `rate_limited`, `quota_exceeded`, `internal`, `bad_gateway` or `service_unavailable`. Branch on this.'
example: unauthorized
message:
type: string
description: Human-readable explanation. Wording may change; do not parse it.
example: Invalid or revoked API key.
code:
type: string
description: Finer-grained reason. Equals `type` unless a more specific code applies, e.g. `unsupported_language`, `same_language`, `invalid_message_format`, `message_too_complex`, `payment_method_required`, `server_only`, `upstream_error`, `not_configured`, `terms_limit`, `tls_version`.
example: unauthorized
required:
- type
- message
- code
description: Error details.
required:
- error
description: Every error response uses this envelope.
AccountTermsUpsert:
type: object
properties:
terms:
type: array
items:
type: object
properties:
term:
type: string
minLength: 1
maxLength: 200
example: Optalgin
translations:
type: object
properties:
he:
type: string
minLength: 1
maxLength: 200
en:
type: string
minLength: 1
maxLength: 200
ru:
type: string
minLength: 1
maxLength: 200
additionalProperties: false
example:
he: אופטלגין
ru: Оптальгин
note:
type:
- string
- 'null'
maxLength: 500
required:
- term
minItems: 1
maxItems: 2000
required:
- terms
AccountTermList:
type: object
properties:
terms:
type: array
items:
$ref: '#/components/schemas/AccountTerm'
limit:
type: integer
example: 2000
required:
- terms
- limit
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
description: 'HebrewCore API key, sent as `Authorization: Bearer <key>`: `hc_live_…` for production, `hc_test_…` for the sandbox. Create keys in the dashboard.'
externalDocs:
description: Documentation (also as Markdown at /docs.md and /llms-full.txt)
url: https://hc.itsbaba.com/docs