openapi: 3.0.3
info:
  title: Tavus Developer API Collection Conversations Pronunciation Dictionaries API
  version: 1.0.0
  contact: {}
servers:
- url: https://tavusapi.com
security:
- apiKey: []
tags:
- name: Pronunciation Dictionaries
paths:
  /v2/pronunciation-dictionaries:
    post:
      tags:
      - Pronunciation Dictionaries
      summary: Create Pronunciation Dictionary
      description: 'Create a [pronunciation dictionary](/sections/conversational-video-interface/persona/pronunciation-dictionaries) with custom rules for controlling how words are spoken. Rules are automatically synced to both Cartesia and ElevenLabs so they work regardless of which TTS engine your persona uses.

        '
      operationId: createPronunciationDictionary
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the pronunciation dictionary. Max 255 characters.
                  example: Brand Terms
                rules:
                  type: array
                  description: List of pronunciation rules. Duplicate `text` values are not allowed. You can omit rules at creation and add them later via [Update Pronunciation Dictionary](/api-reference/pronunciation-dictionaries/update-pronunciation-dictionary).
                  items:
                    type: object
                    properties:
                      text:
                        type: string
                        description: The word or phrase to match. Max 200 characters.
                        example: Tavus
                      pronunciation:
                        type: string
                        description: How the text should be pronounced. For `alias` type, this is the replacement text. For `ipa` type, this is an IPA string (raw or pipe-delimited). Max 500 characters.
                        example: TAH-vus
                      type:
                        type: string
                        description: Rule type. One of `alias` or `ipa`.
                        enum:
                        - alias
                        - ipa
                        example: alias
                      case_sensitive:
                        type: boolean
                        description: Whether matching is case-sensitive.
                        default: false
                        example: false
                      word_boundaries:
                        type: boolean
                        description: Whether to match only whole words.
                        default: true
                        example: true
                    required:
                    - text
                    - pronunciation
                    - type
                  example:
                  - text: Tavus
                    pronunciation: TAH-vus
                    type: alias
              required:
              - name
      responses:
        '201':
          description: Pronunciation dictionary created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  pronunciation_dictionary_id:
                    type: string
                    description: Unique identifier for the pronunciation dictionary.
                    example: pd_abc123def456gh
                  name:
                    type: string
                    description: Name of the pronunciation dictionary.
                    example: Brand Terms
                  rules:
                    type: array
                    description: List of pronunciation rules.
                    items:
                      type: object
                      properties:
                        text:
                          type: string
                          example: Tavus
                        pronunciation:
                          type: string
                          example: TAH-vus
                        type:
                          type: string
                          enum:
                          - alias
                          - ipa
                          example: alias
                        case_sensitive:
                          type: boolean
                          example: false
                        word_boundaries:
                          type: boolean
                          example: true
                  rules_count:
                    type: integer
                    description: Number of rules in the dictionary.
                    example: 1
                  created_at:
                    type: string
                    description: ISO 8601 timestamp of when the dictionary was created.
                    example: '2025-01-15T10:30:00Z'
                  updated_at:
                    type: string
                    description: ISO 8601 timestamp of when the dictionary was last updated.
                    example: '2025-01-15T10:30:00Z'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The error message
                    example: 'Invalid request: name is required'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The error message
                    example: Invalid access token
      security:
      - apiKey: []
    get:
      tags:
      - Pronunciation Dictionaries
      summary: List Pronunciation Dictionaries
      description: 'List all pronunciation dictionaries for the authenticated user with pagination.

        '
      operationId: listPronunciationDictionaries
      parameters:
      - in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        description: 'Number of results per page. Range: 1-100.'
        example: 10
      - in: query
        name: page
        schema:
          type: integer
          default: 0
        description: Zero-based page number.
        example: 0
      - in: query
        name: sort
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        description: Sort order by creation date.
        example: desc
      responses:
        '200':
          description: List of pronunciation dictionaries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: Dictionaries for the current page; use `total_count`, `page`, and `limit` with the query parameters for pagination.
                    items:
                      type: object
                      properties:
                        pronunciation_dictionary_id:
                          type: string
                          description: Unique identifier for the pronunciation dictionary.
                          example: pd_abc123def456gh
                        name:
                          type: string
                          description: Name of the pronunciation dictionary.
                          example: Brand Terms
                        rules_count:
                          type: integer
                          description: Number of rules in the dictionary. List responses omit the full `rules` array; use [Get Pronunciation Dictionary](/api-reference/pronunciation-dictionaries/get-pronunciation-dictionary) to retrieve rules.
                          example: 3
                        created_at:
                          type: string
                          description: ISO 8601 timestamp of when the dictionary was created.
                          example: '2025-01-15T10:30:00Z'
                        updated_at:
                          type: string
                          description: ISO 8601 timestamp of when the dictionary was last updated.
                          example: '2025-01-15T10:30:00Z'
                  total_count:
                    type: integer
                    description: Total number of pronunciation dictionaries for the user
                    example: 2
                  page:
                    type: integer
                    description: Current page number
                    example: 0
                  limit:
                    type: integer
                    description: Number of dictionaries per page
                    example: 10
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The error message
                    example: Invalid access token
      security:
      - apiKey: []
  /v2/pronunciation-dictionaries/{dictionary_id}:
    get:
      tags:
      - Pronunciation Dictionaries
      summary: Get Pronunciation Dictionary
      description: 'Retrieve a pronunciation dictionary by its ID, including all rules.

        '
      operationId: getPronunciationDictionary
      parameters:
      - in: path
        name: dictionary_id
        required: true
        schema:
          type: string
        description: The unique identifier of the pronunciation dictionary.
        example: pd_abc123def456gh
      responses:
        '200':
          description: Pronunciation dictionary details
          content:
            application/json:
              schema:
                type: object
                properties:
                  pronunciation_dictionary_id:
                    type: string
                    description: Unique identifier for the pronunciation dictionary.
                    example: pd_abc123def456gh
                  name:
                    type: string
                    description: Name of the pronunciation dictionary.
                    example: Brand Terms
                  rules:
                    type: array
                    description: List of pronunciation rules.
                    items:
                      type: object
                      properties:
                        text:
                          type: string
                          example: Tavus
                        pronunciation:
                          type: string
                          example: TAH-vus
                        type:
                          type: string
                          enum:
                          - alias
                          - ipa
                          example: alias
                        case_sensitive:
                          type: boolean
                          example: false
                        word_boundaries:
                          type: boolean
                          example: true
                  rules_count:
                    type: integer
                    description: Number of rules in the dictionary.
                    example: 1
                  created_at:
                    type: string
                    description: ISO 8601 timestamp of when the dictionary was created.
                    example: '2025-01-15T10:30:00Z'
                  updated_at:
                    type: string
                    description: ISO 8601 timestamp of when the dictionary was last updated.
                    example: '2025-01-15T10:30:00Z'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The error message
                    example: Invalid access token
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The error message
                    example: Pronunciation dictionary not found
      security:
      - apiKey: []
    patch:
      tags:
      - Pronunciation Dictionaries
      summary: Update Pronunciation Dictionary
      description: 'Update a pronunciation dictionary''s name or rules using [JSON Patch](https://jsonpatch.com/) format (RFC 6902). Supported mutable fields are `name` and `rules`.

        '
      operationId: patchPronunciationDictionary
      parameters:
      - in: path
        name: dictionary_id
        required: true
        schema:
          type: string
        description: The unique identifier of the pronunciation dictionary.
        example: pd_abc123def456gh
      requestBody:
        description: "Read-only fields like `pronunciation_dictionary_id`, `created_at`, and `updated_at` are silently ignored. If all operations target read-only fields or result in no changes, the endpoint returns `304`.\n\nWhen rules are updated, all personas referencing this dictionary are automatically updated with the new provider-specific pronunciation data.\n\n**Note:** Updating rules replaces the entire rules array. There is no way to add or remove individual rules — provide the complete updated list.\n\nFor example:\n\n```json\n[\n  { \"op\": \"replace\", \"path\": \"/name\", \"value\": \"Updated Brand Terms\" },\n  { \"op\": \"replace\", \"path\": \"/rules\", \"value\": [\n    { \"text\": \"Tavus\", \"pronunciation\": \"TAH-vus\", \"type\": \"alias\" }\n  ]}\n]\n```\n"
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  op:
                    type: string
                    description: 'The operation to perform. Must be one of: add, remove, replace, copy, move, test'
                    enum:
                    - add
                    - remove
                    - replace
                    - copy
                    - move
                    - test
                    example: replace
                  path:
                    type: string
                    description: 'A JSON Pointer string that references a location within the target document where the operation is performed. Supported paths: `/name`, `/rules`.'
                    example: /name
                  value:
                    description: The value to be used within the operation. Required unless using `remove`.
                required:
                - op
                - path
            examples:
              Update name:
                value:
                - op: replace
                  path: /name
                  value: Updated Brand Terms
              Update rules:
                value:
                - op: replace
                  path: /rules
                  value:
                  - text: Tavus
                    pronunciation: TAH-vus
                    type: alias
                  - text: CVI
                    pronunciation: conversational video interface
                    type: alias
              Update both:
                value:
                - op: replace
                  path: /name
                  value: Updated Brand Terms
                - op: replace
                  path: /rules
                  value:
                  - text: Tavus
                    pronunciation: TAH-vus
                    type: alias
      responses:
        '200':
          description: Pronunciation dictionary updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  pronunciation_dictionary_id:
                    type: string
                    description: Unique identifier for the pronunciation dictionary.
                    example: pd_abc123def456gh
                  name:
                    type: string
                    description: Name of the pronunciation dictionary.
                    example: Updated Brand Terms
                  rules:
                    type: array
                    description: List of pronunciation rules.
                    items:
                      type: object
                      properties:
                        text:
                          type: string
                          example: Tavus
                        pronunciation:
                          type: string
                          example: TAH-vus
                        type:
                          type: string
                          enum:
                          - alias
                          - ipa
                          example: alias
                        case_sensitive:
                          type: boolean
                          example: false
                        word_boundaries:
                          type: boolean
                          example: true
                  rules_count:
                    type: integer
                    description: Number of rules in the dictionary.
                    example: 1
                  created_at:
                    type: string
                    description: ISO 8601 timestamp of when the dictionary was created.
                    example: '2025-01-15T10:30:00Z'
                  updated_at:
                    type: string
                    description: ISO 8601 timestamp of when the dictionary was last updated.
                    example: '2025-01-15T12:00:00Z'
        '304':
          description: No changes were made to the pronunciation dictionary
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The error message
                    example: 'Invalid request: duplicate text values in rules'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The error message
                    example: Invalid access token
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The error message
                    example: Pronunciation dictionary not found
        '422':
          description: Invalid JSON patch format
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The error message
                    example: Invalid JSON patch format
      security:
      - apiKey: []
    delete:
      tags:
      - Pronunciation Dictionaries
      summary: Delete Pronunciation Dictionary
      description: 'Permanently delete a pronunciation dictionary and remove it from all linked personas.

        '
      operationId: deletePronunciationDictionary
      parameters:
      - in: path
        name: dictionary_id
        required: true
        schema:
          type: string
        description: 'The unique identifier of the pronunciation dictionary to delete.


          **Warning:** This action is permanent. The dictionary is deleted from both Cartesia and ElevenLabs, and all personas referencing it will have their `pronunciation_dictionary_id` set to `null` and provider-specific pronunciation settings removed from `voice_settings`.

          '
        example: pd_abc123def456gh
      responses:
        '204':
          description: NO CONTENT - Pronunciation dictionary deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The error message
                    example: Invalid access token
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The error message
                    example: Pronunciation dictionary not found
      security:
      - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key