Wistia Data API

openapi: 3.1.1
info:
  title: Data API
  description: Wistia Data API
  version: 1.0.0
servers:
  - url: https://api.wistia.com/v1
tags:
  - name: Projects
    x-displayName: Projects
  - name: Subfolders
    x-displayName: Subfolders
  - name: Project Sharings
    x-displayName: Project Sharings
  - name: Media
    x-displayName: Media
  - name: Account
    x-displayName: Account
  - name: Allowed Domains
    x-displayName: Allowed Domains
  - name: Background Job Status
    x-displayName: Background Job Status
  - name: Customizations
    x-displayName: Customizations
  - name: Captions
    x-displayName: Captions
  - name: Trims
    x-displayName: Trims
  - name: Localizations
    x-displayName: Localizations
  - name: Tags
    x-displayName: Tags
  - name: Search
    x-displayName: Search
  - name: Channels
    x-displayName: Channels
  - name: Channel Episodes
    x-displayName: Channel Episodes
  - name: Expiring Access Tokens
    x-displayName: Expiring Access Tokens
  - name: Live Stream Events
    x-displayName: Live Stream Events
  - name: Live Stream Event Registrations
    x-displayName: Live Stream Event Registrations
  - name: Stats:Account
    x-displayName: Stats:Account
  - name: Stats:Projects
    x-displayName: Stats:Projects
  - name: Stats:Media
    x-displayName: Stats:Media
  - name: Stats:Visitors
    x-displayName: Stats:Visitors
  - name: Stats:Events
    x-displayName: Stats:Events
paths:
  /projects:
    get:
      summary: Project List
      description: >
        Use this endpoint to request a list of Projects in your Wistia account.
        This request supports paging and sorting.


        ## Requires api token with one of the following permissions

        ```

        Read, update & delete anything

        Read all data

        Read all folder and media data

        ```
      parameters:
        - name: page
          in: query
          description: Page number to retrieve
          required: false
          schema:
            type: integer
        - name: per_page
          in: query
          description: Number of projects per page
          required: false
          schema:
            type: integer
        - name: sort_by
          in: query
          description: Ordering
          required: false
          schema:
            type: string
            enum:
              - name
              - created
              - updated
              - mediaCount
              - 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
        - name: hashed_ids[]
          in: query
          description: A collection of hashed ids belonging to projects to fetch
          required: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: A list of projects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
      tags:
        - Projects
      security:
        - BearerAuth: []
    post:
      summary: Project Create
      description: >
        Create a new project. If the project is created successfully the
        Location HTTP header will point to the new project.


        ## Requires api token with one of the following permissions

        ```

        Read, update & delete anything

        ```
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProject'
      responses:
        '201':
          description: Project created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      tags:
        - Projects
      security:
        - BearerAuth: []
  /projects/{id}:
    get:
      summary: Project Show
      description: >
        Retrieve a single project. Projects#show uses pagination by default -
        we’ll return up to the first 500 medias in a Project. If you have more
        than 500 medias in a Project, you’ll need to add a query param, page=2
        to get the second page of medias (and the third, etc.). You can check
        how many pages you will need by looking at the media_count in your first
        request.


        ## Requires api token with one of the following permissions

        ```

        Read, update & delete anything

        Read all data

        Read all folder and media data

        ```
      parameters:
        - name: id
          in: path
          description: Project Hashed ID
          required: true
          schema:
            description: Hashed ID of the project (e.g., "4d23503f70")
            type: string
      responses:
        '200':
          description: A single project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectWithMedias'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      tags:
        - Projects
      security:
        - BearerAuth: []
    put:
      summary: Project Update
      description: |
        Update a project

        ## Requires api token with one of the following permissions
        ```
        Read, update & delete anything
        ```
      parameters:
        - name: id
          in: path
          description: Project Hashed ID
          required: true
          schema:
            description: Hashed ID of the project (e.g., "4d23503f70")
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProject'
      responses:
        '200':
          description: A single project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      tags:
        - Projects
      security:
        - BearerAuth: []
    delete:
      summary: Project Delete
      description: |
        Delete a project

        ## Requires api token with one of the following permissions
        ```
        Read, update & delete anything
        ```
      parameters:
        - name: id
          in: path
          description: Project Hashed ID
          required: true
          schema:
            description: Hashed ID of the project (e.g., "4d23503f70")
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      tags:
        - Projects
      security:
        - BearerAuth: []
  /projects/{id}/copy:
    post:
      summary: Project Copy
      description: >
        This method does not copy the project’s sharing information (i.e. users
        that could see the old project will not automatically be able to see the
        new one).

        For the request you can specify the owner of a new project by passing an
        optional parameter. The person you specify must be a Manager in the
        account.

        For the response, the HTTP Location header will be set to the URL where
        the new project resource resides. The body of the response will contain
        an object representing the new copy of the project that was just
        created.


        ## Requires api token with one of the following permissions

        ```

        Read, update & delete anything

        ```
      parameters:
        - name: id
          in: path
          description: Project Hashed ID
          required: true
          schema:
            description: Hashed ID of the project (e.g., "4d23503f70")
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                adminEmail:
                  description: >-
                    The email address of the account Manager that will be the
                    owner of the new project. Defaults to the Account Owner if
                    invalid or omitted.
                  type: string
                  examples:
                    - admin@example.com
      responses:
        '201':
          description: Project copied successfully
          headers:
            Location:
              description: The URL where the new project resource resides.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      tags:
        - Projects
      security:
        - BearerAuth: []
  /projects/{projectId}/subfolders:
    get:
      summary: Subfolder List
      description: >
        Use this endpoint to request a list of subfolders in a specific project.
        This request supports paging and sorting.


        ## Requires api token with one of the following permissions

        ```

        Read, update & delete anything

        Read all data

        Read all folder and media data

        ```
      parameters:
        - name: projectId
          in: path
          description: The hashed ID of the project
          required: true
          schema:
            type: string
            examples:
              - abc123def4
        - name: page
          in: query
          description: Page number to retrieve
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: per_page
          in: query
          description: Number of subfolders per page
          required: false
          schema:
            type: integer
            default: 100
            maximum: 100
            minimum: 1
        - name: sort_by
          in: query
          description: Field to sort by
          required: false
          schema:
            type: string
            default: position
            enum:
              - name
              - created
              - updated
              - position
              - id
        - name: sort_direction
          in: query
          description: Sort direction (0 = desc, 1 = asc; default is 1)
          required: false
          schema:
            type: integer
            default: 1
            enum:
              - 0
              - 1
      responses:
        '200':
          description: A list of subfolders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Subfolder'
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    examples:
                      - Project with ID abc123def4 not found.
        '500':
          $ref: '#/components/responses/500'
      tags:
        - Subfolders
      security:
        - BearerAuth: []
    post:
      summary: Create Subfolder
      description: >
        Create a new subfolder within a project. The subfolder will be created
        with the next available position.


        ## Requires api token with one of the following permissions

        ```

        Read, update & delete anything

        ```
      parameters:
        - name: projectId
          in: path
          description: The hashed ID of the project
          required: true
          schema:
            type: string
            examples:
              - abc123def4
      requestBody:
        description: Subfolder data
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubfolderInput'
            example:
              name: Marketing Videos
              description: Collection of all marketing and promotional videos
      responses:
        '201':
          description: Subfolder created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subfolder'
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    examples:
                      - Project with ID abc123def4 not found.
        '500':
          $ref: '#/components/responses/500'
      tags:
        - Subfolders
      security:
        - BearerAuth: []
  /projects/{projectId}/subfolders/{subfolderId}:
    get:
      summary: Show Subfolder
      description: >
        Retrieve detailed information about a specific subfolder, including all
        media files contained within it.


        ## Requires api token with one of the following permissions

        ```

        Read, update & delete anything

        Read all data

        Read all folder and media data

        ```
      parameters:
        - name: projectId
          in: path
          description: The hashed ID of the project
          required: true
          schema:
            type: string
            examples:
              - abc123def4
        - name: subfolderId
          in: path
          description: The hashed ID of the subfolder
          required: true
          schema:
            type: string
            examples:
              - xyz789ghi0
        - name: description_format
          in: query
          description: Format for media descriptions
          required: false
          schema:
            type: string
            examples:
              - markdown
            const: markdown
      responses:
        '200':
          description: Subfolder details with contained media
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubfolderWithMedia'
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: Project or subfolder not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    examples:
                      - Subfolder with ID xyz789ghi0 not found.
        '500':
          $ref: '#/components/responses/500'
      tags:
        - Subfolders
      security:
        - BearerAuth: []
    put:
      summary: Update Subfolder
      description: |
        Update a subfolder's name and/or description. 

        ## Requires api token with one of the following permissions
        ```
        Read, update & delete anything
        ```
      parameters:
        - name: projectId
          in: path
          description: The hashed ID of the project
          required: true
          schema:
            type: string
            examples:
              - abc123def4
        - name: subfolderId
          in: path
          description: The hashed ID of the subfolder
          required: true
          schema:
            type: string
            examples:
              - xyz789ghi0
      requestBody:
        description: Updated subfolder data
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: The new name for the subfolder
                  type: string
                  examples:
                    - Updated Marketing Videos
                  maxLength: 255
                description:
                  description: The new description for the subfolder
                  type:
                    - string
                    - 'null'
                  examples:
                    - Updated collection of marketing materials
                  maxLength: 1000
            example:
              name: Updated Marketing Videos
              description: Updated collection of marketing materials
      responses:
        '200':
          description: Subfolder updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subfolder'
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: Project or subfolder not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    examples:
                      - Subfolder with ID xyz789ghi0 not found.
        '500':
          $ref: '#/components/responses/500'
      tags:
        - Subfolders
      security:
        - BearerAuth: []
    delete:
      summary: Delete Subfolder
      description: >
        Delete a subfolder from a project. All media files in the subfolder will
        be moved to the project's root level.


        The subfolder is soft-deleted and may be recoverable through other
        means, but is no longer accessible via the API.


        ## Requires api token with one of the following permissions

        ```

        Read, update & delete anything

        ```
      parameters:
        - name: projectId
          in: path
          description: The hashed ID of the project
          required: true
          schema:
            type: string
            examples:
              - abc123def4
        - name: subfolderId
          in: path
          description: The hashed ID of the subfolder
          required: true
          schema:
            type: string
            examples:
              - xyz789ghi0
      responses:
        '200':
          description: Subfolder deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subfolder'
              example:
                id: 123
                hashed_id: xyz789ghi0
                name: Marketing Videos
                description: Collection of all marketing and promotional videos
                position: 1
                created: '2024-01-15T10:30:00+00:00'
                updated: '2024-01-20T14:45:00+00:00'
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: Project or subfolder not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    examples:
                      - Subfolder with ID xyz789ghi0 not found.
        '500':
          $ref: '#/components/responses/500'
      tags:
        - Subfolders
      security:
        - BearerAuth: []
  /projects/{projectId}/sharings:
    get:
      summary: Project Sharing List
      description: >
        A sharing is an object that links either a contact or a contact group to
        a project, including information about the contacts' permissions to that
        project.

        Retrieve a list of all sharings for a given project. Supports paging and
        sorting.


        ## Requires api token with one of the following permissions

        ```

        Read, update & delete anything

        Read all data

        ```
      parameters:
        - name: projectId
          in: path
          description: Project Hashed ID
          required: true
          schema:
            description: Hashed ID of the project (e.g., "4d23503f70")
            type: string
        - name: page
          in: query
          description: Page number to retrieve
          required: false
          schema:
            type: integer
        - name: per_page
          in: query
          description: Number of projects per page
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Successfully retrieved list of sharings
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProjectSharingSchema'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
      tags:
        - Project Sharings
      security:
        - BearerAuth: []
    post:
      summary: Project Sharing Create
      description: >
        Create a new sharing object for a project by specifying the email of the
        person to share with and other optional parameters.


        ## Requires api token with one of the following permissions

        ```

        Read, update & delete anything

        ```
      parameters:
        - name: projectId
          in: path
          description: Hashed ID of the project to be shared
          required: true
          schema:
            description: Hashed ID of the project (e.g., "4d23503f70")
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectSharing'
      responses:
        '201':
          description: Project shared successfully
          headers:
            Location:
              description: The API endpoint for the new sharing object.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateProjectSharingResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  description: Error message detailing the reason for the bad request.
                examples:
                  - - email@example.com is already shared on this project.
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
      tags:
        - Project Sharings
      security:
        - BearerAuth: []
  /projects/{projectId}/sharings/{sharingId}:
    get:
      summary: Project Sharing Show
      description: |
        Retrieve the details of a specific sharing object for a given project.

        ## Requires api token with one of the following permissions
        ```
        Read, update & delete anything
        Read all data
        ```
      parameters:
        - name: projectId
          in: path
          description: Hashed ID for the project for which you'd like to see sharings.
          required: true
          schema:
            description: Hashed ID of the project (e.g., "4d23503f70")
            type: string
        - name: sharingId
          in: path
          description: The ID of the specific sharing object that you want to see.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successfully retrieved sharing details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectSharingSchema'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      tags:
        - Project Sharings
      security:
        - BearerAuth: []
    put:
      summary: Project Sharing Update
      description: |
        Update a sharing on a project.

        ## Requires api token with one of the following permissions
        ```
        Read, update & delete anything
        ```
      parameters:
        - name: projectId
          in: path
          description: ID of the project
          required: true
          schema:
            type: string
        - name: sharingId
          in: path
          description: ID of the sharing to be updated
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSharingRequest'
      responses:
        '200':
          description: Sharing updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectSharingSchema'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      tags:
        - Project Sharings
      security:
        - BearerAuth: []
    delete:
      summary: Project Sharing Delete
      description: |
        Delete a sharing on a project.

        ## Requires api token with one of the following permissions
        ```
        Read, update & delete anything
        ```
      parameters:
        - name: projectId
          in: path
          description: Hashed ID of the project
          required: true
          schema:
            description: Hashed ID of the project (e.g., "4d23503f70")
            type: string
        - name: sharingId
          in: path
          description: ID of the sharing to be deleted
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Sharing deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectSharingSchema'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      tags:
        - Project Sharings
      security:
        - BearerAuth: []
  /medias:
    get:
      summary: Media List
      description: >
        Obtain a list of all the media in your account. For accounts with more
        than 100 media, you’ll want to page and sort the returned list.


        ## Requires api token with one of the following permissions

        ```

        Read, update & delete anything

        Read all data

        Read all folder and media data

        ```
      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 then 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
            then pass that

            cursor value to a `sort_by` name.
          required: false
          schema:
            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 then 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 then 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: project_id
          in: query
          description: >-
            A hashed ID specifying the project from which you would like to get
            results.
          required: false
          schema:
            description: Hashed ID of the project (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_id
          in: query
          description: Find the media by hashed_id.
          required: false
          schema:
            type: string
        - name: hashed_ids[]
          in: query
          description: Find all of the medias by these hashed_ids.
          required: false
          schema:
            type: array
            items:
              type: string
          explode:

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