Upload a File with a Generated Resumable File Upload URL

To upload a file to a site's Media Manager with a URL that allows you to pause and resume an upload, you can call Generate File Resumable Upload URL. This call returns a signed uploadUrl and uploadToken that you can then use to upload a file.

Notes:

  • If you don't specifically need a resumable upload experience, you can call one of the following options instead of calling Generate File Resumable Upload URL:

Upload flow

The code for generating an upload URL and sending it an upload request varies depending on your context. For example, the code for a dashboard page of a self-hosted app differs slightly from the code for a headless site.

However, in all scenarios, you need to perform the following steps:

  1. Get the file to upload.
  2. Get the name of the file.
  3. Get the MIME type of the file.
  4. Generate an upload URL and upload token using the Generate File Resumable Upload URL method.
  5. Create a new tus upload using the generated upload URL.
  6. Start the tus upload.
  7. When the tus upload completes successfully, send a PUT request to finalize the upload. Append the upload token to the generated upload URL path and add the file name as a query parameter.

Create a tus upload

To create a resumable upload experience, use a tus client. There are tus client implementations available for many popular languages.

After generating an uploadUrl by calling Generate File Resumable Upload URL, use a tus client to create a tus upload with the following information:

  • File: Specify the file to upload.
  • endpoint: The uploadUrl returned from the call to Generate File Resumable Upload URL.
  • metadata Specify the following metadata:
    • filename: The name of the file to upload.
    • contentType: The MIME type of the file to upload.
    • token: The upload token returned from the call to Generate File Resumable Upload URL.

Call the upload URL

After the tus upload completes successfully, call the uploadUrl using the following information:

  • HTTP method: PUT.
  • URL: The uploadUrl followed by a / and the uploadToken.
  • Query parameters: filename with the name of the file, including the extension. The filename parameter is optional if fileName was already provided in the Generate File Resumable Upload URL call.

Note: You need to determine the file's MIME type before uploading. For example, in Node.js you can use the mime-types library or the file-type package. Other languages and platforms have equivalent libraries for detecting MIME types.

Upload URL response

When the upload is successful, Wix returns information about the file being uploaded.

Uploading files takes time. Receiving a successful response from a call to the uploadUrl doesn't mean that the upload is complete. To run code when the upload finishes, listen for the File Ready and File Failed events. Learn more about knowing when a file is ready.

Example

The following example code shows the calls to generate a resumable upload URL and use it to upload an image file. How you make those calls depends on the context in which you're writing that code.

You also need to write code that performs the other steps in the upload flow to retrieve the information you need to provide when making the calls shown below.

Generate an upload URL

To generate an upload URL, you need to send a POST request to Generate File Resumable Upload URL, specifying the MIME type of the file.

Copy

The response contains a signed uploadUrl and an uploadToken.

Use a generated resumable URL to upload a file

After generating an uploadUrl and uploadToken, use a tus client to upload the file. When the tus upload completes, make a PUT request to finalize the upload.

This example uses tus-js-client to implement the resumable upload:

Copy

Example response

A call to a generated uploadUrl returns a response structured as follows:

Copy

See also

Did this help?