Skip to content
Data Ocean

Upload a file

Uploading a file is a core function in Data Ocean file management. Data Ocean supports these types of uploads:

  • Singlepart files are uploaded in a single upload. This is a basic file upload.
  • Multipart files are divided into chunks for resumable uploads and to allow faster uploads for low-bandwidth connections. After each part is loaded, the complete action recompiles the file.
  • Filesets are collections of files managed through a single file object.

The overall size of any file upload can never exceed 5 TB. Larger files can be uploaded as multipart files to break them into 5 MB - 5 GB chunks and support resumable uploading of files.

The following status values can be returned during the upload process:

  • UPLOADABLE

This file has not been uploaded yet.

  • FINALIZING

Multipart and copy only. The file parts have been uploaded and are being reassembled.

  • AVAILABLE

The file is available for download.

  • DELETING

The file is being deleted. Existing links may continue to function until this delete has been processed.

  • UPLOAD_FAILED

An upload was received, but was not compatible with the intended use of the file. This typically occurs when an unsupported archive type is used for an archive upload.

It takes subseconds for file status to change. It is recommended that you check the file state (GET by file ID) before uploading and downloading a file.

Diagram

Use the following steps to upload a singlepart file to Data Ocean.

Tip: Plan your file structure ahead of time. Use the path parameter to easily and immediately organize files into a directory structure. Include a path before the file name to automatically create a directory the first time that path is used. Upload additional files using the same base path to group files into a directory.

1. Create a new file object

Section titled “1. Create a new file object”
  • API call:
POST {base URL}/api/files

  • Headers:

    • Accept: application/json

    This may be automatically added by your development tool. Postman and curl add this header to all requests.

    • Content-Type: application/json
    • Authorization: Bearer {bearer token}
    • Include the Trimble Identity OAuth Bearer token for your application.

  • BODY:

    • path: {name of file and location of file}
    • regions: {regions}

Use the path to name your file and set the file location to organize your files.

Base your body on the Example Request code sample below. This example shows the minimum required request body, see API Definition for parameter details and additional optional parameters.

:::note[Example request body:]
:::
```
{
    "file": {
        "path": "/user/examplefile.pdf",
        "regions": ["us1"]
    }
}
```






After the operation is completed, the JSON response includes the id value for the file and URLs for your file upload and download.

2. Upload your file

Section titled “2. Upload your file”

Perform a PUT operation with the upload URL from the POST call in the previous step.

  • API CALL:
PUT {UPLOAD URL}
  • BODY: {File Content}
  • The upload code varies by language. For signed URLs, use these AWS code examples for reference.
  • expires_at = {optional}

If this value is not set, file will not be deleted.

  • If you are are uploading a support file, please add the master_id in the payload.

3. Validate the upload

Section titled “3. Validate the upload”

Run a GET API call to check the status. The value should be AVAILABLE.

  • API CALL:
GET {base URL}/api/files/{id}

—OR—

GET {base URL}/api/files/api/files?path={file_path}

  • HEADER:

    • Accept: application/json
    • Value: Bearer {bearer token}

    Include Trimble Identity v3 OAuth Bearer token for your application.

Reference Materials

Data Ocean API definition