> ## Documentation Index
> Fetch the complete documentation index at: https://dev.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 omits `updateMask`, so both `displayName` and `pronunciations` are updated. The `pronunciations` value must contain the complete desired dictionary; entries omitted from it are deleted.

## Update selected fields

Use the optional `updateMask` query parameter for a partial update. 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 theme={"system"}
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`. Omit `updateMask` or set it to `*` only when you intend to update both fields and supply both values.


## OpenAPI

````yaml patch /pronunciations/v1/workspaces/{workspaceId}/pronunciationDictionaries/{pronunciationDictionaryId}
openapi: 3.0.0
info:
  title: Inworld Pronunciation Dictionaries API
  version: v1
  description: >-
    Create and manage named pronunciation dictionaries. Each dictionary contains
    its complete set of pronunciation entries; create and update validate the
    supplied contents before committing them atomically.
  contact:
    name: Inworld AI
    url: https://inworld.ai
    email: support@inworld.ai
servers:
  - url: https://api.inworld.ai
security:
  - inworld_basic: []
tags:
  - name: Pronunciation dictionaries
    description: Manage workspace-owned named pronunciation dictionaries.
paths:
  /pronunciations/v1/workspaces/{workspaceId}/pronunciationDictionaries/{pronunciationDictionaryId}:
    patch:
      tags:
        - Pronunciation dictionaries
      summary: Update a pronunciation dictionary
      description: >-
        Updates a dictionary using optimistic concurrency. Include the current
        `etag` from a get, list, create, or update response. Updating
        `pronunciations` atomically replaces the complete entry list, so entries
        omitted from the request are deleted. Omit `updateMask` only when
        supplying both mutable fields, or use it to select only `displayName` or
        `pronunciations`.
      operationId: Pronunciations_UpdatePronunciationDictionary
      parameters:
        - $ref: '#/components/parameters/workspaceId'
        - $ref: '#/components/parameters/pronunciationDictionaryId'
        - name: updateMask
          in: query
          required: false
          description: >-
            Comma-separated fields to update, using lowerCamelCase JSON names.
            Supported fields are `displayName` and `pronunciations`. Omit this
            parameter or set it to `*` to update all mutable fields.
          schema:
            type: string
            example: displayName,pronunciations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PronunciationDictionaryUpdate'
            example:
              displayName: Product names v2
              pronunciations:
                - displayHeadword: World
                  languageCode: en-US
                  phoneSymbols:
                    - w
                    - ɜː
                    - l
                    - d
              etag: tLKwUsvfq4TjPZQYhA9Dg3pM
      responses:
        '200':
          description: The updated complete dictionary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PronunciationDictionary'
        '409':
          $ref: '#/components/responses/etagConflict'
        default:
          $ref: '#/components/responses/error'
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --request PATCH \
              "https://api.inworld.ai/pronunciations/v1/workspaces/${INWORLD_WORKSPACE_ID}/pronunciationDictionaries/${PRONUNCIATION_DICTIONARY_ID}" \
              --header "Authorization: Basic ${INWORLD_API_KEY}" \
              --header "Content-Type: application/json" \
              --data "{\"displayName\":\"Product names v2\",\"pronunciations\":[{\"displayHeadword\":\"World\",\"languageCode\":\"en-US\",\"phoneSymbols\":[\"w\",\"ɜː\",\"l\",\"d\"]}],\"etag\":\"${PRONUNCIATION_DICTIONARY_ETAG}\"}"
        - lang: python
          label: Python
          source: |-
            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,
                headers={"Authorization": f"Basic {os.environ['INWORLD_API_KEY']}"},
                json={
                    "displayName": "Product names v2",
                    "pronunciations": [
                        {
                            "displayHeadword": "World",
                            "languageCode": "en-US",
                            "phoneSymbols": ["w", "ɜː", "l", "d"],
                        }
                    ],
                    "etag": os.environ["PRONUNCIATION_DICTIONARY_ETAG"],
                },
            )
            response.raise_for_status()
            print(response.json())
        - lang: javascript
          label: JavaScript
          source: >-
            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}`;


            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: 'World',
                    languageCode: 'en-US',
                    phoneSymbols: ['w', 'ɜː', 'l', 'd'],
                  },
                ],
                etag: PRONUNCIATION_DICTIONARY_ETAG,
              }),
            });


            if (!response.ok) throw new Error(await response.text());

            console.log(await response.json());
components:
  parameters:
    workspaceId:
      name: workspaceId
      in: path
      required: true
      description: >-
        ID of the workspace that owns the dictionary. It must match a workspace
        accessible to the API key.
      schema:
        type: string
        minLength: 1
        maxLength: 61
        pattern: ^[a-z0-9_-]+$
        example: my-workspace
    pronunciationDictionaryId:
      name: pronunciationDictionaryId
      in: path
      required: true
      description: Service-assigned UUID from the dictionary's resource `name`.
      schema:
        type: string
        format: uuid
        example: 2d470a1e-0262-4f22-9b46-5353d454d988
  schemas:
    PronunciationDictionaryUpdate:
      type: object
      description: >-
        Mutable dictionary fields and the current concurrency token. When
        `updateMask` is omitted, supply both mutable fields because both are
        applied; an explicit mask selects a partial update.
      required:
        - etag
      properties:
        displayName:
          $ref: '#/components/schemas/PronunciationDictionaryDisplayName'
        pronunciations:
          $ref: '#/components/schemas/PronunciationEntries'
        etag:
          type: string
          minLength: 1
          description: >-
            Current dictionary etag. A stale value fails the update rather than
            overwriting a concurrent change.
      additionalProperties: false
    PronunciationDictionary:
      type: object
      description: >-
        A workspace-owned named pronunciation dictionary with its complete
        contents.
      required:
        - name
        - displayName
        - pronunciations
        - etag
        - createTime
        - updateTime
      properties:
        name:
          type: string
          readOnly: true
          description: >-
            Service-assigned resource name in the form
            `workspaces/{workspace}/pronunciationDictionaries/{uuid}`.
          example: >-
            workspaces/my-workspace/pronunciationDictionaries/2d470a1e-0262-4f22-9b46-5353d454d988
        displayName:
          $ref: '#/components/schemas/PronunciationDictionaryDisplayName'
        pronunciations:
          $ref: '#/components/schemas/PronunciationEntries'
        etag:
          type: string
          description: >-
            Optimistic-concurrency token. Include the current value when
            updating or deleting the dictionary.
        createTime:
          type: string
          format: date-time
          readOnly: true
          description: Time at which the dictionary was created.
        updateTime:
          type: string
          format: date-time
          readOnly: true
          description: Time at which the dictionary's metadata or contents last changed.
      additionalProperties: false
    PronunciationDictionaryDisplayName:
      type: string
      minLength: 1
      maxLength: 64
      description: >-
        Non-blank human-readable dictionary name, containing at most 64 Unicode
        code points.
      example: Product names
    PronunciationEntries:
      type: array
      maxItems: 1000
      description: >-
        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.
      items:
        $ref: '#/components/schemas/PronunciationEntry'
      default: []
    rpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
          description: gRPC status code.
        message:
          type: string
          description: Developer-facing error message.
        details:
          type: array
          description: >-
            Structured error details. Validation failures can include
            `google.rpc.BadRequest` field violations without echoing
            customer-authored pronunciation content.
          items:
            $ref: '#/components/schemas/protobufAny'
    PronunciationEntry:
      type: object
      description: >-
        One validated pronunciation override. The service can canonicalize
        supported phone aliases before returning the saved entry.
      required:
        - displayHeadword
        - languageCode
        - phoneSymbols
      properties:
        displayHeadword:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            Caller-facing spelling. It must be non-blank and tokenize to exactly
            one replaceable lexical token.
          example: Hello
        languageCode:
          type: string
          minLength: 1
          description: >-
            Supported canonical BCP-47 language code, such as `en-US`. Use the
            exact canonical spelling; `auto` and unspecified languages are not
            accepted.
          example: en-US
        phoneSymbols:
          type: array
          minItems: 1
          maxItems: 64
          description: >-
            Ordered phone tokens or supported aliases. Each token can contain at
            most 16 Unicode code points and must be valid for the selected
            language. Send symbols without `/` delimiters.
          items:
            type: string
            minLength: 1
            maxLength: 16
          example:
            - h
            - ə
            - l
            - oʊ
      additionalProperties: false
    protobufAny:
      type: object
      properties:
        '@type':
          type: string
          description: A URL identifying the serialized protocol-buffer message type.
      additionalProperties: true
  responses:
    etagConflict:
      description: >-
        The supplied `etag` is stale. Get the dictionary again, reconcile your
        changes with the current resource, and retry using its new `etag`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/rpcStatus'
          example:
            code: 10
            message: Pronunciation dictionary etag does not match
            details: []
    error:
      description: The request failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/rpcStatus'
  securitySchemes:
    inworld_basic:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        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.

````