---
title: "Add or update protected terms (upsert by exact term)"
method: POST
path: "/v1/terms"
tags: ["Account Terms"]
---

# Add or update protected terms (upsert by exact term)

`POST /v1/terms`

## Request

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

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.

## Request body

- AccountTermsUpsert
  - `terms` object[], required
    - `term` string, required
    - `translations` object
      - `he` string
      - `en` string
      - `ru` string
    - `note` string, nullable

## Response `200`

Stored terms

- AccountTermsUpserted
  - `terms` AccountTerm[], required
    - `id` string, required
    - `term` string, required: Kept exactly as written in every protected translation.
    - `translations` object, required: Optional required rendering per target language. When set for the target, it replaces the term; otherwise the term is kept verbatim.
      - `he` string
      - `en` string
      - `ru` string
    - `note` string, nullable, required: Your own note, up to 500 characters.
    - `created_at` string, required: ISO 8601 timestamp.
  - `count` integer, required

## Other responses

- `400`: Invalid body, a term that is empty or too long, an unsupported language in `translations`, or the account limit reached.
- `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 connection used TLS older than 1.2.
- `429`: Too many requests this minute. Retry after a short wait.
- `500`: Unexpected server error. Safe to retry.

---

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