Wistia Data API

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#list
• Projects#show
• Projects#create
• Projects#update
• Projects#delete
• Projects#copy

Projects Response

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

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

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:

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.

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

• Project Sharings#list
• Project Sharings#show
• Project Sharings#create
• Project Sharings#update
• Project Sharings#delete

Sharings Response

Share Response

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": "[email protected]"
      },
      "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": "[email protected]"
  },
  "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.

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

Example Project Sharings#Update Request

{
 "id": 14,
 "isAdmin": true,
 "canShare": true,
 "canDownload": true,
 "canUpload": true,
 "share": {
   "id": 3,
   "name": "Jim",
   "type": "Contact",
   "email": "[email protected]"
 },
 "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": "[email protected]"
  },
  "project": {
    "id": 13,
    "name": "My Project"
  }
}

Medias

Methods

• Medias#list
• Medias#show
• Medias#update
• Medias#delete
• Medias#copy
• Medias#stats
• Medias#archive
• Medias#restore

Medias Response

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

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.

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

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

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:

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

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

📝

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

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

📝

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

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

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

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
• Customizations#create
• Customizations#update
• Customizations#delete

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
• Captions#create
• Captions#show
• Captions#update
• Captions#delete
• Captions#purchase

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:

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

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:

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.

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

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.