> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Brand Glossary

> Updates a brand glossary. A field you omit is left untouched, a list you send replaces the existing list in full across all languages, and an empty array removes every entry. Read the glossary and preserve every entry's `pronunciation_language` or `target_language` when sending an edited list; omitting a language field means all languages. A duplicate name or term/rule-type/language combination returns 409. A concurrent-edit conflict also returns 409 without saving the update; fetch the latest glossary and reapply your changes. Clients do not supply revisions. Tone settings are never modified by this endpoint. Temporary access-evaluation failures return 503; retry the request.



## OpenAPI

````yaml /openapi/external-api.json patch /v3/brand-glossaries/{brand_glossary_id}
openapi: 3.1.0
info:
  title: HeyGen External API
  version: 1.0.0
  description: >-
    HeyGen's external API for programmatic AI video creation. See
    https://docs.heygen.com for full documentation.
  contact:
    name: HeyGen Product Infra
    url: https://heygen.com
servers:
  - url: https://api.heygen.com
    description: Production
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: Video
    description: >-
      Create videos from a prompt or an avatar, then list, fetch, deliver and
      delete them
  - name: Avatar
    description: >-
      Create avatars and looks, record consent, and generate with the Avatar 6
      model
  - name: Voice
    description: Text to speech, speech to speech, and voice cloning
  - name: Audio
    description: Music, sound effects, transcription, stem separation and audio analysis
  - name: Image
    description: Generate images
  - name: Video editing
    description: >-
      Translate, lipsync, clip, analyze and remove filler words or backgrounds
      from existing videos
  - name: Video Agent
    description: Create videos from a prompt with an agent that plans, writes and edits
  - name: Templates
    description: Generate videos from reusable templates by replacing their variables
  - name: HyperFrames
    description: Render HyperFrames compositions into video
  - name: Brand
    description: >-
      Brand kits (colors, fonts, logos) and brand glossaries (term translations
      and pronunciations)
  - name: Assets and folders
    description: Upload files and organize them in folders
  - name: Batches
    description: Submit and track videos, translations, lipsyncs and uploads in bulk
  - name: Webhooks
    description: Manage webhook endpoints and events
  - name: Feedback
    description: Tell HeyGen how a generated result turned out
  - name: Account and usage
    description: Your account, the current API key, request logs and usage
paths:
  /v3/brand-glossaries/{brand_glossary_id}:
    patch:
      tags:
        - Brand
      summary: Update Brand Glossary
      description: >-
        Updates a brand glossary. A field you omit is left untouched, a list you
        send replaces the existing list in full across all languages, and an
        empty array removes every entry. Read the glossary and preserve every
        entry's `pronunciation_language` or `target_language` when sending an
        edited list; omitting a language field means all languages. A duplicate
        name or term/rule-type/language combination returns 409. A
        concurrent-edit conflict also returns 409 without saving the update;
        fetch the latest glossary and reapply your changes. Clients do not
        supply revisions. Tone settings are never modified by this endpoint.
        Temporary access-evaluation failures return 503; retry the request.
      operationId: updateBrandGlossary
      parameters:
        - name: brand_glossary_id
          in: path
          required: true
          schema:
            type: string
          description: Unique brand glossary identifier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBrandGlossaryRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BrandGlossaryDetail'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: invalid_parameter
                  message: Provide at least one field to update.
                  param: null
                  doc_url: null
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: unauthorized
                  message: Invalid or expired API key. Verify your x-api-key header.
                  param: null
                  doc_url: null
        '403':
          description: >-
            Forbidden — `error.code` is one of: `resource_access_denied`,
            `insufficient_api_key_scope`, `ai_vendor_access_restricted`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              examples:
                glossary_edit_restricted:
                  value:
                    error:
                      code: resource_access_denied
                      message: >-
                        Glossary editing is restricted by your workspace
                        settings.
                      doc_url: >-
                        https://developers.heygen.com/docs/error-codes#resource-access-denied
                insufficient_api_key_scope:
                  value:
                    error:
                      code: insufficient_api_key_scope
                      message: >-
                        This API key does not have permission to perform this
                        action. Required scope: brand:write.
                      doc_url: >-
                        https://developers.heygen.com/docs/error-codes#insufficient-api-key-scope
                ai_vendor_access_restricted:
                  value:
                    error:
                      code: ai_vendor_access_restricted
                      message: >-
                        Workspace AI vendor policy blocks google for this
                        request.
                      doc_url: >-
                        https://developers.heygen.com/docs/error-codes#ai-vendor-access-restricted
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: resource_not_found
                  message: Brand glossary not found.
                  param: null
                  doc_url: null
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: conflict
                  message: A brand glossary with this name already exists.
                  param: null
                  doc_url: null
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: rate_limit_exceeded
                  message: >-
                    Too many requests. Retry after the duration specified in the
                    Retry-After header.
                  param: null
                  doc_url: null
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
        '503':
          description: >-
            Temporarily unavailable — the request did not complete and is safe
            to retry.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: service_unavailable
                  message: >-
                    Brand glossary access is temporarily unavailable. Please
                    retry the request.
                  param: null
                  doc_url: null
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  schemas:
    UpdateBrandGlossaryRequest:
      additionalProperties: false
      description: >-
        Request body for PATCH /v3/brand-glossaries/{brand_glossary_id}.


        Each field is replaced independently: a field you omit is left
        untouched, a field you send

        replaces that value across all languages, and an empty array clears that
        list. To add a

        single entry, read the glossary, append to the list, and send the whole
        list back with every language field preserved.
      properties:
        name:
          default: null
          description: >-
            New display name. Surrounding whitespace is removed, and the trimmed
            name must be 1-64 characters and unique within your workspace,
            compared without regard to case. Omit to keep the current name.
          maxLength: 64
          minLength: 1
          title: Name
          type: string
        terms:
          default: null
          description: >-
            Replacement term list across all languages. Preserve every entry's
            pronunciation_language when editing. Omit to leave the existing
            terms untouched, or pass an empty array to remove them all.
          items:
            $ref: '#/components/schemas/BrandGlossaryTermWrite'
          title: Terms
          type: array
        do_not_translate_terms:
          default: null
          description: >-
            Replacement Don't Translate list. Omit to leave the existing entries
            untouched, or pass an empty array to remove them all.
          items:
            $ref: '#/components/schemas/DoNotTranslateEntryWrite'
          title: Do Not Translate Terms
          type: array
        forced_translations:
          default: null
          description: >-
            Replacement Force Translate list across all languages. Preserve
            every entry's target_language when editing. Omit to leave the
            existing entries untouched, or pass an empty array to remove them
            all. Don't Translate takes precedence for overlapping terms without
            deleting their Force Translate rules.
          items:
            $ref: '#/components/schemas/ForcedTranslationEntryWrite'
          title: Forced Translations
          type: array
      title: UpdateBrandGlossaryRequest
      type: object
      x-mcp-exclude-unset: true
      x-mcp-omit-invalid-nulls: true
    BrandGlossaryDetail:
      description: >-
        A single brand glossary with its full term list (GET
        /v3/brand-glossaries/{id}).
      properties:
        brand_glossary_id:
          description: >-
            Unique brand glossary ID. Pass it as `brand_glossary_id` when
            creating a video or translation to apply this glossary.
          title: Brand Glossary Id
          type: string
        name:
          description: Display name of the brand glossary.
          title: Name
          type: string
        created_at:
          description: Creation timestamp (UTC).
          format: date-time
          title: Created At
          type: string
        updated_at:
          description: Last update timestamp (UTC).
          format: date-time
          title: Updated At
          type: string
        terms:
          description: >-
            Every term mapping in this glossary. Empty when the glossary has no
            terms yet, in which case applying it has no effect.
          items:
            $ref: '#/components/schemas/BrandGlossaryTerm'
          title: Terms
          type: array
        do_not_translate_terms:
          default: null
          description: Don't Translate rules in this glossary. Omitted when it has none.
          items:
            $ref: '#/components/schemas/DoNotTranslateEntry'
          title: Do Not Translate Terms
          type: array
        forced_translations:
          default: null
          description: >-
            Force Translate rules in this glossary. Omitted when it has none. If
            a term also appears in `do_not_translate_terms`, Don't Translate
            takes precedence without deleting its Force Translate rules.
          items:
            $ref: '#/components/schemas/ForcedTranslationEntry'
          title: Forced Translations
          type: array
      required:
        - brand_glossary_id
        - name
        - created_at
        - updated_at
        - terms
      title: BrandGlossaryDetail
      type: object
      x-mcp-exclude-unset: true
    StandardAPIError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
          example: invalid_parameter
        message:
          type: string
          description: Human-readable error message
          example: Video not found
        param:
          type:
            - string
            - 'null'
          description: Which request field caused the error
        doc_url:
          type:
            - string
            - 'null'
          description: Link to error documentation
        errors:
          type: array
          description: >-
            Per-item error details for batch/multi-node failures (e.g. graph
            compilation errors by node).
          items:
            $ref: '#/components/schemas/StandardAPIErrorDetail'
        request_id:
          type: string
          description: >-
            Request identifier, also returned in the X-HeyGen-Request-Id
            response header. Include it when contacting support.
          example: 8c4f0b9e1d2a4f6b9e3c7a1d5f2b8e40
      required:
        - code
        - message
    BrandGlossaryTermWrite:
      additionalProperties: false
      anyOf:
        - required:
            - pronunciation
        - properties:
            ipa:
              type: string
          required:
            - ipa
      description: >-
        One glossary entry as accepted on POST / PATCH: a written term and how
        it should be spoken.
      properties:
        term:
          description: >-
            The term as written in a script, matched case-insensitively.
            Surrounding whitespace is removed and the trimmed value must be
            non-empty.
          minLength: 1
          title: Term
          type: string
        pronunciation:
          description: >-
            Respelling handed to the speech synthesizer in place of `term` (for
            example 'hey-jen' for 'HeyGen'). Affects generated audio only —
            captions and subtitles keep the original `term` spelling.
            Surrounding whitespace is removed and the trimmed value must be
            non-empty. May be omitted when IPA is supplied and glossary IPA
            access is enabled; a Respelling fallback is generated before saving.
            Conversion failure leaves the glossary unchanged. Null is not
            accepted.
          minLength: 1
          title: Pronunciation
          type: string
        pronunciation_language:
          default: null
          description: >-
            Language in which this pronunciation applies. Omit or use scope
            'all' for all languages; null is invalid. Use scope 'specific' with
            a base language code such as 'fr', not a locale such as 'fr-FR'. A
            language-specific rule overrides an all-languages rule.
          discriminator:
            mapping:
              all: '#/components/schemas/AllBrandGlossaryLanguages'
              specific: '#/components/schemas/SpecificBrandGlossaryLanguage'
            propertyName: scope
          oneOf:
            - $ref: '#/components/schemas/AllBrandGlossaryLanguages'
            - $ref: '#/components/schemas/SpecificBrandGlossaryLanguage'
          title: Pronunciation Language
        ipa:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          default: null
          description: >-
            IPA pronunciation, for example '/ˈæk.mi/'. Requires glossary IPA
            access. Supply pronunciation, IPA, or both. Null clears IPA when
            pronunciation is provided. Omission preserves saved IPA only when
            Respelling and language are unchanged. New or changed pronunciations
            prefer IPA on supported engines, with Respelling as the fallback.
            Unchanged pronunciations retain their saved internal preference.
          title: Ipa
      required:
        - term
      title: BrandGlossaryTermWrite
      type: object
      x-mcp-omit-invalid-nulls: true
    DoNotTranslateEntryWrite:
      additionalProperties: false
      description: One Don't Translate rule as accepted on POST / PATCH bodies.
      properties:
        term:
          description: >-
            A term to keep untranslated. When this glossary is used by a
            translation feature, each occurrence of the term — matched
            case-insensitively — is kept untranslated in every target language.
            Surrounding whitespace is removed and the trimmed value must be
            non-empty.
          minLength: 1
          title: Term
          type: string
      required:
        - term
      title: DoNotTranslateEntryWrite
      type: object
    ForcedTranslationEntryWrite:
      additionalProperties: false
      description: One Force Translate rule as accepted on POST / PATCH bodies.
      properties:
        term:
          description: >-
            The term to replace, matched in the source text case-insensitively.
            Surrounding whitespace is removed and the trimmed value must be
            non-empty.
          minLength: 1
          title: Term
          type: string
        translation:
          description: >-
            The exact text used in place of `term` in the translated output for
            the selected target language scope. Inserted verbatim: grammatical
            inflection (case, gender, number) is not adapted to the surrounding
            sentence. Surrounding whitespace is removed and the trimmed value
            must be non-empty.
          minLength: 1
          title: Translation
          type: string
        target_language:
          default: null
          description: >-
            Target language in which this translation applies. Omit or use scope
            'all' for all languages; null is invalid. Use scope 'specific' with
            a base language code such as 'fr', not a locale such as 'fr-FR'. A
            language-specific rule overrides an all-languages rule. Responses
            omit this field for all-languages rules.
          discriminator:
            mapping:
              all: '#/components/schemas/AllBrandGlossaryLanguages'
              specific: '#/components/schemas/SpecificBrandGlossaryLanguage'
            propertyName: scope
          oneOf:
            - $ref: '#/components/schemas/AllBrandGlossaryLanguages'
            - $ref: '#/components/schemas/SpecificBrandGlossaryLanguage'
          title: Target Language
      required:
        - term
        - translation
      title: ForcedTranslationEntryWrite
      type: object
      x-mcp-omit-invalid-nulls: true
    BrandGlossaryTerm:
      description: 'One glossary entry: a written term and how it should be spoken.'
      properties:
        term:
          description: The term as written in a script, matched case-insensitively.
          title: Term
          type: string
        pronunciation:
          description: >-
            Respelling handed to the speech synthesizer in place of `term` (for
            example 'hey-jen' for 'HeyGen'). Affects generated audio only —
            captions and subtitles keep the original `term` spelling.
          title: Pronunciation
          type: string
        pronunciation_language:
          default: null
          description: >-
            Language in which this pronunciation applies. Omit or use scope
            'all' for all languages; null is invalid. Use scope 'specific' with
            a base language code such as 'fr', not a locale such as 'fr-FR'. A
            language-specific rule overrides an all-languages rule. Responses
            omit this field for all-languages rules.
          discriminator:
            mapping:
              all: '#/components/schemas/AllBrandGlossaryLanguages'
              specific: '#/components/schemas/SpecificBrandGlossaryLanguage'
            propertyName: scope
          oneOf:
            - $ref: '#/components/schemas/AllBrandGlossaryLanguages'
            - $ref: '#/components/schemas/SpecificBrandGlossaryLanguage'
          title: Pronunciation Language
        ipa:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Stored IPA pronunciation. Returned only when glossary IPA access is
            enabled.
          title: Ipa
      required:
        - term
        - pronunciation
      title: BrandGlossaryTerm
      type: object
    DoNotTranslateEntry:
      description: >-
        One Don't Translate rule: a term kept untranslated when content is
        translated.
      properties:
        term:
          description: >-
            A term to keep untranslated. When this glossary is used by a
            translation feature, each occurrence of the term — matched
            case-insensitively — is kept untranslated in every target language.
          title: Term
          type: string
      required:
        - term
      title: DoNotTranslateEntry
      type: object
    ForcedTranslationEntry:
      description: >-
        One Force Translate rule: a term and the exact translation that replaces
        it.
      properties:
        term:
          description: The term to replace, matched in the source text case-insensitively.
          title: Term
          type: string
        translation:
          description: >-
            The exact text used in place of `term` in the translated output for
            the selected target language scope. Inserted verbatim: grammatical
            inflection (case, gender, number) is not adapted to the surrounding
            sentence.
          title: Translation
          type: string
        target_language:
          default: null
          description: >-
            Target language in which this translation applies. Omit or use scope
            'all' for all languages; null is invalid. Use scope 'specific' with
            a base language code such as 'fr', not a locale such as 'fr-FR'. A
            language-specific rule overrides an all-languages rule. Responses
            omit this field for all-languages rules.
          discriminator:
            mapping:
              all: '#/components/schemas/AllBrandGlossaryLanguages'
              specific: '#/components/schemas/SpecificBrandGlossaryLanguage'
            propertyName: scope
          oneOf:
            - $ref: '#/components/schemas/AllBrandGlossaryLanguages'
            - $ref: '#/components/schemas/SpecificBrandGlossaryLanguage'
          title: Target Language
      required:
        - term
        - translation
      title: ForcedTranslationEntry
      type: object
    StandardAPIErrorDetail:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
          example: unknown_node_type
        message:
          type: string
          description: Human-readable error message
          example: Unknown node type
        node_id:
          type: string
          description: Graph node id this error pertains to, if applicable
        port:
          type: string
          description: Port name on the node this error pertains to, if applicable
        path:
          type: string
          description: Field path within the item this error pertains to, if applicable
      required:
        - code
        - message
    AllBrandGlossaryLanguages:
      additionalProperties: false
      description: Apply the rule in every language.
      properties:
        scope:
          const: all
          description: Apply this rule in every language.
          title: Scope
          type: string
      required:
        - scope
      title: AllBrandGlossaryLanguages
      type: object
    SpecificBrandGlossaryLanguage:
      additionalProperties: false
      description: Apply the rule in one language.
      properties:
        scope:
          const: specific
          description: Apply this rule only in the specified language.
          title: Scope
          type: string
        code:
          description: >-
            Language code, such as 'en' or 'fr'. Locale codes such as 'en-US'
            are not accepted.
          maxLength: 32
          title: Code
          type: string
      required:
        - scope
        - code
      title: SpecificBrandGlossaryLanguage
      type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: HeyGen API key. Obtain from your HeyGen dashboard.
    BearerAuth:
      type: http
      scheme: bearer
      description: OAuth2 bearer token.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.