Skip to content

Uploading

Uploading allows new files to be made accessible in the API. Once a file has been uploaded, it can be used in a query operation or as input to a job.

Supported file types and endpoints

The types of files that can be uploaded (and their associated endpoints) are:

Upload a file

Upload a new file to the API.

Route: /v3{instance-uri}{files-endpoint} (see supported file endpoints)
Method: POST
Encoding: multipart/form-data

Required form parameters (either one of these can be used, but not both):

  • "file" - The file to be uploaded.
  • "file_url" - A public URL to the file to be uploaded.

Optional form parameters:

  • "attributes" - JSON-encoded string containing a dictionary of attributes and their values. For more details, refer to the section on setting attribute values when uploading.
  • "custom_attributes" - JSON-encoded string containing a dictionary of custom attributes and their values. For more details, refer to the section on setting attribute values when uploading.
  • "folders" - JSON-encoded string containing a list of folder URIs, which adds the file to the one or more folders upon successful completion of the upload.

Upon successfully uploading a file, the response will contain the details of the newly uploaded file.

Start multipart upload of a file

Indicate that a new file will be uploaded to the API in parts. In contrast to uploading a file in a single operation, a multipart upload enables a file to be broken apart and uploaded as a set of smaller files. This is useful if the upload of a very large file is expected to fail.

Route: /v3{instance-uri}{files-endpoint}/start-multipart-upload (see supported file endpoints)
Method: POST
Encoding: multipart/form-data

Required form parameters:

  • "file_name" - The name of the file (including its file extension) to be uploaded.
  • "total_parts" - The total number of file parts that will be uploaded for this file.

Optional form parameters:

Upon successfully starting a multipart upload, the response will contain the details (and URI) of the newly created file that will be uploaded. Once this new file is created, the file can begin to be uploaded in parts using its URI.

Upload part of a file

Upload a part of a file that corresponds to a multipart upload. Parts should typically be uploaded in order, as when the last part of the file is uploaded (based on the part index), the API will attempt to assemble the whole file. Parts should be created by dividing the whole file into separate smaller files (optionally of different sizes), where the whole file can be reassembled by concatenating those smaller files in order.

Route: /v3{instance-uri}{file-uri}
Method: POST
Encoding: multipart/form-data

Required form parameters:

  • "part" - The index of this part file (counting starts at 1).
  • "file" - The part file to be uploaded.

Upon successfully uploading a part of a file, the response will contain the updated details of the file.