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.

Getting Started

Creating and Managing Access Tokens

When your Wistia account is created, a master token will automatically be generated for you account, which you can find in the API tab of your Account Settings. This master token has full read/write permissions on your account. You can generate additional access tokens with various permissions as well. Keep these tokens secret! do not put them in client-side code or commit them to a github repository.

Versions

We will introduce API changes when necessary/possible, and update the version number (i.e. v1) when a breaking change is made.

Making Requests

Authentication

You must use SSL (https instead of http) to access the API.

The easiest way to access the api is via Bearer Token:

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

Passing

All parameters should be passed in the body of the request and URL encoded. Alternatively, they can be appended to the end of the URL after a question mark (?) character and passed as query string parameters.

Response

The request examples retrieve the data in JSON format. If you would like the data in XML format, change the extension of the request from json to xml.

PUT

Some HTTP clients are limited to sending GET and POST requests (e.g. HTML forms have this limitation). You will notice, however, that many of the API calls only respond to PUT or DELETE requests. In order to trigger these calls from a client that does not support PUT or DELETE, use a POST request and add a _method parameter with a value of either put or delete.

Rate

The API has a rate limit of 600 requests per minute. If there are more than 600 requests in a minute for a particular account, the service will respond with HTTP error 503 Service Unavailable and the Retry-After HTTP header will be set with a number of seconds to wait before trying again.

You’re only working towards that 600 requests/minute limit when you submit an HTTP request to upload.wistia.com or api.wistia.com. Simply accessing a media asset (like a .bin file) does not count.

Paging and Sorting Responses

The list methods in the API support paging, sorting, and filtering of results. Filtering will be covered in the individual methods.

Paging

You can get your results back in chunks. To set the page size and/or the number of pages that you want to see, use the following query parameters:

Sorting

You can sort your results based on a field you specify. To specify how you want the results to be sorted, append one or both of the following query parameters to the request URL:

For example, if you want to sort your results in descending order by the date created, your request URL would look like this:

https://api.wistia.com/v1/projects.json?sort_by=created&sort_direction=0

Projects

Projects are the main organizational objects in Wistia. Media must be stored in Projects.

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 will include 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": "My Project Description",
      "mediaCount": 2,
      "created": "2010-08-13T18:47:39+00:00",
      "updated": "2010-08-19T21:47:00+00:00",
      "hashedId": "4d23503f70",
      "anonymousCanUpload": false,
      "anonymousCanDownload": false,
      "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",
      "anonymousCanUpload": false,
      "anonymousCanDownload": false,
      "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, this means that 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

{
    "anonymousCanDownload": false,
    "anonymousCanUpload": false,
    "created": "2013-09-19T15:05:15+00:00",
    "description": "",
    "hashedId": "ln2k6qwi9k",
    "id": 464427,
    "mediaCount": 3,
    "medias": [
        {
            "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"
        },
        {
            "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": "My Project Description",
    "mediaCount": 0,
    "created": "2010-08-15T18:47:39+00:00",
    "updated": "2010-08-15T18:47:39+00:00",
    "hashedId": "4d23503f70",
    "anonymousCanUpload": false,
    "anonymousCanDownload": false,
    "public": false,
    "publicId": "4bD"
}

Projects: Update

The Wistia data API allows you to 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",
  "anonymousCanUpload": false,
  "anonymousCanDownload": false,
  "public": false,
  "publicId": "lpzgy6e09m"
}

Projects: Delete

The Wistia data API allows you to 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 project that was deleted.

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": "Project Description",
  "mediaCount": 5,
  "created": "2010-08-15T18:47:39+00:00",
  "updated": "2010-08-15T18:47:39+00:00",
  "hashedId": "lpzgy6e09m",
  "anonymousCanUpload": false,
  "anonymousCanDownload": false,
  "public": false,
  "publicId": "lpzgy6e09m"
}

Projects: Copy

Copy a project, including all media and sections.

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

Parameters

You can specify the owner of the 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": "Project Description",
  "mediaCount": 5,
  "created": "2010-08-15T18:47:39+00:00",
  "updated": "2010-08-15T18:47:39+00:00",
  "hashedId": "epzn8s7wju",
  "anonymousCanUpload": false,
  "anonymousCanDownload": false,
  "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": "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 the 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 would 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. Conceptually, 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 the way that 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": "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 will contain 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#list
• Medias#show
• Medias#update
• Medias#delete
• Medias#copy
• Medias#stats

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 or type of media. 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 that 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",
    "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 that you have 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",
  "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 piece of 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",
  "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 from your account.

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",
  "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 Wistia data API allows you to copy a piece of media.

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

Parameters

The Response

If the media is copied successfully, the server will respond with HTTP status 201 Created. The HTTP Location header will be set to the URL where the newly created media resource resides. The body of the response will contain 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",
  "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 that has been embedded on your site.

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

The Response

If the request is successful, the server will send 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
    }
}

Account

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

The Response

Customizations

The Customize API lets you configure each video in your account with specific customizations. These customizations will apply to your video 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

In order 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

Make sure you 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 in the Embedding Options Documentation.

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.

Notes:

• The Captions API only supports JSON.
• 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.

Captions: Show

This method will return the captions for a specific language for a video in SRT format.

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

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

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.

Asset URLs - Tips & Tricks

Asset URL tips and tricks are here.