> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lehar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pronunciation Dictionaries

> Control how an agent says specific words — brand names, places, acronyms — across every voice.

A **pronunciation dictionary** is a named set of substitution rules that fix how an agent speaks particular words. Bind one to an [agent](/concepts/agents) and, just before each line is spoken, the agent rewrites the matching text — so "Lehar" becomes "luh-har" no matter which TTS provider is running.

## The model

A pronunciation dictionary is a **named entity in your workspace**, created and edited independently of any agent. An agent points at one through `pronunciation_dictionary_id`:

* **One dictionary per agent.** An agent applies exactly the dictionary it is bound to.
* **Many agents per dictionary.** Several agents can share one dictionary.
* **Provider-agnostic.** Rules are applied as a text substitution **before** the words reach text-to-speech, so they behave identically for Sarvam, Murf, ElevenLabs, Edge, and every other [provider](/concepts/providers).
* **Read for all, write for admins.** Every workspace member can list and attach dictionaries (`pronunciation_dictionary:read`); only admins can create, edit, or delete them (`pronunciation_dictionary:write`).
* Names are unique within a workspace; creating a duplicate returns `409`.

## Manage dictionaries

| Method | Path                               | Scope                            | Notes                                                                                             |
| ------ | ---------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------- |
| GET    | `/pronunciation-dictionaries`      | `pronunciation_dictionary:read`  | List (paginated), each with an `entry_count`.                                                     |
| POST   | `/pronunciation-dictionaries`      | `pronunciation_dictionary:write` | `name` (required), `description?`, `entries?`. Returns `201`.                                     |
| PATCH  | `/pronunciation-dictionaries/{id}` | `pronunciation_dictionary:write` | Partial update. Sending `entries` **replaces the whole list**; `description: ""` clears the note. |
| DELETE | `/pronunciation-dictionaries/{id}` | `pronunciation_dictionary:write` | Delete. Agents referencing it are auto-unbound; the response reports `agents_unbound`.            |

```bash theme={null}
curl -X POST "$LEHAR_BASE_URL/pronunciation-dictionaries" \
  -H "X-API-KEY: $LEHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand names",
    "entries": [
      { "grapheme": "Lehar", "replacement": "luh-har", "language": "en" },
      { "grapheme": "Bengaluru", "replacement": "beng-uh-loo-roo" }
    ]
  }'
```

## Entry shape

Each entry is a single rule. A dictionary holds up to **500** entries.

| Field         | Required | Notes                                                                      |
| ------------- | -------- | -------------------------------------------------------------------------- |
| `grapheme`    | Yes      | The written form to match (max 200 chars).                                 |
| `replacement` | Yes      | What the agent should say instead (max 500 chars).                         |
| `kind`        | No       | `substitution` (default) or `ipa`.                                         |
| `language`    | No       | Optional language tag (max 32 chars) that scopes the rule to one language. |

Two entries may not share the same `grapheme` + `language`, so a match is always unambiguous. `substitution` rewrites the spoken text and works with every provider; `ipa` is reserved for a future provider-native path (stored today, applied only where the catalog lists the provider under `pronunciation_dictionary_ipa_providers`).

## Attach to an agent

Set `pronunciation_dictionary_id` on the agent — on create or while it is a `draft`:

```bash theme={null}
curl -X PUT "$LEHAR_BASE_URL/agent/agent_sales_hi" \
  -H "X-API-KEY: $LEHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "pronunciation_dictionary_id": "pd_01EXAMPLE" }'
```

The dictionary must belong to the same workspace. Deleting a dictionary that agents still reference simply unbinds them — their `pronunciation_dictionary_id` becomes `null`, and nothing else changes.

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/concepts/agents">Bind a dictionary to an agent.</Card>
  <Card title="Providers & Models" icon="microchip" href="/concepts/providers">Where voices are chosen.</Card>
</CardGroup>