> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage a Glossary

> Create, update, read, and delete a HeyGen brand glossary over the API, with full-list updates that preserve per-language rules and a field map from the v1 brand voice lists.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=3e4c2594813dcfd56985f3d63e3ba321)

A workspace has one [brand glossary](https://heygen-1fa696a7.mintlify.site/docs/brand-glossary.md). Create it once, then keep it current with updates. Workspaces that made several glossaries before this limit keep all of them, and each stays usable.

## Create

[`POST /v3/brand-glossaries`](https://heygen-1fa696a7.mintlify.site/reference/create-brand-glossary) takes a `name` (1 to 64 characters) and any of the three lists. The `201` response is the full glossary, usable immediately. If the workspace already has a glossary, the request returns `409 conflict`; find it with [`GET /v3/brand-glossaries`](https://heygen-1fa696a7.mintlify.site/reference/list-brand-glossaries) and change it with an [update](#update).

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/brand-glossaries" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "name": "Acme Product Names",
    "terms": [
      { "term": "HeyGen", "pronunciation": "hey-jen" },
      { "term": "2024", "pronunciation": "twenty twenty-four" }
    ],
    "do_not_translate_terms": [
      { "term": "HeyGen" }
    ],
    "forced_translations": [
      { "term": "CEO", "translation": "Geschäftsführer" }
    ]
  }'
```

Send an `Idempotency-Key` so a retry replays the first response instead of failing.

## Update

[`PATCH /v3/brand-glossaries/{brand_glossary_id}`](https://heygen-1fa696a7.mintlify.site/reference/update-brand-glossary) replaces each field independently. Omit a field to leave it alone, send a list to replace it in full, send `[]` to clear it. Send at least one field. A list replaces that kind of rule across every language, so send language-specific entries back with their language fields. A term repeated for the same language within one list returns `409 conflict`.

To add a single entry, read the glossary, append, and send the whole list back:

```python theme={null}
import requests

base = "https://api.heygen.com/v3/brand-glossaries/8c2d5e91a47b4f3c8d1e6a9b2f5c7d40"
headers = {"X-Api-Key": HEYGEN_API_KEY}

current = requests.get(base, headers=headers).json()["data"]["terms"]
current.append({"term": "Reformer", "pronunciation": "ree-form-er"})

requests.patch(base, headers=headers, json={"terms": current})
```

Entries read back this way keep their [IPA](https://heygen-1fa696a7.mintlify.site/docs/brand-glossary/pronunciations.md#editing-ipa) and language fields. Tone settings are managed in the HeyGen app under **Brand Kit** and stay as they are.

## Read

[`GET /v3/brand-glossaries`](https://heygen-1fa696a7.mintlify.site/reference/list-brand-glossaries) lists names, IDs, and timestamps, paged with `limit` and `token`. [`GET /v3/brand-glossaries/{brand_glossary_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-brand-glossary) returns the full glossary; `do_not_translate_terms` and `forced_translations` appear whenever the glossary has rules of that kind, including rules set in the app. Read it when a video pronounces or translates a term unexpectedly.

## Delete

[`DELETE /v3/brand-glossaries/{brand_glossary_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-brand-glossary) removes a glossary. Videos and translations already created with it keep their audio and text. This cannot be undone.

## Migrating from v1 brand voice

`brand_voice_id` is the former name of `brand_glossary_id`. It is still accepted on [`POST /v3/templates/{template_id}`](https://heygen-1fa696a7.mintlify.site/reference/generate-video-from-template), [`POST /v3/video-translations`](https://heygen-1fa696a7.mintlify.site/reference/create-video-translation), and [`POST /v3/video-translations/proofreads`](https://heygen-1fa696a7.mintlify.site/reference/create-proofread-session). [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video) takes `brand_glossary_id`.

The lists of the legacy `POST /v1/brand_voice/{brand_voice_id}` map to the v3 glossary as follows (see the [v1/v2 sunset](https://heygen-1fa696a7.mintlify.site/endpoint-version-comparison.md)):

| v1 field | v1 shape | v3 field | v3 shape |
| - | - | - | - |
| `vocabulary` | `[["HeyGen", "hey-jen"]]` | `terms` | `[{ "term": "HeyGen", "pronunciation": "hey-jen" }]` |
| `blacklist` | `["HeyGen"]` | `do_not_translate_terms` | `[{ "term": "HeyGen" }]` |
| `whitelist` | `[["CEO", "Geschäftsführer"]]` | `forced_translations` | `[{ "term": "CEO", "translation": "Geschäftsführer" }]` |
| `tones`, `tone` | | | Managed in the HeyGen app under **Brand Kit**. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.