> ## 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.

# Create a pronunciation dictionary

> Creates a pronunciation dictionary — a named set of substitution rules the agent applies to its own speech just before it is spoken, identically across every voice provider. Attach one to an agent with the agent's `pronunciation_dictionary_id` (one dictionary per agent). Scope `pronunciation_dictionary:write` (admins only). Names must be unique within the workspace.



## OpenAPI

````yaml /api-reference/openapi.json post /pronunciation-dictionaries
openapi: 3.1.0
info:
  title: Lehar API
  version: v0
  description: >-
    Customer-facing REST API for the Lehar voice-AI platform. Platform-admin
    endpoints are intentionally excluded from this reference. Regenerate with
    `npm run sync:openapi`.
servers:
  - url: https://api.lehar.ai/ca/api/v0
security:
  - ApiKeyAuth: []
  - BearerAuth: []
paths:
  /pronunciation-dictionaries:
    post:
      tags:
        - Pronunciation Dictionaries
      summary: Create a pronunciation dictionary
      description: >-
        Creates a pronunciation dictionary — a named set of substitution rules
        the agent applies to its own speech just before it is spoken,
        identically across every voice provider. Attach one to an agent with the
        agent's `pronunciation_dictionary_id` (one dictionary per agent). Scope
        `pronunciation_dictionary:write` (admins only). Names must be unique
        within the workspace.
      operationId: >-
        create_pronunciation_dictionary_ca_api_v0_pronunciation_dictionaries_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: Unique name for the dictionary (max 200 chars).
                description:
                  type: string
                  description: Optional note (max 2000 chars).
                entries:
                  type: array
                  description: >-
                    Replacement rules, applied top to bottom. At most 500
                    entries; two entries may not share the same grapheme +
                    language.
                  items:
                    type: object
                    required:
                      - grapheme
                      - replacement
                    properties:
                      grapheme:
                        type: string
                        description: The written form to match (max 200 chars).
                      replacement:
                        type: string
                        description: What the agent should say instead (max 500 chars).
                      kind:
                        type: string
                        enum:
                          - substitution
                          - ipa
                        default: substitution
                        description: >-
                          `substitution` rewrites the text before speech and
                          works with every voice provider. `ipa` is reserved for
                          a future provider-native path — stored but not yet
                          applied.
                      language:
                        type: string
                        description: >-
                          Optional BCP-47 language tag (max 32 chars) that
                          scopes the rule to one language.
            example:
              name: Brand names
              description: How the agent should pronounce product and place names
              entries:
                - grapheme: Lehar
                  replacement: luh-har
                  language: en
                - grapheme: Bengaluru
                  replacement: beng-uh-loo-roo
      responses:
        '201':
          description: Created dictionary
          content:
            application/json:
              example:
                id: pd_01EXAMPLE
                name: Brand names
                description: How the agent should pronounce product and place names
                entries:
                  - grapheme: Lehar
                    replacement: luh-har
                    kind: substitution
                    language: en
                  - grapheme: Bengaluru
                    replacement: beng-uh-loo-roo
                    kind: substitution
                entry_count: 2
                created_by_user_id: user_01EXAMPLE
                created_at: '2026-08-24T10:00:00Z'
                updated_at: '2026-08-24T10:00:00Z'
        '400':
          description: Invalid request
          content:
            application/json:
              example:
                error:
                  code: invalid_request
                  message: name is required
        '403':
          description: Missing pronunciation_dictionary:write (admins only)
          content:
            application/json:
              example:
                error:
                  code: forbidden
                  message: Insufficient scope
        '409':
          description: A dictionary with this name already exists
          content:
            application/json:
              example:
                error:
                  code: conflict
                  message: >-
                    A pronunciation dictionary named 'Brand names' already
                    exists
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    BearerAuth:
      type: http
      scheme: bearer

````