# Account Terms

Part of the HebrewCore documentation. Web: https://hc.itsbaba.com/docs#terms · Whole docs: https://hc.itsbaba.com/docs.md · Index: https://hc.itsbaba.com/llms.txt

Account terms are a persistent, per-account list of names that must never change in translation: drug names, product names, brand names. Add them once, in the dashboard or with the endpoints below, and every protected translation on the account keeps them exactly as written: `/v1/translate`, `/v1/translate/batch` and the [Clinical API](https://hc.itsbaba.com/docs#medical), for every key.

| Behavior | Detail |
| --- | --- |
| Kept exactly | Every term is kept exactly as written. When a term has a rendering for the target language in `translations` (for example `translations.he`), that exact rendering is used instead. |
| Placeholder masking | Terms are replaced with placeholders before the model runs and restored afterwards, so the model never sees them and cannot alter them. This is stronger than an instruction in a prompt. |
| Automatic protection | When the account has terms, protection switches on automatically for Hebrew, English and Russian pairs. You do not need `protect: true`. |
| Per-request fields | `protected_terms` and `glossary` still work and add to the account list. When both name the same term, the request's entry wins. |
| Limits | 2,000 terms per account. A term or rendering is up to 200 characters, a note up to 500. `translations` accepts `he`, `en` and `ru`. |
| Propagation | Changes apply to new requests within 30 seconds. |

## The Term Object

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Identifier, used to delete the term. |
| `term` | string | The name, exactly as it must appear. |
| `translations` | object | Optional required rendering per target language: `{ "he"?, "en"?, "ru"? }`. |
| `note` | string \| null | Your own note, for example why the term is protected. |
| `created_at` | string | ISO 8601 timestamp. |

## POST /v1/terms

`POST /v1/terms`

Add or update terms. The body is `{ "terms": [{ "term", "translations"?, "note"? }] }`. Terms are upserted by exact term text: sending an existing term replaces its `translations` and `note`. Returns the stored terms and their `count`.

```bash
curl https://hc.itsbaba.com/v1/terms \
  -H "Authorization: Bearer hc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "terms": [
      { "term": "Wireless Earbuds Pro" },
      { "term": "Optalgin", "translations": { "he": "אופטלגין", "ru": "Оптальгин" }, "note": "brand name" }
    ]
  }'
```

```json
{
  "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" }
  ],
  "count": 2
}
```

## GET /v1/terms

`GET /v1/terms`

List the account's terms, sorted by term, with the account `limit`.

```http
GET /v1/terms

{ "terms": [ { "id": "3f2c…", "term": "Optalgin", "translations": { "he": "אופטלגין" }, "note": "brand name", "created_at": "…" }, … ],
  "limit": 2000 }
```

## DELETE /v1/terms/{id}

`DELETE /v1/terms/{id}`

Delete one term. Returns `404 not_found` when the id does not belong to the account.

```http
DELETE /v1/terms/3f2c1a9e-8b7d-4c6e-9f10-2a3b4c5d6e7f

{ "deleted": true }
```

## Effect on a Translation

With the two terms above on the account, a plain request is protected automatically:

```http
POST /v1/translate
{ "text": "Take Optalgin with water. Wireless Earbuds Pro ships tomorrow.", "target_lang": "he" }

→ "יש ליטול אופטלגין עם מים. Wireless Earbuds Pro נשלח מחר."
```