---
updatedAt: 2025-11-11T16:35:42.000Z
agentTools:
  projectIndex: https://docs.wistia.com/llms.txt
---

# Getting Started with the 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](https://wistia.com/support/account/setup#api-access) 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).

<Callout icon="📝" theme="default">
  ### 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.
</Callout>

## 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.

## Importing Alternate Audio Localizations

To import an alternate audio file for a localization language you must use the additional request parameters *localization\_language* and *localization\_media\_id*. *localization\_language* must be a valid IETF language tag. *localization\_media\_id* must be the alphanumeric hashed ID of a media owned by the account the upload auth token belongs to.

*overwrite\_existing\_localization=true* may be used to replace an existing localization.

#### Example

```sh
curl -v -i -H "Authorization: Bearer <your_token>" --data-urlencode "url=https://my.video.host.com/videos/my_video.mp4" -d "localization_media_id=abcde12345" -d "localization_language=es-419" https://upload-v2.wistia.com
```

## 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](https://docs.wistia.com/docs/making-api-requests#authentication).

## 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.

**While most uploads will be picked up immediately, there is a possibility for a delay due to high traffic or system maintenance. If`url` includes an authorization grant (like a presigned S3 URL would) then we suggest that you configure the grant to be valid for at least a few hours. This will ensure that we'll still be authorized to download your content when the upload runs.**

## Examples

[cURL](http://curl.haxx.se/) 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**

```sh
$ 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`:

```sh
$ 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**

```sh
$ 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.

```sh
$ 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](https://docs.wistia.com/docs/authenticating-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.

## Video Limit

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:

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