Wistia Upload API

The Upload API is the best way to programmatically get new videos and files into your Wistia account.

If you are looking to have site visitors upload content, you should create a new access token with upload permissions for that.

Uploading to Wistia

To upload a file from your computer, supply the required parameters and POST your media file to https://upload.wistia.com as multipart-form encoded data.

Uploaded media will be visible immediately in your account, but may require processing (as is the case for uploads in general).

Importing Web-hosted Content to Wistia

To import a file from another web server (such as Amazon S3, Dropbox, or other cloud service), supply the required parameters as a standard form-url encoded POST to https://upload.wistia.com.

The file URL must end in the correct file extension, for example “.mp4.” Imported media will also require some processing time, which varies depending on the file size and connection speed.

Authentication

• All upload requests must use SSL (https://, not http://).
• The required access_token should be added to the head of the request as a bearer token. You can find an example here.

The Request

POST https://upload.wistia.com

All parameters (with the exception of file and access_token) may be encoded into the request body or included as part of the query string.

The file parameter must be multipart-form encoded into the request body.

The access_token must be included in the request header.

Examples

cURL is a great way to try out the Upload API and an excellent method of uploading files to Wistia via the command line.

Uploading a media file with cURL

$ curl -i -H "Authorization: Bearer YOUR_TOKEN_HERE" -F file=@<LOCAL_FILE_PATH> https://upload.wistia.com/

We expect a multipart/form-data POST to the server, with both file and access_token parameters. Feel free to tack on additional parameters, like name and project_id:

$ curl -i -H "Authorization: Bearer YOUR_TOKEN_HERE" -F name=<NAME> -F project_id=<PROJECT_ID> -F file=@<LOCAL_FILE_PATH> https://upload.wistia.com/

Importing a media file via URL with cURL

$ curl -i -H "Authorization: Bearer YOUR_TOKEN_HERE" -d "url=<REMOTE_FILE_PATH>" https://upload.wistia.com/

We expect an application/x-www-form-urlencoded POST to the server, with the url param and a provided access token.

If your URL includes multiple query parameters, you will need to encode it. This is important for pre-signed Amazon Web Services S3 URLs, for example.

$ curl -i -H "Authorization: Bearer YOUR_TOKEN_HERE" --data-urlencode "url=<REMOTE_FILE_PATH>" https://upload.wistia.com/

Using the OAuth2 Access Token

If you are using the access_token param with OAuth2, it should be provided in the header, like:

curl -i -H "Authorization: Bearer YOUR_TOKEN_HERE" https://upload.wistia.com/

If you are importing the media file via URL, you can also include the access_token as a POST param.

Response Format

For successful uploads, the Upload API will respond with an HTTP-200 and the body will contain a JSON object.

• HTTP 200 [application/json] Success. A JSON object with media details.
• HTTP 400 [application/json] Error. A JSON object detailing errors.
• HTTP 401 [text/html] Authorization error. Check your access_token.

The most common error that all implementations should beware of is a 400 due to reaching the video limit of your account. Not all accounts have video limits, but for those that do, you will receive a 400 response with JSON like:

{
  "error": "This account has exceeded its video limit. Please upgrade to upload more videos."
}

Example Response

{
  "id":2208087,
  "name":"dramatic_squirrel.mp4",
  "type":"Video",
  "created":"2012-10-26T16:47:09+00:00",
  "updated":"2012-10-26T16:47:10+00:00",
  "duration":5.333000183105469,
  "hashed_id":"gn69c10tqw",
  "progress":0.0,
  "thumbnail":
  {
    "url":"http://embed.wistia.com/deliveries/ffbada01610466e66f67a5dbbf473ed6574a6405.jpg?image_crop_resized=100x60",
    "width":100,
    "height":60
  }
}

This data structure may change in future releases.

Using the Upload API with Dropbox

Dropbox has a few options for different URL parameters to get a downloadable file from their service. These involve either adding query parameters to the URL or modifying the URL directly. Currently the Wistia Upload API only supports the directly modified URLs.

Examples of supported URLs:

• Adding dl before dropbox in the URL so the link looks like https://dl.dropbox.com/s/<dropbox-id>/<asset-name>.mp4
• Adding raw/ after the /s/ in the URL so the link looks like https://dropbox.com/s/raw/<dropbox-id>/<asset-name>.mp4

Examples of unsupported URLs:

• Adding ?dl=1 or ?dl=0 as query parameters
• Adding ?raw=1 as a query parameter

Examples Using Ruby

All media uploaded via https://upload.wistia.com must be transferred as multipart-form encoded data inside the body of an HTTP-POST. This can be achieved in Ruby quite simply using the ’multipart-post' gem.

Installation:

$ gem install multipart-post

Example Code

# upload_ruby_gem.rb
require 'net/http'
require 'net/http/post/multipart'

def post_video_to_wistia(name, path_to_video)
  uri = URI('https://upload.wistia.com/')

  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  # Construct the request.
  request = Net::HTTP::Post::Multipart.new uri.request_uri, {
    'access_token' => '<ACCESS_TOKEN>',
    'contact_id'   => '<CONTACT_ID>', # Optional.
    'project_id'   => '<PROJECT_ID>', # Optional.
    'name'         => '<MEDIA_NAME>', # Optional.

    'file' => UploadIO.new(
                File.open(path_to_video),
                'application/octet-stream',
                File.basename(path_to_video)
              )
  }

  # Make it so!
  response = http.request(request)

  return response
end

There’s a Gem For That

To make using the Upload API even easier, we created a Ruby gem that lets you use it via the command line!

AJAX Examples

An example of uploading a file from a URL using jQuery. It’s advisable to generate an API token from your account with upload-only permissions for this.

<!-- ajax_file_upload.html -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.2.0/jquery.min.js"></script>
<script>
  var access_token = "API token with upload permission";
  var url = "Your video file URL";
  var requestData = jQuery.param({
    url: url
  });

  $.ajax({
    type:'POST',
    url: 'https://upload.wistia.com',
    data: requestData,
    headers: { Authorization: `Bearer ${access_token}` }
    contentType: 'application/x-www-form-urlencoded',
    cache: false,
    processData: false,
    success:function(data) {
      console.log(data);
      alert('Success!');
    },
    error: function(data) {
      console.log(data);
      alert('Error');
    }
  });
</script>