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

# Update a pronunciation dictionary

> Update a dictionary's display name or atomically replace all of its pronunciation entries.

<Warning>
Updating `pronunciations` replaces the complete entry list. Entries omitted from the request are deleted, and an empty list clears the dictionary.
</Warning>

The request must include the current `etag`. If another writer has changed the dictionary, the stale `etag` returns HTTP `409 Conflict` instead of overwriting the newer state. Get the dictionary again, reconcile the changes, and retry with the new value.

The primary example supplies both mutable fields and sets `updateMask=displayName,pronunciations`. The `pronunciations` value must contain the complete desired dictionary; entries omitted from it are deleted.

## Update selected fields

Always send an explicit `updateMask` query parameter in REST requests. Its comma-separated field names use the same lowerCamelCase spelling as the JSON request body. For example, rename a dictionary without changing its entries:

```bash
curl --request PATCH \
  "https://api.inworld.ai/pronunciations/v1/workspaces/${INWORLD_WORKSPACE_ID}/pronunciationDictionaries/${PRONUNCIATION_DICTIONARY_ID}?updateMask=displayName" \
  --header "Authorization: Basic ${INWORLD_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "{\"displayName\":\"Product names v2\",\"etag\":\"${PRONUNCIATION_DICTIONARY_ETAG}\"}"
```

Supported fields are `displayName` and `pronunciations`. Use `updateMask=displayName,pronunciations` or `updateMask=*` only when you intend to update both fields and supply both values. Keep `etag` in the request body; it is a concurrency token, not an update-mask field.

## API reference

**Endpoint:** `PATCH https://api.inworld.ai/pronunciations/v1/workspaces/{workspaceId}/pronunciationDictionaries/{pronunciationDictionaryId}`

### Authorization

- `Authorization` (string; required) — Your [authentication](../../../api-reference/introduction) credentials. For Basic authentication, send `Basic $INWORLD_API_KEY`. Use a Standard API key for the target workspace. Voices Read access permits list and get; Voices Write access permits all five methods.

### Path parameters

- `workspaceId` (string; required) — ID of the workspace that owns the dictionary. It must match a workspace accessible to the API key.
- `pronunciationDictionaryId` (string; required) — Service-assigned UUID from the dictionary's resource `name`.

### Query parameters

- `updateMask` (string) — Comma-separated fields to update, using lowerCamelCase JSON names. Supported fields are `displayName` and `pronunciations`. For REST requests, send an explicit mask. Use `displayName,pronunciations` or `*` to update both mutable fields. Keep `etag` in the request body, not in the mask.

### Request body

Content type: `application/json`

- `displayName` (string) — Non-blank human-readable dictionary name, containing at most 64 Unicode code points.
- `pronunciations` (object[]; default: []) — Complete dictionary contents. A dictionary can contain up to 1,000 entries and must remain within the 512 KiB encoded dictionary limit. Entries must be unique after language-aware lexical canonicalization.
  - `displayHeadword` (string; required) — Caller-facing spelling. It must be non-blank and tokenize to exactly one replaceable lexical token.
  - `languageCode` (string; required) — Concrete language supported for pronunciation entries, in its exact canonical BCP-47 spelling: for example, `en-US`, not `en-us`, `EN_US`, or `en`. Blank values and `auto` are not accepted. The general TTS language list is not a pronunciation catalog. See [Author pronunciation entries](https://docs.inworld.ai/tts/capabilities/pronunciation-dictionaries.md#author-pronunciation-entries).
  - `phoneSymbols` (string[]; required) — Ordered array of complete phone tokens supported for the selected language, not a slash-delimited or whitespace-separated IPA string. Each token can contain at most 16 Unicode code points. Preserve compound-phone token boundaries; do not split by Unicode character. Supported aliases may be canonicalized in the response. See [phone-token guidance and examples](https://docs.inworld.ai/tts/capabilities/pronunciation-dictionaries.md#send-phone-tokens-not-an-ipa-string).
- `etag` (string; required) — Current dictionary etag. A stale value fails the update rather than overwriting a concurrent change.

#### Request example

```json
{
  "displayName": "Product names v2",
  "pronunciations": [
    {
      "displayHeadword": "Ship",
      "languageCode": "en-US",
      "phoneSymbols": [
        "ʃ",
        "ɪ",
        "p"
      ]
    }
  ],
  "etag": "tLKwUsvfq4TjPZQYhA9Dg3pM"
}
```

### Response

Status: `200`. Content type: `application/json`.

- `name` (string; required) — Service-assigned resource name in the form `workspaces/{workspace}/pronunciationDictionaries/{uuid}`.
- `displayName` (string; required) — Non-blank human-readable dictionary name, containing at most 64 Unicode code points.
- `pronunciations` (object[]; required; default: []) — Complete dictionary contents. A dictionary can contain up to 1,000 entries and must remain within the 512 KiB encoded dictionary limit. Entries must be unique after language-aware lexical canonicalization.
  - `displayHeadword` (string; required) — Caller-facing spelling. It must be non-blank and tokenize to exactly one replaceable lexical token.
  - `languageCode` (string; required) — Concrete language supported for pronunciation entries, in its exact canonical BCP-47 spelling: for example, `en-US`, not `en-us`, `EN_US`, or `en`. Blank values and `auto` are not accepted. The general TTS language list is not a pronunciation catalog. See [Author pronunciation entries](https://docs.inworld.ai/tts/capabilities/pronunciation-dictionaries.md#author-pronunciation-entries).
  - `phoneSymbols` (string[]; required) — Ordered array of complete phone tokens supported for the selected language, not a slash-delimited or whitespace-separated IPA string. Each token can contain at most 16 Unicode code points. Preserve compound-phone token boundaries; do not split by Unicode character. Supported aliases may be canonicalized in the response. See [phone-token guidance and examples](https://docs.inworld.ai/tts/capabilities/pronunciation-dictionaries.md#send-phone-tokens-not-an-ipa-string).
- `etag` (string; required) — Optimistic-concurrency token. Include the current value when updating or deleting the dictionary.
- `createTime` (string; required) — Time at which the dictionary was created.
- `updateTime` (string; required) — Time at which the dictionary's metadata or contents last changed.

### Response examples

#### 200: default_response

```json
{
  "name": "workspaces/my-workspace/pronunciationDictionaries/2d470a1e-0262-4f22-9b46-5353d454d988",
  "displayName": "Product names",
  "pronunciations": [],
  "etag": "string",
  "createTime": "string",
  "updateTime": "string"
}
```

#### 409: default_response

```json
{
  "code": 10,
  "message": "Pronunciation dictionary etag does not match",
  "details": []
}
```

#### default: default_response

```json
{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}
```

### Code examples

#### cURL

```bash
curl --request PATCH \
  "https://api.inworld.ai/pronunciations/v1/workspaces/${INWORLD_WORKSPACE_ID}/pronunciationDictionaries/${PRONUNCIATION_DICTIONARY_ID}?updateMask=displayName,pronunciations" \
  --header "Authorization: Basic ${INWORLD_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "{\"displayName\":\"Product names v2\",\"pronunciations\":[{\"displayHeadword\":\"Ship\",\"languageCode\":\"en-US\",\"phoneSymbols\":[\"ʃ\",\"ɪ\",\"p\"]}],\"etag\":\"${PRONUNCIATION_DICTIONARY_ETAG}\"}"
```

#### Python

```python
import os
import requests

workspace_id = os.environ["INWORLD_WORKSPACE_ID"]
dictionary_id = os.environ["PRONUNCIATION_DICTIONARY_ID"]
url = (
    "https://api.inworld.ai/pronunciations/v1/"
    f"workspaces/{workspace_id}/pronunciationDictionaries/{dictionary_id}"
)
response = requests.patch(
    url,
    params={"updateMask": "displayName,pronunciations"},
    headers={"Authorization": f"Basic {os.environ['INWORLD_API_KEY']}"},
    json={
        "displayName": "Product names v2",
        "pronunciations": [
            {
                "displayHeadword": "Ship",
                "languageCode": "en-US",
                "phoneSymbols": ["ʃ", "ɪ", "p"],
            }
        ],
        "etag": os.environ["PRONUNCIATION_DICTIONARY_ETAG"],
    },
)
response.raise_for_status()
print(response.json())
```

#### JavaScript

```javascript
const { INWORLD_API_KEY, INWORLD_WORKSPACE_ID, PRONUNCIATION_DICTIONARY_ID, PRONUNCIATION_DICTIONARY_ETAG } = process.env;
const url = `https://api.inworld.ai/pronunciations/v1/workspaces/${INWORLD_WORKSPACE_ID}/pronunciationDictionaries/${PRONUNCIATION_DICTIONARY_ID}?updateMask=displayName,pronunciations`;

const response = await fetch(url, {
  method: 'PATCH',
  headers: {
    Authorization: `Basic ${INWORLD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    displayName: 'Product names v2',
    pronunciations: [
      {
        displayHeadword: 'Ship',
        languageCode: 'en-US',
        phoneSymbols: ['ʃ', 'ɪ', 'p'],
      },
    ],
    etag: PRONUNCIATION_DICTIONARY_ETAG,
  }),
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```