Glossaries¶

Glossaries enforce consistent terminology across translations. Create a glossary once and reference it by ID in any translation job.

GlossaryEntry Structure¶

Field	Type	Required	Description
`id`	`string`	auto	Auto-generated: `term_<hex8>`
`term`	`string`	yes	Source term
`translations`	`dict[string, string]`	yes (min 1)	Target language → translated term mapping
`context`	`string`	no	Disambiguates polysemous terms, e.g. `"medical context"`
`domain`	`string`	no	Subject domain, e.g. `"medical"`, `"finance"`
`forbidden_alternatives`	`list[string]`	no	Terms the translator must not use
`status`	`"approved"` \| `"pending"` \| `"deprecated"`	no	Default: `"approved"`

GET /v1/glossaries¶

List all glossaries for the authenticated API key. Entries are not included.

Auth: X-API-Key required

Response¶

[
  {
    "id": "gloss_abc12345",
    "name": "Medical Terms",
    "description": "EN→DE medical terminology",
    "source_lang": "en",
    "entries_count": 42,
    "created_at": "2026-03-01T08:00:00+00:00",
    "updated_at": "2026-03-05T14:30:00+00:00"
  }
]

Error: 401

POST /v1/glossaries¶

Create a new glossary.

Auth: X-API-Key required Status: 201 Created

Request Body¶

Field	Type	Required	Description
`name`	`string`	yes	Glossary name
`description`	`string`	no	Optional description
`source_lang`	`string`	no	Source language code
`entries`	`list[GlossaryEntry]`	no	Initial entries (default: `[]`)

Example¶

cURLPython

curl -X POST https://falara.io/v1/glossaries \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Medical Terms",
    "source_lang": "en",
    "entries": [
      {
        "term": "hypertension",
        "translations": { "de": "Bluthochdruck", "fr": "hypertension" },
        "context": "cardiovascular condition",
        "domain": "medical",
        "forbidden_alternatives": ["Hypertonie"],
        "status": "approved"
      }
    ]
  }'

r = requests.post(
    "https://falara.io/v1/glossaries",
    headers={"X-API-Key": "sk_live_..."},
    json={
        "name": "Medical Terms",
        "source_lang": "en",
        "entries": [
            {
                "term": "hypertension",
                "translations": {"de": "Bluthochdruck", "fr": "hypertension"},
                "context": "cardiovascular condition",
                "domain": "medical",
                "forbidden_alternatives": ["Hypertonie"],
                "status": "approved",
            }
        ],
    },
)
glossary_id = r.json()["id"]

Errors: 401, 500

GET /v1/glossaries/{glossary_id}¶

Retrieve a single glossary with all entries.

Auth: X-API-Key required

Response¶

{
  "id": "gloss_abc12345",
  "name": "Medical Terms",
  "description": null,
  "source_lang": "en",
  "entries": [
    {
      "id": "term_f3a1b2c3",
      "term": "hypertension",
      "translations": { "de": "Bluthochdruck", "fr": "hypertension" },
      "context": "cardiovascular condition",
      "domain": "medical",
      "forbidden_alternatives": ["Hypertonie"],
      "status": "approved"
    }
  ],
  "entries_count": 1,
  "created_at": "2026-03-01T08:00:00+00:00",
  "updated_at": "2026-03-05T14:30:00+00:00"
}

Errors: 401, 404

PUT /v1/glossaries/{glossary_id}¶

Partially update a glossary. Only fields included in the request body are updated.

Auth: X-API-Key required

Request Body (all fields optional)¶

Field	Type
`name`	`string`
`description`	`string`
`source_lang`	`string`
`entries`	`list[GlossaryEntry]`

Note

Setting entries replaces the full entries list. To add entries incrementally, fetch the current entries first and merge.

Response: GlossaryResponse (same as GET)

Errors: 401, 404

DELETE /v1/glossaries/{glossary_id}¶

Delete a glossary permanently.

Auth: X-API-Key required

Response: 204 No Content

Errors: 401, 404

Using a glossary in a translation job¶

Reference a glossary by its id in any translation request:

{
  "mode": "translation",
  "source_lang": "en",
  "target_lang": "de",
  "text": "The patient has hypertension.",
  "glossary_id": "gloss_abc12345"
}

Or pass entries inline without creating a stored glossary:

{
  "mode": "translation",
  "source_lang": "en",
  "target_lang": "de",
  "text": "The patient has hypertension.",
  "glossary": [
    {
      "term": "hypertension",
      "translations": { "de": "Bluthochdruck" },
      "forbidden_alternatives": ["Hypertonie"]
    }
  ]
}