Wistia Captions API

openapi: 3.2.0
info:
  title: Wistia Captions API
  version: '1.0'
  description: 'Operations tagged Captions across 4 of this provider''s published API definitions: wistia-captions-api-openapi.yml, wistia-data-api-2026-01-openapi.yml, wistia-data-api-modern-edge-openapi.yml, wistia-data-api-v1-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.wistia.com/v1
  description: Wistia Data API production server
- url: https://api.wistia.com/modern
tags:
- name: Captions
paths:
  /medias/{hashedId}/captions:
    parameters:
    - in: path
      name: hashedId
      required: true
      schema:
        type: string
    get:
      tags:
      - Captions
      summary: List captions
      operationId: listCaptions
      responses:
        '200':
          description: OK
      security:
      - bearerAuth: []
      - basicAuth: []
    post:
      tags:
      - Captions
      summary: Create captions
      operationId: createCaptions
      responses:
        '201':
          description: Created
      security:
      - bearerAuth: []
      - basicAuth: []
    servers:
    - url: https://api.wistia.com/v1
      description: Wistia Data API production server
  /medias/{hashedId}/captions/{languageCode}:
    parameters:
    - in: path
      name: hashedId
      required: true
      schema:
        type: string
    - in: path
      name: languageCode
      required: true
      schema:
        type: string
    get:
      tags:
      - Captions
      summary: Show captions
      operationId: getCaption
      responses:
        '200':
          description: OK
      security:
      - bearerAuth: []
      - basicAuth: []
    put:
      tags:
      - Captions
      summary: Update captions
      operationId: updateCaption
      responses:
        '200':
          description: OK
      security:
      - bearerAuth: []
      - basicAuth: []
    delete:
      tags:
      - Captions
      summary: Delete captions
      operationId: deleteCaption
      responses:
        '204':
          description: No Content
      security:
      - bearerAuth: []
      - basicAuth: []
    servers:
    - url: https://api.wistia.com/v1
      description: Wistia Data API production server
  /medias/{hashedId}/captions/purchase:
    parameters:
    - in: path
      name: hashedId
      required: true
      schema:
        type: string
    post:
      tags:
      - Captions
      summary: Purchase captions
      operationId: purchaseCaptions
      responses:
        '200':
          description: OK
      security:
      - bearerAuth: []
      - basicAuth: []
    servers:
    - url: https://api.wistia.com/v1
      description: Wistia Data API production server
  /medias/{mediaHashedId}/captions:
    get:
      summary: List Captions by Media
      description: 'Lists captions belonging to a specific video.


        <!--- HIDE-MCP -->

        ## Requires api token with one of the following permissions

        ```

        Read all folder and media data

        ```

        <!--- /HIDE-MCP -->

        '
      parameters:
      - name: mediaHashedId
        in: path
        description: The hashed ID of the media for which captions are to be retrieved.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Captions retrieval successful
          content:
            application/json:
              schema:
                type: array
                items:
                  unevaluatedProperties: false
                  type: object
                  properties:
                    english_name:
                      description: English name of the language.
                      type: string
                    native_name:
                      description: Native name of the language.
                      type: string
                    language:
                      description: A 3 character language code as specified by ISO-639–2.
                      type: string
                    text:
                      description: The text of the captions for the specified language in SRT format.
                      type:
                      - string
                      - 'null'
                    is_draft:
                      type: boolean
                    id:
                      description: The unique hashed identifier of the time-coded transcript.
                      type: string
                    cursor:
                      description: A cursor for stable pagination based on current `sort_by` order. You can pass this to `cursor[before]` or `cursor[after]` as a parameter to fetch the records before or after this record in the same sort order. This is only populated if records were fetched with `cursor[enabled]`, or `cursor[before]` or `cursor[after]`.
                      type:
                      - string
                      - 'null'
                  required:
                  - language
                  - is_draft
                  - id
        '401':
          description: Unauthorized, invalid or missing token
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                type: object
                properties:
                  code:
                    description: A machine-readable identifier for the specific authorization failure.
                    type: string
                    enum:
                    - unauthorized_credentials
                    - account_inactive
                    - unauthorized_scope
                    - unauthorized_params
                  error:
                    type: string
                    examples:
                    - Invalid credentials.
        '404':
          description: Video not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                type: object
                properties:
                  error:
                    type: string
                    examples:
                    - Internal server error
      tags:
      - Captions
      security:
      - BearerAuth: []
    post:
      summary: Create Captions
      description: 'Adds captions to a specified video by providing an SRT file or its contents directly.


        <!--- HIDE-MCP -->

        ## Requires api token with one of the following permissions

        ```

        Read, update & delete anything

        ```

        <!--- /HIDE-MCP -->

        '
      parameters:
      - name: mediaHashedId
        in: path
        description: The hashed ID of the media for which captions are to be added.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              unevaluatedProperties: false
              type: object
              properties:
                caption_file:
                  description: Either an attached SRT file or a string parameter with the contents of an SRT file.
                  type: string
                language:
                  description: An optional parameter that denotes which language this file represents. Should conform to ISO-639–2. If left unspecified, the language code will be detected automatically.
                  type: string
              required:
              - caption_file
          multipart/form-data:
            schema:
              unevaluatedProperties: false
              type: object
              properties:
                caption_file:
                  description: Either an attached SRT file or a string parameter with the contents of an SRT file.
                  type: string
                  format: binary
                language:
                  description: An optional parameter that denotes which language this file represents. Should conform to ISO-639–2. If left unspecified, the language code will be detected automatically.
                  type: string
              required:
              - caption_file
      responses:
        '200':
          description: Captions added successfully
        '400':
          description: Captions already exist for this video
        '401':
          description: Unauthorized, invalid or missing token
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                type: object
                properties:
                  code:
                    description: A machine-readable identifier for the specific authorization failure.
                    type: string
                    enum:
                    - unauthorized_credentials
                    - account_inactive
                    - unauthorized_scope
                    - unauthorized_params
                  error:
                    type: string
                    examples:
                    - Invalid credentials.
        '404':
          description: Video not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                type: object
                properties:
                  error:
                    type: string
                    examples:
                    - Internal server error
      tags:
      - Captions
      security:
      - BearerAuth: []
    servers:
    - url: https://api.wistia.com/modern
  /captions:
    get:
      summary: List Captions
      description: 'Lists captions belonging to the account. This endpoint can also narrow down results

        to those belonging to a specific video.


        <!--- HIDE-MCP -->

        ## Requires api token with one of the following permissions

        ```

        Read all folder and media data

        ```

        <!--- /HIDE-MCP -->

        '
      parameters:
      - name: media_id
        in: query
        description: Find captions for a particular video by providing the media hashed ID
        required: false
        schema:
          type: string
      - name: page
        in: query
        description: 'The page number to retrieve. This cannot be combined with `cursor`,

          pagination.

          '
        required: false
        schema:
          type: integer
      - name: per_page
        in: query
        description: The number of medias per page. Use this for both offset pagination and cursor pagination.
        required: false
        schema:
          type: integer
      - name: cursor
        in: query
        description: 'If `cursor[enabled]` is set to 1 than cursor pagination is enabled and the

          first set of records are fetched up to the `per_page`. Cursor

          pagination will also be turned on if `cursor[before]` or `cursor[after]`

          are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering.

          The cursor value of the last record can be used to fetch records after the current result set and

          the cursor of the first record can be used to fetch records before the result set.


          NOTE: a cursor value is only valid if the `sort_by` value hasn''t changed from the

          last fetch. For example, you cannot fetch using `sort_by` id and than pass that

          cursor value to a `sort_by` name.

          '
        required: false
        schema:
          unevaluatedProperties: false
          type: object
          properties:
            enabled:
              description: 'If `cursor[enabled]` is set to 1, the first result set will be fetched with cursor pagination enabled. This

                values is ignored if `cursor[before]` or `cursor[after]` are set.

                '
              type: integer
              enum:
              - 0
              - 1
            before:
              description: 'If `cursor[before]` is set than cursor pagination is enabled and all records

                before the cursor up to the `per_page` are returned. This feature is useful for

                fetching "new records", for example, in a "pull to refersh" feature when showing records in a descending

                order.

                '
              type: string
            after:
              description: 'If `cursor[after]` is set than cursor pagination is enabled and all records

                after the cursor up to the `per_page` are returned.

                '
              type: string
        style: deepObject
      - name: sort_by
        in: query
        description: 'Ordering. When using cursor pagination (see cursor param),

          only `id` is supported.

          '
        required: false
        schema:
          type: string
          enum:
          - id
          - created
          default: id
      - name: sort_direction
        in: query
        description: Ordering Sort Direction (0 = desc, 1 = asc; default is 1)
        required: false
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 1
      responses:
        '200':
          description: Captions retrieval successful
          content:
            application/json:
              schema:
                type: array
                items:
                  unevaluatedProperties: false
                  type: object
                  properties:
                    english_name:
                      description: English name of the language.
                      type: string
                    native_name:
                      description: Native name of the language.
                      type: string
                    language:
                      description: A 3 character language code as specified by ISO-639–2.
                      type: string
                    text:
                      description: The text of the captions for the specified language in SRT format.
                      type:
                      - string
                      - 'null'
                    is_draft:
                      type: boolean
                    id:
                      description: The unique hashed identifier of the time-coded transcript.
                      type: string
                    cursor:
                      description: A cursor for stable pagination based on current `sort_by` order. You can pass this to `cursor[before]` or `cursor[after]` as a parameter to fetch the records before or after this record in the same sort order. This is only populated if records were fetched with `cursor[enabled]`, or `cursor[before]` or `cursor[after]`.
                      type:
                      - string
                      - 'null'
                  required:
                  - language
                  - is_draft
                  - id
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                type: object
                properties:
                  error:
                    description: Error message detailing the reason for the bad request.
                    type: string
                    examples:
                    - Bad request
                  errors:
                    description: Array of error messages detailing the reasons for the bad request.
                    type: array
                    items:
                      type: string
        '401':
          description: Unauthorized, invalid or missing token
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                type: object
                properties:
                  code:
                    description: A machine-readable identifier for the specific authorization failure.
                    type: string
                    enum:
                    - unauthorized_credentials
                    - account_inactive
                    - unauthorized_scope
                    - unauthorized_params
                  error:
                    type: string
                    examples:
                    - Invalid credentials.
        '404':
          description: Video not found (when media_id parameter is provided)
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                type: object
                properties:
                  error:
                    type: string
                    examples:
                    - Internal server error
      tags:
      - Captions
      security:
      - BearerAuth: []
    servers:
    - url: https://api.wistia.com/modern
  /medias/{mediaHashedId}/captions/purchase:
    post:
      summary: Purchase Captions
      x-wistia-is-purchase: true
      x-wistia-mcp-annotations:
        open_world_hint: true
        destructive_hint: true
      description: 'This method is for purchasing English captions for a video. The request will charge the credit card on the account if successful. A saved credit card is required to use this endpoint.


        > 🚫 Alert

        >

        > The `automated` parameter defaults to `false`, which orders **paid human-generated captions**. To order computer-generated captions, you must explicitly set `automated` to `true`.


        <!--- HIDE-MCP -->

        ## Requires api token with one of the following permissions

        ```

        Read, update & delete anything

        ```

        <!--- /HIDE-MCP -->

        '
      parameters:
      - name: mediaHashedId
        in: path
        description: Unique identifier for the video.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              unevaluatedProperties: false
              type: object
              properties:
                automated:
                  description: Order computer-generated captions or paid human-generated captions.
                  type: boolean
                  default: false
                rush:
                  description: Enable rush order for one business day turnaround or standard four business day turnaround for human-generated captions. Rush can only be used for human-generated captions.
                  type: boolean
                  default: false
                automatically_enable:
                  description: Automatically enable captions for the video once the order is ready or hold the captions for review before manually enabling.
                  type: boolean
                  default: true
              required:
              - automated
              - rush
              - automatically_enable
      responses:
        '200':
          description: Successful operation. Captions purchased.
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                type: object
                properties:
                  message:
                    description: Success message indicating the captions have been purchased
                    type: string
                    examples:
                    - Captions purchased for this video. Your account will be charged when the captions are ready.
                  id:
                    description: The unique hashed identifier of the time-coded transcript that was created
                    type: string
                    examples:
                    - abc123def456
                required:
                - message
                - id
        '400':
          description: English captions already exist for this video.
        '401':
          description: Unauthorized, invalid or missing token
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                type: object
                properties:
                  code:
                    description: A machine-readable identifier for the specific authorization failure.
                    type: string
                    enum:
                    - unauthorized_credentials
                    - account_inactive
                    - unauthorized_scope
                    - unauthorized_params
                  error:
                    type: string
                    examples:
                    - Invalid credentials.
        '404':
          description: Video not found.
        '422':
          description: Unprocessable entity. Account not eligible, captions already purchased, or other validation error.
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                type: object
                properties:
                  message:
                    description: Error message explaining why the purchase cannot be completed
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                type: object
                properties:
                  error:
                    type: string
                    examples:
                    - Internal server error
      tags:
      - Captions
      security:
      - BearerAuth: []
    servers:
    - url: https://api.wistia.com/modern
  /medias/{mediaHashedId}/captions/{languageCode}:
    get:
      summary: Show Captions
      description: 'Returns a video''s captions in the specified language.

        Supports multiple formats: JSON (default), SRT, VTT, and TXT.

        Use file extensions (.srt, .vtt, .txt) or Accept headers to specify format.


        <!--- HIDE-MCP -->

        ## Requires api token with one of the following permissions

        ```

        Read all folder and media data

        ```

        <!--- /HIDE-MCP -->

        '
      parameters:
      - name: mediaHashedId
        in: path
        description: The hashed ID of the media from which captions are to be retrieved.
        required: true
        schema:
          type: string
      - name: languageCode
        in: path
        description: The 3-character ISO 639-2 language code of the captions to be retrieved (e.g., `eng`, `fra`, `spa`). Some languages use extended IETF subtags (e.g., `zh-Hant`).
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response containing captions in the requested format
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                type: object
                properties:
                  english_name:
                    description: English name of the language.
                    type: string
                  native_name:
                    description: Native name of the language.
                    type: string
                  language:
                    description: A 3 character language code as specified by ISO-639–2.
                    type: string
                  text:
                    description: The text of the captions for the specified language in SRT format.
                    type:
                    - string
                    - 'null'
                  is_draft:
                    type: boolean
                  id:
                    description: The unique hashed identifier of the time-coded transcript.
                    type: string
                  cursor:
                    description: A cursor for stable pagination based on current `sort_by` order. You can pass this to `cursor[before]` or `cursor[after]` as a parameter to fetch the records before or after this record in the same sort order. This is only populated if records were fetched with `cursor[enabled]`, or `cursor[before]` or `cursor[after]`.
                    type:
                    - string
                    - 'null'
                required:
                - language
                - is_draft
                - id
            text/plain:
              schema:
                description: Caption content in SRT or TXT format
                type: string
            text/vtt:
              schema:
                description: Caption content in VTT format
                type: string
        '401':
          description: Unauthorized, invalid or missing token
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                type: object
                properties:
                  code:
                    description: A machine-readable identifier for the specific authorization failure.
                    type: string
                    enum:
                    - unauthorized_credentials
                    - account_inactive
                    - unauthorized_scope
                    - unauthorized_params
                  error:
                    type: string
                    examples:
                    - Invalid credentials.
        '404':
          description: Captions not found or video not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                type: object
                properties:
                  error:
                    type: string
                    examples:
                    - Internal server error
      tags:
      - Captions
      security:
      - BearerAuth: []
    put:
      summary: Update Captions
      description: 'This method is for replacing the captions on a video for the specified language.


        <!--- HIDE-MCP -->

        ## Requires api token with one of the following permissions

        ```

        Read, update & delete anything

        ```

        <!--- /HIDE-MCP -->

        '
      parameters:
      - name: mediaHashedId
        in: path
        description: Unique identifier for the video.
        required: true
        schema:
          type: string
      - name: languageCode
        in: path
        description: Language code conforming to ISO-639-2 for which the captions should be updated.
        required: true
        schema:
          type: string
          pattern: ^[a-z]{3}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              unevaluatedProperties: false
              type: object
              properties:
                caption_file:
                  description: Either an attached SRT file or a string parameter with the contents of an SRT file.
                  type: string
              required:
              - caption_file
          multipart/form-data:
            schema:
              unevaluatedProperties: false
              type: object
              properties:
                caption_file:
                  description: Either an attached SRT file or a string parameter with the contents of an SRT file.
                  type: string
                  format: binary
              required:
              - caption_file
      responses:
        '200':
          description: Successful operation. Captions replaced.
        '401':
          description: Unauthorized, invalid or missing token
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                type: object
                properties:
                  code:
                    description: A machine-readable identifier for the specific authorization failure.
                    type: string
                    enum:
                    - unauthorized_credentials
                    - account_inactive
                    - unauthorized_scope
                    - unauthorized_params
                  error:
                    type: string
                    examples:
                    - Invalid credentials.
        '404':
          description: Captions or video not found.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                type: object
                properties:
                  error:
                    type: string
                    examples:
                    - Internal server error
      tags:
      - Captions
      security:
      - BearerAuth: []
    delete:
      summary: Delete Captions
      description: 'Removes the captions file from a video for the specified language.


        <!--- HIDE-MCP -->

        ## Requires api token with one of the following permissions

        ```

        Read, update & delete anything

        ```

        <!--- /HIDE-MCP -->

        '
      parameters:
      - name: mediaHashedId
        in: path
        description: Unique identifier for the video.
        required: true
        schema:
          type: string
      - name: languageCode
        in: path
        description: Language code conforming to ISO-639-2 for which the captions should be removed.
        required: true
        schema:
          type: string
          pattern: ^[a-z]{3}$
      responses:
        '200':
          description: Successful operation. Captions removed.
        '401':
          description: Unauthorized, invalid or missing token
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                type: object
                properties:
                  code:
                    description: A machine-readable identifier for the specific authorization failure.
                    type: string
                    enum:
                    - unauthorized_credentials
                    - account_inactive
                    - unauthorized_scope
                    - unauthorized_params
                  error:
                    type: string
                    examples:
                    - Invalid credentials.
        '404':
          description: Captions or video not found.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                type: object
                properties:
                  error:
                    type: string
                    examples:
                    - Internal server error
      tags:
      - Captions
      security:
      - BearerAuth: []
    servers:
    - url: https://api.wistia.com/modern
  /medias/{mediaHashedId}/captions/{languageCode}/edits:
    post:
      summary: Edit Captions Text
      x-wistia-mcp-annotations:
        read_only_hint: false
        read_only_hint_justification: This tool rewrites transcript text and saves a new caption version, so it modifies data.
        open_world_hint: false
        open_world_hint_justification: This tool only operates on records inside the account and does not reach external services.
        destructive_hint: true
        destructive_hint_justification: Edits replace or delete existing transcript text; the public API has no undo, so previous wording cannot be recovered through it.
        idempotent_hint: false
        idempotent_hint_justification: Each call is checked against a specific caption version and advances it, so re-sending the same request against the new version no longer matches and is rejected.
      x-speakeasy-group: captions
      x-speakeasy-name-override: edit
      description: 'Applies targeted find-and-replace corrections to a media''s transcript for

        the specified language, preserving the timings of unchanged words. The whole

        batch is applied atomically against a specific caption version, or nothing is.


        ## Requires api token with one of the following permissions

        ```

        Read, update & delete anything

        ```

        '
      x-wistia-mcp-tool-name: edit-captions-text
      x-wistia-mcp-description: 'Apply targeted corrections to one caption track while preserving word

        timings. Use this instead of update-captions for small fixes;

        update-captions replaces the entire track.


        First call show-captions-file 

# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wistia/refs/heads/main/openapi/wistia-captions-api-openapi.yml