Wistia Data API

Learn how to enable Data API access for your account.

The Wistia data API gives you all kinds of programmatic access to your Wistia account. The data is available in either JSON or XML format over HTTP.

Note
The Wistia APIs were specifically built for videos in projects. We do not formally support using our APIs for audio files in projects, or audio or video episodes in Channels at this time. For the most reliable experience, we recommend continuing to use these for videos in projects.

You’ll need an API token to use the Data API. Head on over here for instructions on how to generate one and learn about using the Wistia APIs!

Projects

Projects are the main organizational objects in Wistia.

Methods

Projects Response

When a Project Object is returned from a method, it includes the following fields:

FieldDescription
idA unique numeric identifier for the project within the system.
nameThe project’s display name.
descriptionThe project’s description.
mediaCountThe number of different medias that have been uploaded to the project.
createdThe date that the project was originally created.
updatedThe date that the project was last updated.
hashedIdA private hashed id, uniquely identifying the project within the system.
publicA boolean indicating whether the project is available for public (anonymous) viewing.
publicIdIf the project is public, this field contains a string representing the ID used for referencing the project in public URLs.

Projects: List

Use the Projects#list method to request a list of Projects in your Wistia account. This request supports paging and sorting.

Projects#list requests look like this:

GET https://api.wistia.com/v1/projects.json

Example Project#List Request

To retrieve all projects in an account, 10 projects at a time, starting on the second page of results, your request URL should look something like this:

https://api.wistia.com/v1/projects.json?page=2&per_page=10

The Response

  [
    {
      "id": 22570,
      "name": "My Project Title",
      "description": "About My Project",
      "mediaCount": 2,
      "created": "2010-08-13T18:47:39+00:00",
      "updated": "2010-08-19T21:47:00+00:00",
      "hashedId": "4d23503f70",
      "public": false,
      "publicId": "4bD"
    },
    {
      "id": 10495,
      "name": "Another Project Title",
      "description": "Another Project Description",
      "mediaCount": 4,
      "created": "2010-08-13T18:47:39+00:00",
      "updated": "2010-08-19T21:47:00+00:00",
      "hashedId": "4d23503f70",
      "public": false,
      "publicId": "3dF"
    }
  ]

Projects: Show

Retrieve details about a specific project.

To get the details on a Project (and all media there), send an HTTP GET request to the following URL:

GET https://api.wistia.com/v1/projects/<project-hashed-id>.json

The response for the Projects#show request will also include an array of media objects. Each entry in the media array has all media object fields.

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.

Example Projects#Show Request

Request

curl https://api.wistia.com/v1/projects/ln2k6qwi9k.json
   -H "Authorization: Bearer YOUR_TOKEN_HERE"

Response

{
    "created": "2013-09-19T15:05:15+00:00",
    "description": "",
    "hashedId": "ln2k6qwi9k",
    "id": 464427,
    "mediaCount": 3,
    "medias": [
        {
            "archived": false,
            "created": "2013-09-19T15:05:17+00:00",
            "description": "",
            "duration": 167.29,
            "hashed_id": "azh1x9nesb",
            "id": 4488635,
            "name": "How They Work: Zappos",
            "progress": 1.0,
            "status": "ready",
            "thumbnail": {
                "height": 60,
                "url": "http://embed.wistia.com/deliveries/11bb346da9e041a4ce5c8f0a37803f8ef50e2848.jpg?image_crop_resized=100x60",
                "width": 100
            },
            "type": "Video",
            "updated": "2013-10-28T20:53:12+00:00"
        },
        {
            "archived": false,
            "created": "2013-09-19T15:30:49+00:00",
            "description": "<p>\n\nWistia goes to Nevada to visit with Zappos to hear what they have to say about their company culture.&nbsp;</p>\n<p>\n\n&nbsp;</p>\n<p>\n\nFor more How They Work videos, check out:</p>\n<p>\n\n<a href=\"http://jeff.wistia.com/projects/ln2k6qwi9k\">http://jeff.wistia.com/projects/ln2k6qwi9k</a></p>\n",
            "duration": 167.0,
            "hashed_id": "v80gyfkt28",
            "id": 4489021,
            "name": "How They Work - Zappos",
            "progress": 1.0,
            "status": "ready",
            "thumbnail": {
                "height": 60,
                "url": "http://embed.wistia.com/deliveries/7fbf9c2fe9c6585f9aa032f43f0aecc3f287e86b.jpg?image_crop_resized=100x60",
                "width": 100
            },
            "type": "Video",
            "updated": "2013-10-28T20:53:12+00:00"
        },
    ],
    "name": "How They Work",
    "public": true,
    "publicId": "ln2k6qwi9k",
    "updated": "2013-10-28T20:53:12+00:00"
}

Projects: Create

Create a new project in your Wistia account.

POST https://api.wistia.com/v1/projects.json

Parameters

Parameter NameDescription
name (required)The name of the project you want to create (required).
adminEmailThe email address of the person you want to set as the owner of this project. Defaults to the Wistia Account Owner.
public (optional)A flag indicating whether or not the project is enabled for public access. Set to “1” to enable and “0” to disable.

The Response

If the project is created successfully, the API will respond with an HTTP 201 Created status code, and the Location HTTP header will point to the new project.

Example Projects#Create Request

Status: 201 Created
Location: https://api.wistia.com/v1/projects/1.json

#json
{
  "id": 1,
    "name": "My New Project",
    "description": "About My Project",
    "mediaCount": 0,
    "created": "2010-08-15T18:47:39+00:00",
    "updated": "2010-08-15T18:47:39+00:00",
    "hashedId": "4d23503f70",
    "public": false,
    "publicId": "4bD"
}

Projects: Update

Update a project.

PUT https://api.wistia.com/v1/projects/<project-hashed-id>.json

The Parameters

Here are the valid parameters for this action:

Parameter NameDescription
nameThe project’s new name.
publicA flag indicating whether or not the project is enabled for public access. Set to “1” to enable and “0” to disable.

Example Projects#Update Request

The Request

PUT https://api.wistia.com/v1/projects/lpzgy6e09m.json?name="Jeff's First Project"

The Response

Status: 200 OK

{
  "id": 1,
  "name": "Jeff's First Project",
  "description": "This Project needs a description BAD.",
  "mediaCount": 5,
  "created": "2013-08-15T18:47:39+00:00",
  "updated": "2013-08-15T18:47:39+00:00",
  "hashedId": "lpzgy6e09m",
  "public": false,
  "publicId": "lpzgy6e09m"
}

Projects: Delete

Delete a project.

The Request

DELETE https://api.wistia.com/v1/projects/<project-hashed-id>.json

The Response

If the project is deleted successfully, the server will respond with HTTP status 200 OK. The body of the response will contain an object representing the deleted project.

Example Projects#Delete Request

The Request

DELETE https://api.wistia.com/v1/projects/lpzgy6e09m.json

The Response

Status: 200 OK

{
  "id": 1,
  "name": "Project Name",
  "description": "About My Project",
  "mediaCount": 5,
  "created": "2010-08-15T18:47:39+00:00",
  "updated": "2010-08-15T18:47:39+00:00",
  "hashedId": "lpzgy6e09m",
  "public": false,
  "publicId": "lpzgy6e09m"
}

Projects: Copy

Copy a project.

Note
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). 
POST https://api.wistia.com/v1/projects/<project-hashed-id>/copy.json

Parameters

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

Parameter NameDescription
adminEmail (optional)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.

The Response

If the project is copied successfully, the server will respond with HTTP status 201 Created.

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.

Example Projects#Copy Request

The Request

POST https://api.wistia.com/v1/projects/fuw14mll5u/copy.json

The Response

Status: 201 Created
Location: https://api.wistia.com/v1/projects/epzn8s7wju.json

{
  "id": 3,
  "name": "Project Name",
  "description": "About My Project",
  "mediaCount": 5,
  "created": "2010-08-15T18:47:39+00:00",
  "updated": "2010-08-15T18:47:39+00:00",
  "hashedId": "epzn8s7wju",
  "public": false,
  "publicId": "epzn8s7wju"
}

Project Sharings

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.

Methods

Sharings Response

FieldDescription
idUnique numeric identifier for the sharing object.
isAdminWhether the user has admin rights on the project.
canShareWhether the user is allowed to share the project with others.
canDownloadWhether the user is allowed to download files from the project.
canUploadWhether the user is allowed to upload files to the project.
shareAn object identifying the Contact or ContactGroup with which this sharing object ties the project. See below for a description of the fields in this object.
projectAn object representing the project to which this sharing object grants access. It only has 2 attributes: id and name, which both have the same meaning as they do elsewhere in the API.

Share Response

FieldDescription
idA unique numeric identifier for the Contact or ContactGroup.
nameThe display name of this Contact or ContactGroup.
typeA string representing what type of share this object represents: Contact or ContactGroup.
emailIf this object refers to a Contact, this field will be present, indicating the contact email of the person with which the project is shared. If it’s a ContactGroup, this field will be omitted.

Project Sharings: List

See a list of sharings on a project. This request supports paging and sorting.

GET https://api.wistia.com/v1/projects/<project-id>/sharings.json

The Response

The server responds with HTTP status 200 OK. The response body contains a list of all sharings on the project.

Example Project Sharings#list Request

[
  {
    "id": 14,
      "isAdmin": true,
      "canShare": true,
      "canDownload": true,
      "canUpload": true,
      "share": {
        "id": 3,
        "name": "Jim",
        "type": "Contact",
        "email": "jim@wistia.com"
      },
      "project": {
        "id": 13,
        "name": "My Project"
      }
  },
  {
    "id": 15,
    "isAdmin": false,
    "canShare": true,
    "canDownload": true,
    "canUpload": false,
    "share": {
      "id": 3,
      "name": "Sales",
      "type": "ContactGroup"
    },
    "project": {
      "id": 13,
      "name": "My Project"
    }
  }
]

Project Sharings: Show

See details of a particular sharing on a project.

GET https://api.wistia.com/v1/projects/<project-id>/sharings/<sharing-id>.json
  • <project-id> is the hashed ID of the project for which you’d like to see sharings,
  • <sharing-id> is the ID of the specific sharing object that you want to see.

The Response

The server responds with HTTP status 200 OK and the response body contains the requested sharing on the project.

Example Project Sharings#Show Request

{
  "id": 14,
  "isAdmin": true,
  "canShare": true,
  "canDownload": true,
  "canUpload": true,
  "share": {
    "id": 3,
    "name": "Jim",
    "type": "Contact",
    "email": "jim@wistia.com"
  },
  "project": {
    "id": 13,
    "name": "My Project"
  }
}

Project Sharings: Create

Share a project with a user by email. You do this by creating a new sharing object for a project.

  POST https://api.wistia.com/v1/projects/<project-id>/sharings.json

This method can accept several parameters to customize how the sharing happens.

The only required parameter is with, which specifies the email address of the person with whom you want to share the project.

ParameterDescription
with (required)The email address of the person with whom you want to share the project.
requirePassword (optional)If this parameter is “1” (no quotes), which is the default value, then the user will be required to activate their account and set a password to see the project. Set it to “0” (again, no quotes) to allow them to see the project without entering a password.
canShare (optional)Set this parameter to “1” (no quotes) to allow the user to share the project with others.
canDownload (optional)Set this parameter to “1” (no quotes) to allow the user to download files from the project.
canUpload (optional)Set this parameter to “1” (no quotes) to allow the user to upload files to the project.
sendEmailNotification (optional)Set this parameter to “1” (no quotes) to send a sharing notification on creation.

The Response

The server responds with HTTP status 201 Created, and the Location HTTP header is set to the API endpoint for the new sharing object.

The response body contains either a link for the user to activate their account or a link for the user to access the project if they already have a username/password.

Example Project Sharings#create Request

Status: 201 Created

Location: https://api.wistia.com/v1/projects/13/sharings/16.json

{ "project": "http://myaccount.wistia.com/projects/13" }

Here’s an example of what the response body might look like if the user is not yet activated:

{ "activation": "http://myaccount.wistia.com/my_activation_link" }

Project Sharings: Update

Update a sharing on a project.

The Request

PUT https://api.wistia.com/v1/projects/<project-id>/sharings/<sharing-id>.json
Parameter NameDescription
canShare“1” to allow the user or group to share the project with others, “0” to disable this functionality.
canDownload“1” to allow the user or group to download media from the project, “0” to disable this functionality.
canUpload“1” to allow the user or group to upload media to the project, “0” to disable this functionality.
isAdmin“1” to give this user admin rights to the project, “0” to take away admin rights.

Example Project Sharings#Update Request

{
 "id": 14,
 "isAdmin": true,
 "canShare": true,
 "canDownload": true,
 "canUpload": true,
 "share": {
   "id": 3,
   "name": "Jim",
   "type": "Contact",
   "email": "jim@wistia.com"
 },
 "project": {
   "id": 13,
   "name": "My Project"
 }
}

Project Sharings: Delete

Delete a sharing on a project.

DELETE https://api.wistia.com/v1/projects/<project-id>/sharings/<sharing-id>.json

The Response

The server will respond with HTTP status 200 OK. The body of the response contains an object representing the sharing that was just deleted.

Example Project Sharings#Delete

{
  "id": 14,
  "isAdmin": true,
  "canShare": true,
  "canDownload": true,
  "canUpload": true,
  "share": {
    "id": 3,
    "name": "Jim",
    "type": "Contact",
    "email": "jim@wistia.com"
  },
  "project": {
    "id": 13,
    "name": "My Project"
  }
}

Medias

Methods

Medias Response

FieldDescription
idA unique numeric identifier for the media within the system.
nameThe display name of the media.
typeA string representing what type of media this is. Values can be Video, Audio, Image, PdfDocument, MicrosoftOfficeDocument, Swf, or UnknownType.
archivedWhether or not the media is archived, either true or false
statusPost upload processing status. There are four statuses: queued, processing, ready, and failed.
progress (if available)This field is a floating point value between 0 and 1 that indicates the progress of the processing for this file. For instance, a value of 0.5 indicates we’re about halfway done processing this file.
sectionThe title of the section in which the media appears. This attribute is omitted if the media is not in a section (default).
thumbnailAn object representing the thumbnail for this media. The attributes are URL, width, and height.
durationSpecifies the length (in seconds) for audio and video files. Specifies number of pages in the document. Omitted for other types of media.
createdThe date when the media was originally uploaded.
updatedThe date when the media was last changed.
assetsAn array of the assets available for this media. See the table below for a description the fields in each asset object.
embedCodeDEPRECATED: If you want to programmatically embed videos, follow the construct an embed code guide.
descriptionA description for the media which usually appears near the top of the sidebar on the media’s page.
hashed_idA unique alphanumeric identifier for this media.

Media Status

Media files return a response attribute called status. After upload is complete, media files must be processed. Status indicates which stage in processing the file is at.

There are four status settings:

  • 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)

Asset Object Response

FieldDescription
urlA direct-access URL to the content of the asset.
widthThe width of this specific asset, if applicable.
heightThe height of this specific asset, if applicable.
fileSizeThe size of the asset file that’s referenced by url, measured in bytes.
contentTypeThe asset’s content type.
typeThe 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.

Medias: List

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.

GET https://api.wistia.com/v1/medias.json

Filtering

You can filter the results by project, name, media type, or archived status. Similar to sorting, filters are specified by appending query parameters to the end of the URL used to access the API. The following table lists the parameters you can use for filtering and a description of how to use them.

ParameterDescription
project_idAn integer specifying the project from which you would like to get results.
nameFind a media or medias whose name exactly matches this parameter.
typeA string specifying which type of media you would like to get. Values can be Video, Audio, Image, PdfDocument, MicrosoftOfficeDocument, Swf, or UnknownType.
hashed_idFind the media by hashed_id.
archivedA boolean to filter by archived status: true will return only archived medias in the response, while false will return only active (ie. non-archived) medias.

Example Medias#List Request

The Request

GET https://api.wistia.com/v1/medias.json

The Response

Status 200 OK

[
  {
    "id": 377249,
    "name": "Litmus Team Video - Proof 2",
    "type": "Video",
    "archived": false,
    "created": "2011-05-26T00:04:25+00:00",
    "updated": "2011-05-26T00:04:25+00:00",
    "duration": 67.85,
    "hashed_id": "0daadf36b3",
    "description": "",
    "progress": 1,
    "status": "ready",

    "thumbnail": {
      "url": "http://embed.wistia.com/deliveries/02b2a615c6cd0db58132d2cb92fda84e04c9d8f3.jpg?image_crop_resized=100x60",
      "width": 100,
      "height": 60
    },

    "project": {
      "id": 47115,
      "name": "Media Needed to Rock",
      "hashed_id": "5cb193e92c"
    },

    "assets": [

      {
        "url": "http://embed.wistia.com/deliveries/6a55cd744123d52dd2735f31a2720451989da1ce.bin",
        "width": 1280,
        "height": 720,
        "fileSize": 42726643,
        "contentType": "video/quicktime",
        "type": "OriginalFile"
      },

      {
        "url": "http://embed.wistia.com/deliveries/d8b6b17ed40700c2bc4ba98dd481f7768dc6ad3a.bin",
        "width": 640,
        "height": 360,
        "fileSize": 9305415,
        "contentType": "video/mp4",
        "type": "Mp4VideoFile"
      },

      {
        "url": "http://embed.wistia.com/deliveries/18bc4e5256107dda3cc5e77e719ac8cc90408cd5.bin",
        "width": 640,
        "height": 360,
        "fileSize": 6054188,
        "contentType": "video/mp4",
        "type": "IphoneVideoFile"
      },

      {
        "url": "http://embed.wistia.com/deliveries/02b2a615c6cd0db58132d2cb92fda84e04c9d8f3.bin",
        "width": 640,
        "height": 360,
        "fileSize": 37470,
        "contentType": "image/jpeg",
        "type": "StillImageFile"
      }
    ]
  }
]

Medias: Show

Get information about a specific piece of media you’ve uploaded to your account.

https://api.wistia.com/v1/medias/<media-hashed-id>.json

Example Media#Show Request

The Request

GET https://api.wistia.com/v1/medias/v80gyfkt28.json

The Response

Status 200 OK

{
  "id":4489021,
  "name":"How They Work - Zappos",
  "type":"Video",
  "archived": false,
  "created":"2013-09-19T15:30:49+00:00",
  "updated":"2013-10-28T20:53:12+00:00",
  "duration":167.0,
  "hashed_id":"v80gyfkt28",
  "description":"<p>\n\nWistia goes to Nevada to visit with Zappos to hear what they have to say about their company culture.&nbsp;</p>\n<p>\n\n&nbsp;</p>\n<p>\n\nFor more How They Work videos, check out:</p>\n<p>\n\n<a href=\"http://jeff.wistia.com/projects/ln2k6qwi9k\">http://jeff.wistia.com/projects/ln2k6qwi9k</a></p>\n",
  "progress":1.0,
  "status":"ready",
  "thumbnail":{
    "url":"http://embed.wistia.com/deliveries/7fbf9c2fe9c6585f9aa032f43f0aecc3f287e86b.jpg?image_crop_resized=100x60",
    "width":100,
    "height":60
  },
  "project":{
    "id":464427,
    "name":"How They Work",
    "hashed_id":"ln2k6qwi9k"
  },
  "assets":[
    {
      "url":"http://embed.wistia.com/deliveries/856970d9a4bcb9aab381a0bd9ab714f19d72c62f.bin",
      "width":960,
      "height":540,
      "fileSize":23695556,
      "contentType":"video/mp4",
      "type":"OriginalFile"
    },
    {
      "url":"http://embed.wistia.com/deliveries/c16c2ef4a87dc8147305637cc302f2e9f9c78977.bin",
      "width":960,
      "height":540,
      "fileSize":17493009,
      "contentType":"video/x-flv",
      "type":"FlashVideoFile"
    },
    {
      "url":"http://embed.wistia.com/deliveries/9e5ead0ef514bef19e3bad9062038c7dad60e10a.bin",
      "width":640,
      "height":360,
      "fileSize":19542684,
      "contentType":"video/mp4",
      "type":"IphoneVideoFile"
    },
    {
      "url":"http://embed.wistia.com/deliveries/7fbf9c2fe9c6585f9aa032f43f0aecc3f287e86b.bin",
      "width":960,
      "height":540,
      "fileSize":105070,
      "contentType":"image/jpeg",
      "type":"StillImageFile"
    }
  ]
}

Medias: Update

Update attributes on a media.

The Request

PUT https://api.wistia.com/v1/medias/<media-hashed-id>.json
Parameter NameDescription
nameThe media’s new name.
new_still_media_idThe Wistia hashed ID of an image that will replace the still that’s displayed before the player starts playing. Will return failure message unless media to update is a video, and new still is an image.
descriptionA new description for this media. Accepts plain text or markdown.

Example Media#Update Request

The Request

PUT https://api.wistia.com/v1/medias/x8fiv4y2mc.json?name=A%20New%20Hope

The Response

Status 200 OK

{
  "id": 5483881,
  "name": "A New Hope",
  "type": "Video",
  "archived": false,
  "created": "2014-01-03T23:27:30+00:00",
  "updated": "2014-01-03T23:27:30+00:00",
  "duration": 67.85,
  "hashed_id": "x8fiv4y2mc",
  "description": "",
  "progress": 1,
  "status": "ready",
  "thumbnail": {
    "url": "http://embed.wistia.com/deliveries/02b2a615c6cd0db58132d2cb92fda84e04c9d8f3.jpg?image_crop_resized=100x60",
    "width": 100,
    "height": 60
  }
}

Medias: Delete

Delete a media.

DELETE https://api.wistia.com/v1/medias/<media-hashed-id>.json

If the media is deleted successfully, the server will respond with HTTP status 200 OK to let you know that it worked.

The body of the response will contain an object representing the piece of media that was just deleted.

Example Request

The Request

DELETE https://api.wistia.com/v1/medias/w3fpuwlec9.json

The Response

Status 200 OK

{
  "id": 5483881,
  "name": "A New Hope",
  "type": "Video",
  "archived": false,
  "created": "2014-01-03T23:27:30+00:00",
  "updated": "2014-01-03T23:27:30+00:00",
  "duration": 67.85,
  "hashed_id": "x8fiv4y2mc",
  "description": "",
  "progress": 1,
  "status": "ready",
  "thumbnail": {
    "url": "http://embed.wistia.com/deliveries/02b2a615c6cd0db58132d2cb92fda84e04c9d8f3.jpg?image_crop_resized=100x60",
    "width": 100,
    "height": 60
  }
}

Medias: Copy

The Data API allows you to copy a media.

POST https://api.wistia.com/v1/medias/<media-hashed-id>/copy.json

Parameters

ParameterDescription
project_id (optional)The ID of the project where you want the new copy placed. If this value is invalid or omitted, defaults to the source media’s current project.
owner (optional)An email address specifying the owner of the new media. If this value is invalid or omitted, defaults to the source media’s current owner.

The Response

If the media is copied successfully, the server responds with HTTP status 201 Created. The HTTP Location header is set to the URL where the newly created media resource resides. The body of the response contains an object representing the new copy of the media that was just created, as well as the project it belongs to.

Example Media#Copy Request

The Request

POST https://api.wistia.com/v1/medias/zckfiliwoi/copy.json

The Response

Status: 201 Created
Location: https://api.wistia.com/v1/medias/wrlyf77iw5.json

{
  "id":160,
  "name":"MVI_9736",
  "type":"Video",
  "archived": false,
  "created":"2013-11-09T21:33:23+00:00",
  "updated":"2013-11-09T21:33:23+00:00",
  "duration":68.0,
  "hashed_id":"wrlyf77iw5",
  "description":"",
  "progress":1.0,
  "status":"ready",
  "thumbnail":{
    "url":"http://embed-0.wistia.com/deliveries/fcf39d52918652ecbde8e2123ea479c382f8771c.jpg?image_crop_resized=100x60",
    "width":100,
    "height":60
  },
  "project": {
    "id": 47115,
    "name": "Media Needed to Rock",
    "hashed_id": "5cb193e92c"
  }
}

Medias: Stats

Aggregated tracking statistics for a video embedded on your site.

GET https://api.wistia.com/v1/medias/<media-hashed-id>/stats.json
Note
This request works for videos only. Otherwise, the server responds with HTTP status code 400 Bad Request and the body contains an error message.

The Response

If the request is successful, the server sends a response with something similar to the following:

FieldDescription
idA unique numeric identifier for the video within the system.
hashed_idA unique alphanumeric identifier for the video within the system.
nameThe display name of the video.
statsAn object representing the aggregated embed statistics for this video.

Here is the definition of each field in the stats object:

FieldDescription
pageLoadsThe total number of times that the page containing the embedded video has been loaded.
visitorsThe number of unique visitors to the page containing the embedded video.
percentOfVisitorsClickingPlayThis is an integer between 0 and 100 that shows what percentage of the time someone who saw the page containing the embedded video played the video.
playsThe total number of times that the video has been played.
averagePercentWatchedThis is an integer between 0 and 100. It shows the average percentage of the video that was watched over every time the video was played.

Example Media#Stats Request

The Request

GET https://api.wistia.com/v1/medias/g5pnf59ala/stats.json

The Response

Status 200 OK

{
    "id": 3690639,
    "hashed_id": "g5pnf59ala",
    "name": "Dan Mills - Young and Free",
    "stats": {
        "averagePercentWatched": 23,
        "pageLoads": 147,
        "percentOfVisitorsClickingPlay": 50,
        "plays": 46,
        "visitors": 20
    }
}
Note
We also have a Stats API to access stats beyond the media level!

Medias: Archive

Archive medias from your account. This method accepts a list of up to 100 medias to archive per request. It processes requests asynchronously and will return a background_job_status object rather than the typical Media response object. The Background Job Status endpoint can be queried for the job’s progress.

Note
Livestream medias, recording sessions, and Soapbox videos imported to Wistia before September 1, 2023 cannot be archived at this time.
Alert
The video recording power of Soapbox is now available natively in Wistia. Learn more. 
PUT https://api.wistia.com/v1/medias/archive.json
ParameterDescription
hashed_ids[]An array of the media hashed IDs to be archived. NOTE: Each hashed ID must be passed to the method as a separate parameter. In addition, the brackets [] must be URL encoded.
Note
The brackets [] in the hashed_ids param must be URL encoded if the param is being passed as part of the query string or if it’s being passed in the request body and the Content-Type request header is NOT application/x-www-form-urlencoded.

Example Request

PUT https://api.wistia.com/v1/medias/archive.json?hashed_ids%5B%5D=MEDIA_HASHED_ID_ONE&hashed_ids%5B%5D=MEDIA_HASHED_ID_TWO
FieldDescription
messageA confirmation message that the background job has been queued
background_job_status.idThe ID of the background job that’s been queued for the request
background_job_status.statusThe status of the background job that’s been queued for the request. Possible values are queued, started, finished, and failed

Status 200 OK

{
    "message": "Archive request for 2 media has been successfully queued for processing.",
    "background_job_status": {
    "id": 123,
    "status": "queued"
}
}

Medias: Restore

Restore archived medias to your account. This method accepts a list of up to 100 medias to restore per request. It processes requests asynchronously and will return a background_job_status object rather than the typical Media response object. The Background Job Status endpoint can be queried for the job’s progress.

Note
Your account must have access to our Archiving feature in order to utilize this method. 
PUT https://api.wistia.com/v1/medias/restore.json
ParameterDescription
hashed_ids[]An array of the media hashed IDs to be restored. NOTE: Each hashed ID must be passed to the method as a separate parameter.
project_idThe hashed ID of the project to restore the medias to. Required unless channel_id is specified.
channel_idThe hashed ID of the channel to restore the medias to. Required unless project_id is specified.
Note
The brackets [] in the hashed_ids param must be URL encoded if the param is being passed as part of the query string or if it’s being passed in the request body and the Content-Type request header is NOT application/x-www-form-urlencoded.

Example Request

PUT https://api.wistia.com/v1/medias/restore.json?project_id=PROJECT_HASHED_ID&hashed_ids%5B%5D=MEDIA_HASHED_ID_ONE&hashed_ids%5B%5D=MEDIA_HASHED_ID_TWO

The Response

FieldDescription
messageA confirmation message that the background job has been queued
container.typeThe type of container the medias will be restored to, either Project or Channel
container.nameThe display name of the container the medias will be restored to
container.hashedIdThe hashed ID of the container the medias will be restored to
background_job_status.idThe ID of the background job that’s been queued for the request
background_job_status.statusThe status of the background job that’s been queued for the request. Possible values are queued, started, finished, and failed

Status 200 OK

{
    "message": "Restore request for 2 media has been successfully queued for processing.",
    "background_job_status": {
    "id": 123,
    "status": "queued"
}
}

Account

GET https://api.wistia.com/v1/account.json

The Response

FieldDescription
idNumeric id of the account
nameAccount name
urlAccount’s main Wistia URL (e.g. http://brendan.wistia.com)
mediaCountThe total number of medias in this account

Background Job Status

Several methods in the Wistia Data API process requests asynchronously - we create a background job to handle the request. For those methods, the response we send back does not contain a representation of the affected resource. Instead we send back a confirmation message that the job has been queued as well as a background_job_status object containing the job ID and status. That ID can be used to poll the Background Job Status endpoint for updates on the job’s progress.

GET https://api.wistia.com/v1/background_job_status/<background-job-status-id>.json

Example Request

GET https://api.wistia.com/v1/background_job_status/123.json

The Response

FieldDescription
idThe numeric ID of the background job
statusThe background job’s status. Possible values are queued, started, finished, and failed

Status 200 OK

{
    "id": 123,
    "status": "finished"
}

Customizations

The Customize API lets you configure each video in your account with specific customizations. These customizations apply to your videos both in your account, and wherever you embed it.

The Customize API only responds with JSON. It expects data to be posted in JSON format too.

Methods

Customizations: Show

The Customize API allows you to see the customizations saved for your video.

The Request

To tell Wistia that you want information about a specific video, send an HTTP GET request to the following URL:

https://api.wistia.com/v1/medias/<media-id>/customizations.json

Replace <media-id> with the hashed ID of the video you want.

The Response

Assuming authentication is successful and the request is in good order, the HTTP response will contain JSON that describes explicitly defined customizations for the video.

Example JSON Response

The embed options are explained in the Embed Options Documentation.

{
  "playerColor":"ff0000",
  "autoPlay":"false",
  "endVideoBehavior":"default",
  "playButton":"true",
  "smallPlayButton":"true",
  "volumeControl":"true",
  "fullscreenButton":"true",
  "playbar":"true",
  "controlsVisibleOnLoad":"true",
  "branding":"true",
  "plugin":{
    "socialbar-v1":{
      "buttons":"embed-twitter-facebook",
      "showTweetCount":"false",
      "tweetText":"{default}",
      "height":"25"
    },
     "chapters": {
      "visibleOnLoad": true,
      "chapterList": [
        {
          "id": 0,
          "title": "Chapter Title",
          "time": 0.044886,
          "deleted": false
        },
        {
          "id": 1,
          "title": "Chapter Title 2",
          "time": 46.34,
          "deleted": false
        },
      ],
      "on": true
    },
  }
}

Customizations: Create

The Customize API lets you replace the customizations for a video.

The Request

POST https://api.wistia.com/v1/medias/<media-id>/customizations.json

Make sure you replace <media-id> with the hashed ID of the video that you want to customize.

The raw post data is JSON representing the customizations that should be explicitly set for this video. These will replace the existing customizations for the video.

Example JSON Request

The embedding options are explained here.

POST /medias/hxsvasanee/customizations.json HTTP/1.1
Accept: application/json
Content-Type: application/json
Form Data:
{"playerColor":"ffffcc","controlsVisibleOnLoad":false}

The Response

If the request is successful, the server will respond with a status of 201 Created, along with the saved customizations.

Note that the saved customization values will all be strings. These are dynamically casted to the proper type on the client side.

Example JSON Request

{
  "playerColor":"ffffcc",
  "controlsVisibleOnLoad":"false"
}

Customizations: Update

The Customize API allows you to do partial updates on a video’s customizations.

The Request

PUT https://api.wistia.com/v1/medias/<media-id>/customizations.json

Make sure you replace <media-id> with the hashed ID of the video you want to customize.

The raw post data should be JSON representing the customizations that should be explicitly set for this video.

If a value is null, then that key will be deleted from the saved customizations. If it is not null, that value will be set.

Example JSON Request

The embedding options are explained in the Embedding Options Documentation.

PUT /medias/hxsvasanee/customizations.json HTTP/1.1
Accept: application/json
Content-Type: application/json
Form Data:
{
  "playerColor":"77dd77",
  "controlsVisibleOnLoad":null,
  "smallPlayButton":false
}

The Response

If the media update is successful, the server will respond with a status of 200 OK, along with the saved customizations.

Note that the saved customizations will all be strings. These are dynamically casted to the proper type on the client side.

Example JSON Request

{
  "playerColor":"77dd77",
  "smallPlayButton":"false"
}

Customizations: Delete

The Customize API allows you to delete a video’s customizations.

The Request

DELETE https://api.wistia.com/v1/medias/<media-id>/customizations.json

Make sure you replace <media-id> with the hashed ID of the media that you want to delete.

This method will wipe out all explicit customizations for a video, and it will act like it has never been customized.

Example JSON Request

DELETE /medias/hxsvasanee/customizations.json HTTP/1.1
Accept: application/json
Content-Type: application/json

The Response

If the media update is successful, the server will respond with a status of 200 OK.

Captions

The Captions API allows you to manage the captions for a video.

Alert
In order to update captions, be sure that your API key has the “Read, update, and delete anything” permission checked.

Notes:

  • denotes which language to get captions for and it should conform to ISO-639–2.

Methods

Captions: Index

This method will return all the captions for a video.

GET https://api.wistia.com/v1/medias/<media-hashed-id>/captions.json

The Response

The response will be an array of JSON objects with the following properties:

FieldDescription
languageA 3 character language code as specified by ISO-639–2.
captionsThe text of the captions for the specified language in SRT format.
Example Captions#Index Response
[
  {
    "captions": {
      "english_name": "English",
      "native_name": "English",
      "language": "eng",
      "text": "English SRT file contents here."
    }
  },
  {
    "captions": {
      "english_name": "French",
      "native_name": "Français",
      "language": "fra",
      "text": "Contenu du fichier SRT Français ici."
    }
  }
]

If captions do not exist for this video, the response will be an empty JSON array.

If this video does not exist, the response will be an empty HTTP 404 Not Found.

Captions: Create

This method is for adding captions to a video.

POST https://api.wistia.com/v1/medias/<media-hashed-id>/captions.json
ParameterDescription
caption_fileEither an attached SRT file or a string parameter with the contents of an SRT file.
languageAn optional parameter that denotes which language this file represents and it should conform to

ISO-639–2. If left unspecified, the language code will be detected automatically.

Example of caption_file as a string parameter using curl:

curl "https://api.wistia.com/v1/medias/<media-hashed-id>/captions.json" --data $'caption_file=1\n00:00:00,000 --> 00:00:03,000\nOh caption, my caption.'

Example of caption_file as an attached file using curl:

curl "https://api.wistia.com/v1/medias/<media-hashed-id>/captions.json" --form "caption_file=@./oh_caption.srt"

The Response

If successful, the response will be an empty HTTP 200 OK.

If captions already exist for this video, the response will be HTTP 400 Bad Request.

If this video does not exist, the response will be an empty HTTP 404 Not Found.

Note
While using this method will upload and add captions to your video, it will not enable captions in the video player. To turn on captions for a video, you’ll want to use the Captions Plugin.

Captions: Show

This method will return a video’s captions in the specified language and format. Defaults to JSON which returns SRT format, but you can optionally specify SRT, VTT or TXT as needed.

GET https://api.wistia.com/v1/medias/<media-hashed-id>/captions/<language-code>.json

GET https://api.wistia.com/v1/medias/<media-hashed-id>/captions/<language-code>.vtt

The Response

The response will be a JSON object with the following properties:

FieldDescription
languageA 3 character language code as specified by ISO-639–2.
captionsThe text of the captions for the specified language in SRT format.
Example Captions#Show Response
{
   "captions": {
      "english_name": "English",
      "native_name": "English",
      "language": "eng",
      "text": "English SRT file contents here."
  }
}

If the specified captions do not exist for this video, the response will be an empty HTTP 404 Not Found.

If this video does not exist, the response will be an empty HTTP 404 Not Found.

Captions: Update

This method is for replacing the captions on a video.

PUT https://api.wistia.com/v1/medias/<media-hashed-id>/captions/<language-code>.json

<language-code> denotes which language to update captions for and it should conform to ISO-639–2.

ParameterDescription
caption_fileEither an attached SRT file or a string parameter with the contents of an SRT file.

The Response

If successful, the response will be an empty HTTP 200 OK.

If the specified captions do not exist for this video, the response will be an empty HTTP 404 Not Found.

If this video does not exist, the response will be an empty HTTP 404 Not Found.

Captions: Delete

This method is for removing the captions file from a video altogether.

DELETE https://api.wistia.com/v1/medias/<media-hashed-id>/captions/<language-code>.json

The Response

If successful, the response will be an empty HTTP 200 OK.

If the specified captions do not exist for this video, the response will be an empty HTTP 404 Not Found.

If this video does not exist, the response will be an empty HTTP 404 Not Found.

Captions: Purchase

Note
If you’re on a Legacy Plan, computer-generated captions are $0.25/minute.

This method is for purchasing English captions on a video.

POST https://api.wistia.com/v1/medias/<media-hashed-id>/captions/purchase.json
ParameterDescription
automatedSet to true to order computer-generated captions (free) or false to order human-generated captions ($2.50/minute). Defaults to false.
rushSet to true to enable a rush order (one business day turnaround, $4.00/minute), or false to retain the standard four business day turnaround for human-generated captions ($2.50/minute). Defaults to true.
automatically_enableSet to true to automatically enable captions for the video as soon as the order is ready or false to hold the captions for review before manually enabling them. Defaults to true.

This request will charge the credit card on your account if successful. Therefore you must have a saved credit card in order to use this API endpoint.

The Response

If successful, the response will be an empty HTTP 200 OK.

If English captions already exist for this video, the response will be an empty HTTP 400 Bad Request.

If this video does not exist, the response will be an empty HTTP 404 Not Found.