DeepL

DeepL Manage Spoken Terms API

The *Spoken Terms* functions allow you to create, inspect, edit and delete Spoken Terms collections. Spoken Terms improve speech recognition in the Voice API: they ensure specific words and phrases, such as company names, acronyms, and product names, are transcribed correctly. A collection contains one or more term lists, each holding terms for a single language, and is applied to a voice session via the `spoken_terms_id` parameter.

Documentation GitHub OpenAPI

Operations 8

POST /v3/spoken-terms Create Spoken Terms collection #

GET /v3/spoken-terms List all Spoken Terms collections #

GET /v3/spoken-terms/{spoken_terms_id} Retrieve Spoken Terms collection details #

PATCH /v3/spoken-terms/{spoken_terms_id} Edit Spoken Terms collection details #

DELETE /v3/spoken-terms/{spoken_terms_id} Delete Spoken Terms collection #

GET /v3/spoken-terms/{spoken_terms_id}/entries Retrieve Spoken Terms entries #

PUT /v3/spoken-terms/{spoken_terms_id}/term-lists Replace or create a term list #

DELETE /v3/spoken-terms/{spoken_terms_id}/term-lists Delete a term list #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/deepl:deepl-managespokenterms-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: DeepL API Documentation Manage Spoken Terms API
  description: 'The DeepL API provides programmatic access to DeepL’s language AI technology.


    Note: this OpenAPI spec is embedded into our API documentation and has shortened descriptions.'
  termsOfService: https://www.deepl.com/pro-license
  contact:
    name: DeepL - Contact us
    url: https://www.deepl.com/contact-us
  version: 3.13.0
servers:
- url: https://api.deepl.com
  description: DeepL API Pro
- url: https://api-free.deepl.com
  description: DeepL API Free
tags:
- name: ManageSpokenTerms
  description: 'The *Spoken Terms* functions allow you to create, inspect, edit and delete Spoken Terms collections.

    Spoken Terms improve speech recognition in the Voice API: they ensure specific words and phrases,

    such as company names, acronyms, and product names, are transcribed correctly. A collection contains

    one or more term lists, each holding terms for a single language, and is applied to a voice session

    via the `spoken_terms_id` parameter.'
paths:
  /v3/spoken-terms:
    post:
      tags:
      - ManageSpokenTerms
      summary: Create Spoken Terms collection
      operationId: createSpokenTerms
      description: Create a new Spoken Terms collection with one or more term lists. Each term list contains terms for a single language. The number of collections per account is limited by your plan.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSpokenTermsParameters'
            examples:
              Basic:
                value:
                  name: Technical Terms
                  term_lists:
                  - lang: en
                    entries: 'DeepL

                      API

                      webhook'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateSpokenTermsParameters'
      responses:
        '201':
          description: Successfully created Spoken Terms collection.
          headers:
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpokenTerms'
        '400':
          $ref: '#/components/responses/BadRequestSpokenTerms'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenSpokenTerms'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '456':
          $ref: '#/components/responses/QuotaExceededSpokenTerms'
      security:
      - auth_header: []
    get:
      tags:
      - ManageSpokenTerms
      summary: List all Spoken Terms collections
      operationId: listSpokenTerms
      description: List all Spoken Terms collections and their metadata, but not the actual terms.
      responses:
        '200':
          description: JSON object containing all Spoken Terms collections.
          headers:
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
          content:
            application/json:
              schema:
                type: object
                properties:
                  spoken_terms:
                    type: array
                    items:
                      $ref: '#/components/schemas/SpokenTerms'
              example:
                spoken_terms:
                - spoken_terms_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
                  name: Technical Terms
                  term_lists:
                  - lang: en
                    entry_count: 3
                  creation_time: '2025-08-03T14:16:18.329Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenSpokenTerms'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v3/spoken-terms/{spoken_terms_id}:
    get:
      tags:
      - ManageSpokenTerms
      summary: Retrieve Spoken Terms collection details
      description: Retrieve metadata for a Spoken Terms collection, including term list information but not the actual terms.
      operationId: getSpokenTerms
      parameters:
      - $ref: '#/components/parameters/SpokenTermsID'
      responses:
        '200':
          description: JSON object containing the Spoken Terms metadata.
          headers:
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpokenTerms'
              example:
                spoken_terms_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
                name: Technical Terms
                term_lists:
                - lang: en
                  entry_count: 3
                creation_time: '2025-08-03T14:16:18.329Z'
        '400':
          $ref: '#/components/responses/BadRequestSpokenTerms'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenSpokenTerms'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
    patch:
      tags:
      - ManageSpokenTerms
      summary: Edit Spoken Terms collection details
      description: Update the name of a Spoken Terms collection or merge new entries into an existing term list.
      operationId: patchSpokenTerms
      parameters:
      - $ref: '#/components/parameters/SpokenTermsID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchSpokenTermsParameters'
            examples:
              UpdateName:
                value:
                  name: Updated Technical Terms
              MergeEntries:
                value:
                  term_lists:
                  - lang: en
                    entries: 'authentication

                      endpoint'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchSpokenTermsParameters'
      responses:
        '200':
          description: Successfully updated Spoken Terms collection.
          headers:
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpokenTerms'
        '400':
          $ref: '#/components/responses/BadRequestSpokenTerms'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenSpokenTerms'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
    delete:
      tags:
      - ManageSpokenTerms
      summary: Delete Spoken Terms collection
      description: Delete the entire Spoken Terms collection.
      operationId: deleteSpokenTerms
      parameters:
      - $ref: '#/components/parameters/SpokenTermsID'
      responses:
        '204':
          description: Successfully deleted Spoken Terms collection.
        '400':
          $ref: '#/components/responses/BadRequestSpokenTerms'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenSpokenTerms'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v3/spoken-terms/{spoken_terms_id}/entries:
    get:
      tags:
      - ManageSpokenTerms
      summary: Retrieve Spoken Terms entries
      description: Retrieve the actual terms for a specific language from a Spoken Terms collection.
      operationId: getSpokenTermsEntries
      parameters:
      - $ref: '#/components/parameters/SpokenTermsID'
      - name: lang
        in: query
        required: true
        description: The language code (ISO 639-1) for the term list to retrieve.
        schema:
          type: string
          example: en
      responses:
        '200':
          description: JSON object containing the term list entries.
          headers:
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpokenTermsEntries'
              example:
                lang: en
                entries: 'DeepL

                  API

                  webhook'
        '400':
          $ref: '#/components/responses/BadRequestSpokenTerms'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenSpokenTerms'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
  /v3/spoken-terms/{spoken_terms_id}/term-lists:
    put:
      tags:
      - ManageSpokenTerms
      summary: Replace or create a term list
      description: Replace an existing term list for a language, or create a new one if it doesn't exist.
      operationId: putSpokenTermsList
      parameters:
      - $ref: '#/components/parameters/SpokenTermsID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutSpokenTermsListParameters'
            examples:
              Basic:
                value:
                  lang: en
                  entries: 'DeepL

                    API

                    webhook

                    integration'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PutSpokenTermsListParameters'
      responses:
        '200':
          description: Successfully replaced or created term list.
          headers:
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpokenTermsList'
        '400':
          $ref: '#/components/responses/BadRequestSpokenTerms'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenSpokenTerms'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
    delete:
      tags:
      - ManageSpokenTerms
      summary: Delete a term list
      description: Delete a term list for a specific language from the Spoken Terms collection.
      operationId: deleteSpokenTermsList
      parameters:
      - $ref: '#/components/parameters/SpokenTermsID'
      - name: lang
        in: query
        required: true
        description: The language code (ISO 639-1) for the term list to delete.
        schema:
          type: string
          example: en
      responses:
        '204':
          description: Successfully deleted term list.
        '400':
          $ref: '#/components/responses/BadRequestSpokenTerms'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenSpokenTerms'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - auth_header: []
components:
  parameters:
    SpokenTermsID:
      name: spoken_terms_id
      description: A unique ID assigned to the Spoken Terms collection.
      in: path
      required: true
      schema:
        type: string
  schemas:
    SpokenTermsListInput:
      type: object
      required:
      - lang
      - entries
      properties:
        lang:
          description: Language code (ISO 639-1) for this term list.
          type: string
          example: en
        entries:
          description: 'Newline-separated list of terms, one term per line. Maximum 300 characters total.


            Terms are case-sensitive. Each term must be non-empty, must not contain C0 or C1 control characters (such as tabs or newlines within a term), and must not have leading or trailing whitespace. Duplicate terms within a list are not allowed (comparison is case-sensitive).

            '
          type: string
          maxLength: 300
          example: 'DeepL

            API

            webhook'
    ErrorResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: A human-readable description of the error.
        code:
          type: string
          description: A machine-readable identifier for the error, when available. Clients should match on this value rather than on `message` when branching on error types.
          example: invalid_content_type
    SpokenTermsList:
      type: object
      properties:
        lang:
          description: Language code (ISO 639-1).
          type: string
          example: en
        entry_count:
          description: Number of terms in this list.
          type: integer
          example: 3
    PutSpokenTermsListParameters:
      type: object
      required:
      - lang
      - entries
      properties:
        lang:
          description: Language code (ISO 639-1) for this term list.
          type: string
          example: en
        entries:
          description: 'Newline-separated list of terms, one term per line. Maximum 300 characters total.


            Terms are case-sensitive. Each term must be non-empty, must not contain C0 or C1 control characters (such as tabs or newlines within a term), and must not have leading or trailing whitespace. Duplicate terms within a list are not allowed (comparison is case-sensitive).

            '
          type: string
          maxLength: 300
          example: 'DeepL

            API

            webhook

            integration'
    SpokenTerms:
      type: object
      properties:
        spoken_terms_id:
          description: A unique ID assigned to the Spoken Terms collection.
          type: string
          example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
        name:
          description: Name of the Spoken Terms collection.
          type: string
          example: Technical Terms
        term_lists:
          description: List of term lists contained in this collection.
          type: array
          items:
            $ref: '#/components/schemas/SpokenTermsList'
        creation_time:
          description: 'The creation time of the Spoken Terms collection in ISO 8601-1:2019 format (e.g.: `2025-08-03T14:16:18.329Z`).'
          type: string
          format: date-time
          example: '2025-08-03T14:16:18.329Z'
    PatchSpokenTermsParameters:
      type: object
      properties:
        name:
          description: New name for the Spoken Terms collection.
          type: string
          maxLength: 1024
          example: Updated Technical Terms
        term_lists:
          description: Term lists to merge with existing lists.
          type: array
          items:
            $ref: '#/components/schemas/SpokenTermsListInput'
    SpokenTermsEntries:
      type: object
      properties:
        lang:
          description: Language code (ISO 639-1).
          type: string
          example: en
        entries:
          description: Newline-separated list of terms.
          type: string
          example: 'DeepL

            API

            webhook'
    CreateSpokenTermsParameters:
      type: object
      required:
      - name
      - term_lists
      properties:
        name:
          description: Name for the Spoken Terms collection.
          type: string
          maxLength: 1024
          example: Technical Terms
        term_lists:
          description: Array of term lists, one per language.
          type: array
          items:
            $ref: '#/components/schemas/SpokenTermsListInput'
  responses:
    NotFound:
      description: The requested resource could not be found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: Too many requests. Please wait and resend your request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequestSpokenTerms:
      description: Bad request. Please check error message and your parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Bad request
    PayloadTooLarge:
      description: The request size exceeds the limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnsupportedMediaType:
      description: Unsupported Media Type. Must be application/json or application/x-www-form-urlencoded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Unsupported Content-Type
    QuotaExceededSpokenTerms:
      description: Quota exceeded. Spoken Terms collection limit reached for your plan.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Spoken Terms quota exhausted
    ForbiddenSpokenTerms:
      description: Forbidden. Authorization failed or feature not available for your plan.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Forbidden. Authorization failed or feature not available for your plan.
    Unauthorized:
      description: Authorization failed. Please supply a valid `DeepL-Auth-Key` via the `Authorization` header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  headers:
    X-Trace-ID:
      description: A unique identifier for the request that can be included in bug reports to DeepL support.
      schema:
        type: string
      example: 501c3d93cc0c4f11ae2f60a226c2f0f0
  securitySchemes:
    auth_header:
      type: apiKey
      description: 'Authentication with `Authorization` header and `DeepL-Auth-Key` authentication scheme. Example: `DeepL-Auth-Key <api-key>`

        '
      name: Authorization
      in: header
      x-default: 'DeepL-Auth-Key '
externalDocs:
  description: DeepL Pro - Plans and pricing
  url: https://www.deepl.com/pro#developer
x-hideTryItPanel: true
x-codeSamples: false
x-provenance:
  method: harvested
  publisher: DeepL
  source: https://developers.deepl.com/api-reference/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)

DeepL Manage Spoken Terms API

Operations 8

Documentation

Specifications

Schemas & Data

Other Resources