Wistia Data API 2026-01

openapi: 3.1.1
info:
  title: Data API
  description: Wistia Data API
  version: 2026.01.0
servers:
  - url: https://api.wistia.com/modern
tags:
  - name: Media
    x-displayName: Media
  - name: Customizations
    x-displayName: Customizations
  - name: Captions
    x-displayName: Captions
  - name: Localizations
    x-wistia-mcp-toolsets: captions
    x-displayName: Localizations
  - name: Trims
    x-wistia-mcp-toolsets: media
    x-displayName: Trims
  - name: Tags
    x-displayName: Tags
  - name: Taggings
    x-wistia-mcp-toolsets: tags
    x-displayName: Taggings
  - name: Folders
    x-displayName: Folders
  - name: Folder Sharings
    x-wistia-mcp-toolsets: folders
    x-displayName: Folder Sharings
  - name: Subfolders
    x-wistia-mcp-toolsets: folders
    x-displayName: Subfolders
  - name: Channels
    x-displayName: Channels
  - name: Channel Episodes
    x-wistia-mcp-toolsets: channels
    x-displayName: Channel Episodes
  - name: Webinars
    x-displayName: Webinars
  - name: Webinar Registrations
    x-wistia-mcp-toolsets: webinars
    x-displayName: Webinar Registrations
  - name: Account
    x-displayName: Account
  - name: Search
    x-wistia-mcp-toolsets:
      - media
      - folders
      - channels
    x-displayName: Search
  - name: Expiring Access Tokens
    x-wistia-mcp-toolsets: sharing
    x-displayName: Expiring Access Tokens
  - name: Background Job Status
    x-wistia-mcp-toolsets: account
    x-displayName: Background Job Status
  - name: Allowed Domains
    x-wistia-mcp-toolsets: sharing
    x-displayName: Allowed Domains
  - name: Stats:Account
    x-wistia-mcp-toolsets: stats
    x-displayName: Stats:Account
  - name: Stats:Projects
    x-wistia-mcp-toolsets: stats
    x-displayName: Stats:Projects
  - name: Stats:Media
    x-wistia-mcp-toolsets: stats
    x-displayName: Stats:Media
  - name: Stats:Visitors
    x-wistia-mcp-toolsets: stats
    x-displayName: Stats:Visitors
  - name: Stats:Events
    x-wistia-mcp-toolsets: stats
    x-displayName: Stats:Events
paths:
  /medias:
    get:
      summary: List Media
      description: >
        Lists the media belonging to the account. This endpoint can also be used
        to

        do a batch fetch based off of the hashed id.


        <!--- HIDE-MCP -->

        ## Requires api token with one of the following permissions

        ```

        Read all folder and media data

        ```

        <!--- /HIDE-MCP -->
      parameters:
        - 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` and `created` are supported. All other sort_by options
            (`name`, `updated`, `position`)

            require offset pagination.
          required: false
          schema:
            type: string
            enum:
              - name
              - created
              - updated
              - position
        - name: sort_direction
          in: query
          description: Ordering Sort Direction (0 = desc, 1 = asc; default is 1)
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
        - name: folder_id
          in: query
          description: >-
            A hashed ID specifying the folder from which you would like to get
            results.
          required: false
          schema:
            description: Hashed ID of the folder (e.g., "4d23503f70")
            type: string
        - name: name
          in: query
          description: Find a media or medias whose name exactly matches this parameter.
          required: false
          schema:
            type: string
        - name: description_format
          in: query
          description: Format for media descriptions
          required: false
          schema:
            type: string
            examples:
              - markdown
            const: markdown
        - name: type
          in: query
          description: A string specifying which type of media you would like to get.
          required: false
          schema:
            type: string
            enum:
              - Video
              - Audio
              - Image
              - PdfDocument
              - MicrosoftOfficeDocument
              - Swf
              - UnknownType
        - name: hashed_ids[]
          in: query
          description: Find all of the medias by these hashed_ids.
          required: false
          schema:
            type: array
            items:
              type: string
          explode: true
          style: form
        - name: tags[]
          in: query
          description: Find all of the medias that match all of these tag names.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: archived
          in: query
          description: >-
            Filter by archived status. True will return only archived medias,
            while false will return only active medias.
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  unevaluatedProperties: false
                  allOf:
                    - type: object
                      description: >
                        A media generally represents a video or an audio which
                        can be embedded into your website.


                        CDN-backed medias are accessible using this url
                        structure:
                        https://fast.wistia.com/embed/medias/{hashed_id}.m3u8.

                        For more information, see
                        https://docs.wistia.com/docs/asset-urls#getting-hls-assets.
                      properties:
                        protected:
                          description: >-
                            Whether the media is protected (e.g. requires a
                            password or other authentication to view). Null if
                            the media is not protected.
                          type:
                            - boolean
                            - 'null'
                        id:
                          description: >-
                            A unique numeric identifier for the media within the
                            system.
                          type: integer
                        name:
                          description: The display name of the media.
                          type: string
                        type:
                          description: A string representing what type of media this is.
                          type: string
                          enum:
                            - Video
                            - Audio
                            - Image
                            - PdfDocument
                            - MicrosoftOfficeDocument
                            - Swf
                            - UnknownType
                        archived:
                          description: >-
                            Whether or not the media is archived, either true or
                            false.
                          type: boolean
                        created:
                          description: The date when the media was originally uploaded.
                          type: string
                          format: date-time
                        updated:
                          description: The date when the media was last changed.
                          type: string
                          format: date-time
                        duration:
                          unevaluatedProperties: false
                          description: >-
                            Specifies the length (in seconds) for audio and
                            video files. Specifies number of pages in the
                            document. Omitted for other types of media.
                          oneOf:
                            - type: number
                            - type: 'null'
                        embedCode:
                          description: >
                            DEPRECATED: If you want to programmatically embed
                            videos, follow the construct an embed code guide.
                          type: string
                          deprecated: true
                        hashed_id:
                          description: A unique alphanumeric identifier for this media.
                          type: string
                        description:
                          description: >-
                            A description for the media which usually appears
                            near the top of the sidebar on the media's page.
                          type: string
                        progress:
                          description: >-
                            A floating point value between 0 and 1 that
                            indicates the progress of the processing for this
                            file.
                          type: number
                          maximum: 1
                          minimum: 0
                        status:
                          description: >
                            Post upload processing status. - `queued`: the file
                            is waiting in the queue to be processed. -
                            `processing`: the file is actively being processed.
                            - `ready`: the file has been fully processed and is
                            ready for embedding and viewing. - `failed`: the
                            file was unable to be processed (usually a format or
                            size error).
                          type: string
                          enum:
                            - queued
                            - processing
                            - ready
                            - failed
                        section:
                          unevaluatedProperties: false
                          description: >-
                            The title of the section in which the media appears.
                            This attribute is omitted if the media is not in a
                            section (default).
                          oneOf:
                            - type: string
                            - type: 'null'
                        thumbnail:
                          unevaluatedProperties: false
                          type: object
                          properties:
                            url:
                              type: string
                            width:
                              type: integer
                            height:
                              type: integer
                    - type: object
                      properties:
                        folder:
                          unevaluatedProperties: false
                          oneOf:
                            - unevaluatedProperties: false
                              type: object
                              properties:
                                id:
                                  description: >-
                                    A unique numeric identifier for the folder
                                    within the system.
                                  type: integer
                                  examples:
                                    - 22570
                                name:
                                  description: The folder’s display name.
                                  type: string
                                  examples:
                                    - My Folder Title
                                hashed_id:
                                  description: >-
                                    A private hashed id, uniquely identifying
                                    the folder within the system.
                                  type: string
                                  examples:
                                    - 4d23503f70
                            - type: 'null'
                      required:
                        - folder
                    - type: object
                      properties:
                        assets:
                          description: An array of the assets available for this media.
                          type: array
                          items:
                            unevaluatedProperties: false
                            type: object
                            properties:
                              url:
                                description: >-
                                  A direct-access URL to the content of the
                                  asset.
                                type: string
                              width:
                                unevaluatedProperties: false
                                description: >-
                                  The width of this specific asset, if
                                  applicable.
                                oneOf:
                                  - type: integer
                                  - type: 'null'
                              height:
                                unevaluatedProperties: false
                                description: >-
                                  The height of this specific asset, if
                                  applicable.
                                oneOf:
                                  - type: integer
                                  - type: 'null'
                              file_size:
                                unevaluatedProperties: false
                                description: >-
                                  The size of the asset file that’s referenced
                                  by url, measured in bytes.
                                oneOf:
                                  - type: integer
                                  - type: 'null'
                              content_type:
                                unevaluatedProperties: false
                                description: The asset’s content type.
                                oneOf:
                                  - type: string
                                  - type: 'null'
                              type:
                                description: >
                                  The internal type of the asset, describing how
                                  the asset should be used. Values can include
                                  OriginalFile, FlashVideoFile,
                                  MdFlashVideoFile, HdFlashVideoFile,
                                  Mp4VideoFile, MdMp4VideoFile, HdMp4VideoFile,
                                  IPhoneVideoFile, StillImageFile, SwfFile,
                                  Mp3AudioFile, and LargeImageFile.
                                type: string
                    - type: object
                      properties:
                        subfolder:
                          unevaluatedProperties: false
                          description: >-
                            The subfolder (media group) in which the media
                            appears. Null if the media is not in a subfolder.
                          allOf:
                            - type: object
                              description: A subfolder within a folder that contains media.
                              properties:
                                hashed_id:
                                  description: >-
                                    A unique alphanumeric identifier for this
                                    subfolder.
                                  type: string
                                  examples:
                                    - abc123def4
                                name:
                                  description: The display name of the subfolder.
                                  type:
                                    - string
                                    - 'null'
                                  examples:
                                    - Marketing Videos
                                description:
                                  description: A description for the subfolder.
                                  type:
                                    - string
                                    - 'null'
                                  examples:
                                    - >-
                                      Collection of all marketing and
                                      promotional videos
                                position:
                                  description: >-
                                    The position of this subfolder within its
                                    folder, used for ordering.
                                  type:
                                    - integer
                                    - 'null'
                                  examples:
                                    - 1
                                created:
                                  description: The date when the subfolder was created.
                                  type:
                                    - string
                                    - 'null'
                                  format: date-time
                                  examples:
                                    - '2024-01-15T10:30:00+00:00'
                                updated:
                                  description: >-
                                    The date when the subfolder was last
                                    modified.
                                  type:
                                    - string
                                    - 'null'
                                  format: date-time
                                  examples:
                                    - '2024-01-20T14:45:00+00:00'
                                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:
                                - hashed_id
                                - position
                                - created
                                - updated
                    - type: object
                      properties:
                        tags:
                          description: Tags associated with this media.
                          type: array
                          items:
                            unevaluatedProperties: false
                            type: object
                            properties:
                              name:
                                description: The display name of the tag.
                                type: string
                    - type: object
                      properties:
                        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'
        '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.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                type: object
                properties:
                  error:
                    type: string
                    examples:
                      - Internal server error
      tags:
        - Media
      security:
        - BearerAuth: []
  /medias/{mediaHashedId}:
    get:
      summary: Show Media
      description: |
        Fetches a single media by its hashed id.

        <!--- 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.
          required: true
          schema:
            description: Hashed ID of the media (e.g., "4d23503f70")
            type: string
        - name: description_format
          in: query
          description: Format for media descriptions
          required: false
          schema:
            type: string
            examples:
              - markdown
            const: markdown
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                unevaluatedProperties: false
                allOf:
                  - type: object
                    description: >
                      A media generally represents a video or an audio which can
                      be embedded into your website.


                      CDN-backed medias are accessible using this url structure:
                      https://fast.wistia.com/embed/medias/{hashed_id}.m3u8.

                      For more information, see
                      https://docs.wistia.com/docs/asset-urls#getting-hls-assets.
                    properties:
                      protected:
                        description: >-
                          Whether the media is protected (e.g. requires a
                          password or other authentication to view). Null if the
                          media is not protected.
                        type:
                          - boolean
                          - 'null'
                      id:
                        description: >-
                          A unique numeric identifier for the media within the
                          system.
                        type: integer
                      name:
                        description: The display name of the media.
                        type: string
                      type:
                        description: A string representing what type of media this is.
                        type: string
                        enum:
                          - Video
                          - Audio
                          - Image
                          - PdfDocument
                          - MicrosoftOfficeDocument
                          - Swf
                          - UnknownType
                      archived:
                        description: >-
                          Whether or not the media is archived, either true or
                          false.
                        type: boolean
                      created:
                        description: The date when the media was originally uploaded.
                        type: string
                        format: date-time
                      updated:
                        description: The date when the media was last changed.
                        type: string
                        format: date-time
                      duration:
                        unevaluatedProperties: false
                        description: >-
                          Specifies the length (in seconds) for audio and video
                          files. Specifies number of pages in the document.
                          Omitted for other types of media.
                        oneOf:
                          - type: number
                          - type: 'null'
                      embedCode:
                        description: >
                          DEPRECATED: If you want to programmatically embed
                          videos, follow the construct an embed code guide.
                        type: string
                        deprecated: true
                      hashed_id:
                        description: A unique alphanumeric identifier for this media.
                        type: string
                      description:
                        description: >-
                          A description for the media which usually appears near
                          the top of the sidebar on the media's page.
                        type: string
                      progress:
                        description: >-
                          A floating point value between 0 and 1 that indicates
                          the progress of the processing for this file.
                        type: number
                        maximum: 1
                        minimum: 0
                      status:
                        description: >
                          Post upload processing status. - `queued`: the file is
                          waiting in the queue to be processed. - `processing`:
                          the file is actively being processed. - `ready`: the
                          file has been fully processed and is ready for
                          embedding and viewing. - `failed`: the file was unable
                          to be processed (usually a format or size error).
                        type: string
                        enum:
                          - queued
                          - processing
                          - ready
                          - failed
                      section:
                        unevaluatedProperties: false
                        description: >-
                          The title of the section in which the media appears.
                          This attribute is omitted if the media is not in a
                          section (default).
                        oneOf:
                          - type: string
                          - type: 'null'
                      thumbnail:
                        unevaluatedProperties: false
                        type: object
                        properties:
                          url:
                            type: string
                          width:
                            type: integer
                          height:
                            type: integer
                  - type: object
                    properties:
                      folder:
                        unevaluatedProperties: false
                        oneOf:
                          - unevaluatedProperties: false
                            type: object
                            properties:
                              id:
                                description: >-
                                  A unique numeric identifier for the folder
                                  within the system.
                                type: integer
                                examples:
                                  - 22570
                              name:
                                description: The folder’s display name.
                                

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