An upload token is used to upload a file to the platform via HTTP or HTTPS. First, an upload token must be created using the Create action, which returns a token and the URL to upload the file to, as well as the hashes of the item and file that will be created when the upload succeeded. It might also return an HTTPS URL that can be used to upload securely. However, this might be disabled on a platform, so one should always check to see if the HTTPS URL is returned.

The file can then be uploaded to the given URL using a HTTP POST request. The POST-data must have a multipart/form-data mime-type, and must contain the following fields:

uploadtoken The upload token as received from the API; note that this is case sensitive.
uploadfile The actual file which is uploaded, as if it was uploaded from a HTML form with input type file.
returnurl The URL where the user will be redirected after the upload. If an error occured, ?error=(some error code) is appended to this URL. If not specified, no output will be given, unless ajax is set. (optional)
ajax If set (and returnurl is not set), a JSON object will be returned with at least the field success, which is true if and only if the upload was done successfully. If an error occurred, a field error will contain some error code. (optional)
title When creating a new item, the title of this item; ignored when no new item is created. (optional)
author When creating a new item, the author of this item; ignored when no new item is created. (optional)
description When creating a new item, the description of this item; ignored when no new item is created. (optional)
archived By default the newly uploaded file will be marked as archived. Set this field to 0 to not mark it as such. (optional, default = 1)
replaceitem When adding a file to an existing item, if given, the ID of the item to replace the files of. This will archive all current files of that item after transcoding of the new file completes. (optional)
categories When creating a new item, categories to add the item to. Can be either one category ID or comma separated list of category ID’s. (optional)
itemarchived By default newly created items will not be archived (note: this is not the same as archiving a file, which will be done by default). When creating a new item, this value can be set to 1, which will immediately archive the newly created item. (optional, default = 0)
keywords When creating a new item, comma separated list of keywords to add to the new item. (optional)
transcodeprofilegroup When creating a new item or replacing one, the ID of a transcode profile group to use to transcode the uploaded file. (optional, defaults to default transcode profile groups in the account of the uploader)

The following actions are defined for this command: