Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: HebrewCore Hebrew 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: Hebrew
description: Nikud (vowel points) for display and speech, and removing them for search and normalization.
paths:
/v1/nikud:
post:
operationId: addNikud
tags:
- Hebrew
summary: Add nikud (vowel points)
description: 'Add full nikud to Hebrew text, for vocalized display, learning materials and text-to-speech, where unvocalized Hebrew is ambiguous. English terms and numbers are left untouched.
The result is checked: `verified: true` means removing the points gives back your text (only the vowel letters ו and י may differ, which does not change pronunciation). When `verified` is false, `nikud` is your text unchanged; send it to speech unvocalized or retry.
**Quota.** Consumes the monthly character quota: the length of `text`.
**Limits.** `text` up to 10,000 characters.'
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NikudRequest'
examples:
speech:
summary: Text for speech
value:
text: שלום עולם
mixed:
summary: Hebrew with an English term and a number
value:
text: ההזמנה שלך ל-Galaxy S25 תגיע בעוד 3 ימים
responses:
'200':
description: Vocalized text
headers:
X-Usage-Chars-Used:
description: Characters used this month by the account, including this request.
schema:
type: integer
example: 1523
X-Usage-Chars-Limit:
description: Monthly character quota of the account.
schema:
type: integer
example: 100000
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
X-Content-Stored:
description: Whether the request text or the result was stored. `false` in the default no-retention mode.
schema:
type: boolean
example: false
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/NikudResponse'
examples:
speech:
summary: Verified
value:
text: שלום עולם
nikud: שָׁלוֹם עוֹלָם
verified: true
'400':
description: 'Invalid request: the body failed validation or a value is out of range.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_request:
summary: Invalid body
value:
error:
type: invalid_request
message: Required
code: invalid_request
unsupported_language:
summary: Protection outside Hebrew, English and Russian
value:
error:
type: invalid_request
message: Protected translation supports Hebrew (he), English (en) and Russian (ru).
code: unsupported_language
same_language:
summary: Source and target are the same
value:
error:
type: invalid_request
message: source_lang and target_lang must differ.
code: same_language
'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 (`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.
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
quota_exceeded:
summary: Monthly character quota
value:
error:
type: quota_exceeded
message: Monthly character quota of 100,000 reached. Upgrade at https://hc.itsbaba.com/dashboard/plans or wait for the next month.
code: quota_exceeded
'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
'502':
description: The model provider failed or returned an empty result. Nothing was charged. Safe to retry.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
upstream_error:
summary: Model provider error
value:
error:
type: bad_gateway
message: Translation provider error.
code: upstream_error
'503':
description: A model feature is temporarily unavailable.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
not_configured:
summary: Feature not configured
value:
error:
type: service_unavailable
message: Translation is not configured on this server.
code: not_configured
/v1/strip-nikud:
post:
operationId: stripNikud
tags:
- Hebrew
summary: Remove nikud
description: 'Remove nikud, dagesh and cantillation marks, keeping punctuation such as the maqaf. Use it for normalization, search keys and de-duplication, or to get display text back from vocalized speech text.
**Quota.** Deterministic, no model. Does not consume the character quota.
**Limits.** `text` up to 20,000 characters. Idempotent.'
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StripNikudRequest'
examples:
basic:
summary: Vocalized word
value:
text: שָׁלוֹם
responses:
'200':
description: Stripped text
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
X-Content-Stored:
description: Whether the request text or the result was stored. `false` in the default no-retention mode.
schema:
type: boolean
example: false
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/StripNikudResponse'
examples:
basic:
summary: Stripped
value:
text: שָׁלוֹם
stripped: שלום
'400':
description: 'Invalid request: the body failed validation or a value is out of range.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_request:
summary: Invalid body
value:
error:
type: invalid_request
message: Required
code: invalid_request
fields_or_text:
summary: Both or neither of text and fields
value:
error:
type: invalid_request
message: Provide either "text" or "fields".
code: invalid_request
'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
components:
schemas:
StripNikudResponse:
type: object
properties:
text:
type: string
description: The input.
example: שָׁלוֹם
stripped:
type: string
description: The text without nikud, dagesh or cantillation. Punctuation such as the maqaf is kept.
example: שלום
required:
- text
- stripped
NikudRequest:
type: object
properties:
text:
type: string
minLength: 1
maxLength: 10000
description: Hebrew text to vocalize, up to 10,000 characters. English terms and numbers pass through.
example: שלום עולם
required:
- text
NikudResponse:
type: object
properties:
text:
type: string
description: The input.
example: שלום עולם
nikud:
type: string
description: The vocalized text, or the input unchanged when `verified` is false.
example: שָׁלוֹם עוֹלָם
verified:
type: boolean
description: 'True when removing the points gives back exactly the input. When false, `nikud` is the input unchanged: send it to speech unvocalized or retry.'
example: true
required:
- text
- nikud
- verified
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.
StripNikudRequest:
type: object
properties:
text:
type: string
minLength: 1
maxLength: 20000
description: Hebrew text with nikud or cantillation, up to 20,000 characters.
example: שָׁלוֹם
required:
- text
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