Skip to main content
Version: 56.0.0

Create an upload

POST 
/api/v1/uploads

Creates an upload: temporary file content of the caller, which only the caller can see or use, transferred before a document is created from it with primaryFile.uploadId. See Uploading files.

The request uses one of two forms, which create the same upload:

  • an application/json body with the filename and the declared size;
  • the tus 1.0.0 creation form, which a stock tus client sends: an empty body with Upload-Length and the filename in the filename key of Upload-Metadata, or in its name key when filename is absent. A request carrying Upload-Length uses this form.

The media type is derived from the filename's extension; a client-declared media type, such as the filetype metadata key, is ignored. The declared size is limited to 24 MiB by default, and an environment can configure a different limit. The declared sizes of a user's open uploads can total 1 GiB by default, and an environment can configure a different size. An upload expires 24 hours after its creation by default, whether or not its content is complete.

Request​

Responses​

The upload was created with status receiving. Send its content to the Location URL with PATCH.

Response Headers
    Cache-Control

    no-store, so no cache answers with an outdated offset.

    Location

    The upload's URL, /api/v1/uploads/{id}, which is also its tus upload URL.

    Tus-Resumable

    The tus protocol version. Every response of an upload operation carries it, Problem responses included, except a 406.

    Upload-Expires

    The upload's expiration time as an HTTP-date.

    Upload-Length

    The upload's declared size in bytes.

    Upload-Metadata

    The filename key with the upload's filename in base64.

    Upload-Offset

    The number of bytes the upload has received and stored, at which the next PATCH continues.