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.
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:
Parameter | Description |
---|---|
page | Specifies which page of the results you want to see. Defaults to 1 (not 0). |
per_page | The number of results you want to get back per request. The maximum value of this parameter is 100, which is also the default. |
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:
Parameter | Description |
---|---|
sort_by | The name of the field to sort by. Valid values are name , created , or updated . Defaults to sorting by Project ID. |
sort_direction | Specifies the direction of the sort, defaults to '1'. 1 = ascending, 0 = descending. |
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 Response
When a Project Object is returned from a method, it will include the following fields:
Field | Description |
---|---|
id | A unique numeric identifier for the project within the system. |
name | The project’s display name. |
description | The project’s description. |
mediaCount | The number of different medias that have been uploaded to the project. |
created | The date that the project was originally created. |
updated | The date that the project was last updated. |
hashedId | A private hashed id, uniquely identifying the project within the system. |
anonymousCanUpload | A boolean indicating whether or not anonymous uploads are enabled for the project. |
anonymousCanDownload | A boolean indicating whether or not anonymous downloads are enabled for this project. |
public | A boolean indicating whether the project is available for public (anonymous) viewing. |
publicId | If 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": "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. </p>\n<p>\n\n </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 Name | Description |
---|---|
name (required) | The name of the project you want to create (required). |
adminEmail | The email address of the person you want to set as the owner of this project. Defaults to the Wistia Account Owner. |
anonymousCanUpload (optional) | A flag indicating whether or not anonymous users may upload files to this project. Set to “1” to enable and “0” to disable. |
anonymousCanDownload (optional) | A flag indicating whether or not anonymous users may download files from this project. Set to “1” to enable and “0” to disable. |
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": "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:
Parameter Name | Description |
---|---|
name | The project’s new name. |
anonymousCanUpload | A flag indicating whether or not anonymous users may upload files to this project. Set to “1” to enable and “0” to disable. |
anonymousCanDownload | A flag indicating whether or not anonymous users may download files from this project. Set to “1” to enable and “0” to disable. |
public | A 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",
"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.
Parameter Name | Description |
---|---|
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": "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
Field | Description |
---|---|
id | Unique numeric identifier for the sharing object. |
isAdmin | Whether the user has admin rights on the project. |
canShare | Whether the user is allowed to share the project with others. |
canDownload | Whether the user is allowed to download files from the project. |
canUpload | Whether the user is allowed to upload files to the project. |
share | An 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. |
project | An 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
Field | Description |
---|---|
id | A unique numeric identifier for the Contact or ContactGroup. |
name | The display name of this Contact or ContactGroup. |
type | A string representing what type of share this object represents: Contact or ContactGroup . |
If 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 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.
Parameter | Description |
---|---|
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 Name | Description |
---|---|
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 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 Response
Field | Description |
---|---|
id | A unique numeric identifier for the media within the system. |
name | The display name of the media. |
type | A string representing what type of media this is. Values can be Video, Audio, Image, PdfDocument, MicrosoftOfficeDocument, Swf, or UnknownType. |
status | Post 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. |
section | The title of the section in which the media appears. This attribute is omitted if the media is not in a section (default). |
thumbnail | An object representing the thumbnail for this media. The attributes are URL, width, and height. |
duration | Specifies the length (in seconds) for audio and video files. Specifies number of pages in the document. Omitted for other types of media. |
created | The date when the media was originally uploaded. |
updated | The date when the media was last changed. |
assets | An array of the assets available for this media. See the table below for a description the fields in each asset object. |
embedCode | DEPRECATED: If you want to programmatically embed videos, follow the construct an embed code guide. |
description | A description for the media which usually appears near the top of the sidebar on the media’s page. |
hashed_id | A 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
Field | Description |
---|---|
url | A direct-access URL to the content of the asset. |
width | The width of this specific asset, if applicable. |
height | The height of this specific asset, if applicable. |
fileSize | The size of the asset file that’s referenced by url, measured in bytes. |
contentType | The asset’s content type. |
type | The internal type of the asset, describing how the asset should be used. Values can include OriginalFile, FlashVideoFile, MdFlashVideoFile, HdFlashVideoFile, Mp4VideoFile, MdMp4VideoFile, HdMp4VideoFile, IPhoneVideoFile, StillImageFile, SwfFile, Mp3AudioFile, and LargeImageFile. |
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.
Parameter | Description |
---|---|
project_id | An integer specifying the project from which you would like to get results. |
name | Find a media or medias whose name exactly matches this parameter. |
type | A string specifying which type of media you would like to get. Values can be Video, Audio, Image, PdfDocument, MicrosoftOfficeDocument, Swf, or UnknownType. |
hashed_id | Find the media by hashed_id. |
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. </p>\n<p>\n\n </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
Parameter Name | Description |
---|---|
name | The media’s new name. |
new_still_media_id | The 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. |
description | A 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",
"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
Parameter | Description |
---|---|
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 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:
Field | Description |
---|---|
id | A unique numeric identifier for the video within the system. |
hashed_id | A unique alphanumeric identifier for the video within the system. |
name | The display name of the video. |
stats | An object representing the aggregated embed statistics for this video. |
Here is the definition of each field in the stats object:
Field | Description |
---|---|
pageLoads | The total number of times that the page containing the embedded video has been loaded. |
visitors | The number of unique visitors to the page containing the embedded video. |
percentOfVisitorsClickingPlay | This 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. |
plays | The total number of times that the video has been played. |
averagePercentWatched | This 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
}
}
Account
GET https://api.wistia.com/v1/account.json
The Response
Field | Description |
---|---|
id | Numeric id of the account |
name | Account name |
url | Account’s main Wistia URL (e.g. http://brendan.wistia.com ) |
mediaCount | The total number of medias in this account |
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
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
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:
Field | Description |
---|---|
language | A 3 character language code as specified by ISO-639–2. |
captions | The 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
Parameter | Description |
---|---|
caption_file | Either an attached SRT file or a string parameter with the contents of an SRT file. |
language | An 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.
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:
Field | Description |
---|---|
language | A 3 character language code as specified by ISO-639–2. |
captions | The 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.
Parameter | Description |
---|---|
caption_file | Either 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
This method is for purchasing English captions on a video.
POST https://api.wistia.com/v1/medias/<media-hashed-id>/captions/purchase.json
Parameter | Description |
---|---|
automated | Set to true to order computer-generated captions ($0.25/minute) or false to order human-generated captions ($2.50/minute). Defaults to false . |
rush | Set 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_enable | Set 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.