Glossary endpoints

A glossary fixes how particular source terms are rendered. The engine treats its entries as mandatory and inflects them as the target grammar requires. Typical contents: product names, legal wording, button labels that must match the UI.

Endpoint overview

All of them require a key. Ids are 26-character ULIDs; anything else answers 404 with glossary_not_found.

Creating one

An English-to-Dutch glossary for an app's navigation terms:

curl https://api.langapi.xyz/v1/glossaries \
  -X POST \
  -H "Authorization: Bearer la_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "App navigation EN-NL",
        "source_lang": "EN",
        "target_lang": "NL",
        "entries": { "Dashboard": "Overzicht", "Sign out": "Afmelden", "Workspace": "Werkruimte" }
      }'

{
  "glossary_id": "01JAX1F7Q0M2ZK8WDN5R3TB9VE",
  "name": "App navigation EN-NL",
  "ready": true,
  "source_lang": "EN",
  "target_lang": "NL",
  "creation_time": "2026-09-07T08:15:42Z",
  "entry_count": 3
}

ready is always true. There is no asynchronous build phase; the id can be used in the next request.

Entry formats

entries is either a JSON object mapping source term to target term, as above, or a string with one tab-separated pair per line:

Dashboard	Overzicht
Sign out	Afmelden
Workspace	Werkruimte

Blank lines are skipped. A line without a tab is rejected with validation_error, and the message names the line number. Leading and trailing whitespace around each term is trimmed.

Validation rules

Because glossaries are stored against base codes, one EN to PT glossary serves both PT-PT and PT-BR requests.

Plan limits

Creating one beyond the limit answers 403 with glossary_limit_reached; the problem document includes max_glossaries. Delete a glossary or change plan to continue.

Using a glossary in a translation

curl https://api.langapi.xyz/v1/translate \
  -X POST \
  -H "Authorization: Bearer la_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "text": ["Open the Dashboard to switch Workspace."],
        "source_lang": "EN",
        "target_lang": "NL",
        "glossary_id": "01JAX1F7Q0M2ZK8WDN5R3TB9VE"
      }'

Two conditions apply, both checked before anything is charged:

• source_lang is mandatory whenever glossary_id is set. Without it the

request answers 400 with validation_error.

• The glossary's pair must equal the request's pair after reducing the target

to its base code. A mismatch is also validation_error, and the message spells out both pairs.

A glossary that does not exist, or belongs to another team, answers 404 with glossary_not_found.

Reading and exporting

curl https://api.langapi.xyz/v1/glossaries/01JAX1F7Q0M2ZK8WDN5R3TB9VE/entries \
  -H "Authorization: Bearer la_live_xxxxxxxx" > navigation-en-nl.tsv

The entries endpoint returns exactly the tab-separated format that POST accepts, so an export can be re-imported without conversion. The list endpoint returns { "glossaries": [ ... ] } with the same objects that the create call returns.

Deleting

curl -X DELETE https://api.langapi.xyz/v1/glossaries/01JAX1F7Q0M2ZK8WDN5R3TB9VE \
  -H "Authorization: Bearer la_live_xxxxxxxx"

204 and no body. There is no undo. Requests that still reference the id fail with glossary_not_found from then on.

Language pairs

curl https://api.langapi.xyz/v1/glossary-language-pairs \
  -H "Authorization: Bearer la_live_xxxxxxxx"

{ "supported_languages": [ { "source_lang": "BG", "target_lang": "CS" }, { "source_lang": "BG", "target_lang": "DA" } ] }

Any ordered pair of two different base codes is allowed, which makes 36 × 35 = 1,260 entries. The endpoint exists for clients that expect to discover pairs dynamically.

Glossaries are immutable

There is no update endpoint. To change terms, create a new glossary with the revised entries, switch glossary_id in your requests, then delete the old one. The translation cache keys on the glossary id and its version, so a new glossary never receives results that were computed with different entries.

Working advice

• Prefer several small, domain-specific glossaries over one large list. A

glossary that tries to translate common vocabulary competes with the engine instead of guiding it.

• Match the capitalisation your source texts actually use. Add a second entry

if a term appears both capitalised and in lower case.

• Keep the source term as it appears in running text, not as a dictionary

headword, if the two differ.