Making API Requests

Learn how to get started and use Wistia APIs.

πŸ“

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.

Getting started

Creating and managing access tokens

πŸ“˜

Important

The API tokens page in an account is only accessible to the Account Owner. If you need to access, create, or update an API token, contact the Account Owner.

When your Wistia account is created, a default 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, and you can generate additional access tokens with custom permissions as well. Keep these tokens secret! do not put them in client-side code or commit them to a Github repository.

screenshot of the default 'master token' in the API access page

The master token is simply a default API token with full permissions. It is ok to edit or delete this token.

You can edit a token to change its permissions, or delete a token entirely, from the "..." icon next to each token. Additionally, you can create a new token with a custom nickname and scope by clicking on the New token button at the top of the page.

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

API authentication

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

Authentication of API requests must be done with an HTTP "Authentication" header.

The supported way to access the API is via Bearer Token:

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

API versions

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

Passing parameters with a request

For non-GET requests, all parameters should be passed in the body of the request and URL encoded. For GET requests, parameters must be passed via the query string - that is, appended to the end of the URL after a question mark (?) character.

API response format

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 requests

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 limit

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 429 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:

ParameterDescription
pageSpecifies which page of the results you want to see. Defaults to 1 (not 0).
per_pageThe 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:

ParameterDescription
sort_byThe name of the field to sort by. Valid values are name, created, or updated. Defaults to sorting by Project ID.
sort_directionSpecifies 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