itsbaba-com Reference API

openapi: 3.2.0
info:
  title: HebrewCore Reference 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: Reference
  description: Supported languages and the public health check.
paths:
  /v1/languages:
    get:
      operationId: listLanguages
      tags:
      - Reference
      summary: List supported languages
      description: Every language HebrewCore translates to and from, with its English and native name and its writing direction. Use `code` as `source_lang` or `target_lang`. Protected translation covers Hebrew, English and Russian. Does not consume the character quota.
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Languages
          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/LanguagesResponse'
              examples:
                list:
                  summary: Supported languages (truncated)
                  value:
                    languages:
                    - code: he
                      name: Hebrew
                      native: עברית
                      dir: rtl
                    - code: en
                      name: English
                      native: English
                      dir: ltr
                    - code: ar
                      name: Arabic
                      native: العربية
                      dir: rtl
                    - code: ru
                      name: Russian
                      native: Русский
                      dir: ltr
        '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
        '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/health:
    get:
      operationId: health
      tags:
      - Reference
      summary: Health check
      description: 'Liveness and database check. Public: no API key needed, no rate limit, no quota. Use it for uptime monitoring.'
      security: []
      responses:
        '200':
          description: Health
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              examples:
                ok:
                  summary: Healthy
                  value:
                    status: ok
                    db: ok
                    version: 1.0.0
components:
  schemas:
    LanguagesResponse:
      type: object
      properties:
        languages:
          type: array
          items:
            $ref: '#/components/schemas/Language'
          description: Every supported language.
      required:
      - languages
    Language:
      type: object
      properties:
        code:
          type: string
          description: BCP 47 code to pass as `source_lang` or `target_lang`.
          example: he
        name:
          type: string
          description: English name.
          example: Hebrew
        native:
          type: string
          description: Name in the language itself.
          example: עברית
        dir:
          type: string
          enum:
          - ltr
          - rtl
          description: Writing direction.
          example: rtl
      required:
      - code
      - name
      - native
      - dir
    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.
    HealthResponse:
      type: object
      properties:
        status:
          type: string
          description: '`ok` when the API is serving.'
          example: ok
        db:
          type: string
          description: '`ok`, or `error` when the database check failed.'
          example: ok
        version:
          type: string
          description: API version.
          example: 1.0.0
      required:
      - status
      - db
      - version
  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