Skip to content

Upload files

To upload files to File Service, an upload object needs to be created. The upload object includes the file name, parent id, and whether the file is a multipart file. The upload object will return an upload URL that can be used to upload the file content.

Files can be uploaded as a single part or in multiple parts.

  • 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 merges the parts back into a single file.
  • An Upload object is deleted 30 days after creation, its associated file is unaffected.

  • The overall size of any file upload may not exceed 5 TB.

  • Name of the file has the following restrictions

    • Name cannot begin with /
    • Length should be less than 255 characters
    • Name should not be reserved keywords like con, nul, prn, aux, ?, <, >, *, |, .
    • Name also should not be com or lpt followed by digits 1 to 9 (e.g, com1 to com9 and lpt1 to lpt9)

Each upload url should only be used once (except in the case of retrying failed uploads). If several successful uploads are executed against the same upload url, content from one of the uploads will be randomly selected for permanent storage.

By default, upload URLs are valid for 60 minutes. The validity period can be customized by setting the urlDuration query parameter. The url duration may be between five minutes(5m) and seven days(7d).

NOTE

The permissions check for uploads occurs during the create upload request. There is no check when the content is uploaded using the pre-signed url.

  • A space should be created. To know more about creating a space refer here
  • The maximum file size for a singlepart upload is 5 GB.
POST {baseUrl}/spaces/{spaceId}/uploads
  • HEADER:

    • Authorization: Bearer {tid token}
  • BODY:

    • name - Name of file
    • parentId - Parent id for the file where it needs to be created
Example request body
{
        "name" : "test",
"parentId" : "e492c129-141d-4679-b0a7-829580679b6a"
}

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

Example response
{
"createdAt": "2024-06-24T09:31:19Z",
"createdByTrn": "trn:tid:application:fae7a6aa-cf9b-42ad-945b-a89d1c1ec580",
"fileInputUploadDetails": {
"permissionsLocal": {
"inherits": true,
"acl": [
{
"actor": "trn:tid:application:fae7a6aa-cf9b-42ad-945b-a89d1c1ec580",
"role": "contentManager"
}
]
},
"fileId": "e492c129-141d-4679-b0a7-829580679b6a",
"fileset": false,
"metadata": {
"testkey": "testvalue"
},
"multipart": false,
"name": "Hettingerstad",
"parentId": "24f92ed9-74be-4556-bfb3-ab037fdb08a1",
"path": "/test125/Hettingerstad",
"restrictedAccess": false,
"spaceId": "cbbf270b-a8cb-450b-8192-495cf252d921",
"upload": {
"type": "SINGLEPART",
"url": "https://us-aws-wo.dev.fileservice.trimblecloud.com/fs_s/e492c129-141d-4679-b0a7-829580679b6a.a257f7d4-5fd8-4300-8d9a-1b611771be4b?Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly91cy1hd3Mtd28uZGV2LmZpbGVzZXJ2aWNlLnRyaW1ibGVjbG91ZC5jb20vZnNfcy9lNDkyYzEyOS0xNDFkLTQ2NzktYjBhNy04Mjk1ODA2NzliNmEuYTI1N2Y3ZDQtNWZkOC00MzAwLThkOWEtMWI2MTE3NzFiZTRiIiwiQ29uZGl0aW9uIjp7IkRhdGVMZXNzVGhhbiI6eyJBV1M6RXBvY2hUaW1lIjoxNzE5MjI1MDc5fX19XX0_&Signature=PGejC2lqBmwoBieqdcyE3xUNx6XQ9tb1GJxHCBGmdknA~5KYj11W37m6JebYBJNjfY~d2WFNzLuNZKLLudCM57CmM3pIWaGBinDN3Msb5dz3gmbBVQeGw1pwDQZFV66fdgCmcA6iYzpNeAaqmEZt-AnBqpQbBTA8IC~Y2OlxSnRMwFM5v4iD4e2Uifxj0zymVTEaKKoZhNLVi3x5EqmCMZrCdG3AQncwdqbqoNlRdysNPg0m01jGRNBUdWIDg6oK-GlS5WWdj3NC0BTwxWe-moGFT9YXiAZn3ZTOUpwSIbmDy~uLjAmUVSmdilpho37Pko9LO5WpbBe2ixUnc1a4FQ__&Key-Pair-Id=APKAI6JAFOBXQEFCLCSQ"
}
},
"id": "a257f7d4-5fd8-4300-8d9a-1b611771be4b",
"resourceTrn": "trn:2:fileservice:<region>:upload:a257f7d4-5fd8-4300-8d9a-1b611771be4b",
"updatedAt": "2024-06-24T09:31:19Z",
"updatedByTrn": "trn:tid:application:fae7a6aa-cf9b-42ad-945b-a89d1c1ec580"
}

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

PUT {UPLOAD URL}
  • BODY: {File Content}

Run a GET upload API call to check the job status. The value should be COMPLETED.

GET {baseUrl}/spaces/{spaceId}/uploads/{uploadId}
  • HEADER:

    • Authorization: Bearer {tid token}
Example response
{
"id": "e28982f5-ebd8-4a76-97f4-0783fc143f30",
"fileInputUploadDetails": {
"fileId": "e28982f5-ebd8-4a76-97f4-0783fc143f30",
"spaceId": "f85bc802-5481-4581-b972-c4652d595ec7",
"name": "FileName.ext",
"permissionsLocal": {
"inherits": true,
"acl": [
{
"actor": "trn:tid:user:6529d0b3-5856-41ab-88b3-86f7955cddf1",
"role": "contentManager"
},
{
"actor": "trn:tid:user:7529d0b3-5856-41ab-88b3-86f7955cddf1",
"role": "contentManager"
}
]
},
"upload": {
"url": "https://example.com/upload/12345678-90ab-cdef-1234-567890abcdef.1",
"type": "SINGLEPART"
},
"parentId": "e28982f5-ebd8-4a76-97f4-0783fc143f30",
"path": "testA/testB/FileName.ext",
"fileset": false,
"restrictedAccess": false,
"expiresAt": "2024-01-01T12:25:00.000Z",
"metadata": {
"language": "Suomi"
},
"multipart": false,
"responseHeaders": {
"response-content-type": "image/jpeg",
"response-content-disposition": "inline",
"response-cache-control": "max-age=3000"
},
"applicationId": "f85bc802-5481-4581-b972-c4652d595ec7"
},
"createdAt": "2023-05-30T10:30:00Z",
"createdByTrn": "trn:tid:application:f85bc802-5481-4581-b972-c4652d595ec7",
"updatedAt": "2023-05-30T10:30:00Z",
"updatedByTrn": "trn:tid:application:f85bc802-5481-4581-b972-c4652d595ec7"
}
  • The minimum size for a multipart upload part is 5 MB (except for the last part, which may be less than 5 MB).
  • The maximum part size is 5 GB.
  • The number of parts of a multipart upload cannot exceed 10,000.

Note

  • If the cloud provider for the space is AWS, the multipart upload request will return an ETag value, which must be included, along with the corresponding part identifier, in the multipart upload completion request.
  • If the cloud provider for the space is Azure, ETag value might be similar for the all part uploads and tags has no effect.
POST {baseUrl}/spaces/{spaceId}/uploads
  • HEADER:

    • Authorization: Bearer {tid token}
  • BODY:

    • name - Name of file
    • parentId - Parent id for the file where it needs to be created
    • multipart - Boolean value to indicate if the file needs to be created as a multipart file
Example request body
{
        "name" : "test",
"parentId" : "e492c129-141d-4679-b0a7-829580679b6a",
"multipart" : true
}

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

Example response
{
"createdAt": "2024-06-24T09:31:19Z",
"createdByTrn": "trn:tid:application:fae7a6aa-cf9b-42ad-945b-a89d1c1ec580",
"fileInputUploadDetails": {
"permissionsLocal": {
"inherits": true,
"acl": [
{
"actor": "trn:tid:application:fae7a6aa-cf9b-42ad-945b-a89d1c1ec580",
"role": "contentManager"
}
]
},
"fileId": "e492c129-141d-4679-b0a7-829580679b6a",
"fileset": false,
"metadata": {
"testkey": "testvalue"
},
"multipart": true,
"name": "Hettingerstad",
"parentId": "24f92ed9-74be-4556-bfb3-ab037fdb08a1",
"path": "/test125/Hettingerstad",
"restrictedAccess": false,
"spaceId": "cbbf270b-a8cb-450b-8192-495cf252d921",
"upload": {
"type": "MULTIPART",
"url": "https://us-aws-wo.dev.fileservice.trimblecloud.com/fs_s/e492c129-141d-4679-b0a7-829580679b6a.a257f7d4-5fd8-4300-8d9a-1b611771be4b?Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly91cy1hd3Mtd28uZGV2LmZpbGVzZXJ2aWNlLnRyaW1ibGVjbG91ZC5jb20vZnNfcy9lNDkyYzEyOS0xNDFkLTQ2NzktYjBhNy04Mjk1ODA2NzliNmEuYTI1N2Y3ZDQtNWZkOC00MzAwLThkOWEtMWI2MTE3NzFiZTRiIiwiQ29uZGl0aW9uIjp7IkRhdGVMZXNzVGhhbiI6eyJBV1M6RXBvY2hUaW1lIjoxNzE5MjI1MDc5fX19XX0_&Signature=PGejC2lqBmwoBieqdcyE3xUNx6XQ9tb1GJxHCBGmdknA~5KYj11W37m6JebYBJNjfY~d2WFNzLuNZKLLudCM57CmM3pIWaGBinDN3Msb5dz3gmbBVQeGw1pwDQZFV66fdgCmcA6iYzpNeAaqmEZt-AnBqpQbBTA8IC~Y2OlxSnRMwFM5v4iD4e2Uifxj0zymVTEaKKoZhNLVi3x5EqmCMZrCdG3AQncwdqbqoNlRdysNPg0m01jGRNBUdWIDg6oK-GlS5WWdj3NC0BTwxWe-moGFT9YXiAZn3ZTOUpwSIbmDy~uLjAmUVSmdilpho37Pko9LO5WpbBe2ixUnc1a4FQ__&Key-Pair-Id=APKAI6JAFOBXQEFCLCSQ"
}
},
"id": "a257f7d4-5fd8-4300-8d9a-1b611771be4b",
"updatedAt": "2024-06-24T09:31:19Z",
"updatedByTrn": "trn:tid:application:fae7a6aa-cf9b-42ad-945b-a89d1c1ec580"
}

There is a query string parameter “partNumber=*” in the upload URL from the previous request. Substitute the “*” value with the number of the current part that needs to be uploaded.

Separate the file into parts, and upload each to the URL with parameter value substituted. Part numbering starts with "1" (not zero).

PUT {UPLOAD URL}
  • BODY
{PART DATA}

Response will include an ETag in the header. Keep track of the ETag responses for each upload.

After all parts are uploaded, run the API call to complete the multipart upload. Use the upload id from the first step.

PATCH /spaces/{spaceId}/uploads/{uploadId}
  • HEADER:

    • Authorization: Bearer {tid token}
  • BODY:

    • etag - ETag generated from aws
    • partNumber - Part number of the uploaded file
Example request body
{
{
"parts": [
{
"etag": "107a11224699641f1366c00ddac5e06b",
"partNumber": "1"
},
{
"etag": "e28982f5-ebd8-4a76-97f4-0783fc143f30",
"partNumber": "2"
}
]
}
}
Example response
{
"id": "e28982f5-ebd8-4a76-97f4-0783fc143f30",
"fileInputUploadDetails": {
"fileId": "e28982f5-ebd8-4a76-97f4-0783fc143f30",
"metadata": {
"language": "Suomi"
},
"multipart": true,
"responseHeaders": {
"response-content-type": "image/jpeg",
"response-content-disposition": "inline",
},
"applicationId": "f85bc802-5481-4581-b972-c4652d595ec7"
},
"result": {
"message": "Upload job is COMPLETED",
"status": "COMPLETED"
},
"createdAt": "2023-05-30T10:30:00Z",
"createdByTrn": "trn:tid:application:f85bc802-5481-4581-b972-c4652d595ec7",
"updatedAt": "2023-05-30T10:30:00Z",
"updatedByTrn": "trn:tid:application:f85bc802-5481-4581-b972-c4652d595ec7"
}

Run a GET upload API call to check the job status. The value should be COMPLETED.

GET {baseUrl}/spaces/{spaceId}/uploads/{uploadId}
  • HEADER:

    • Authorization: Bearer {tid token}
Example response
{
"id": "e28982f5-ebd8-4a76-97f4-0783fc143f30",
"fileInputUploadDetails": {
"fileId": "e28982f5-ebd8-4a76-97f4-0783fc143f30",
"spaceId": "f85bc802-5481-4581-b972-c4652d595ec7",
"name": "FileName.ext",
"permissionsLocal": {
"inherits": true,
"acl": [
{
"actor": "trn:tid:user:6529d0b3-5856-41ab-88b3-86f7955cddf1",
"role": "contentManager"
},
{
"actor": "trn:tid:user:7529d0b3-5856-41ab-88b3-86f7955cddf1",
"role": "contentManager"
}
]
},
"upload": {
"url": "https://example.com/upload/12345678-90ab-cdef-1234-567890abcdef.1",
"type": "SINGLEPART"
},
"parentId": "e28982f5-ebd8-4a76-97f4-0783fc143f30",
"path": "testA/testB/FileName.ext",
"fileset": false,
"restrictedAccess": false,
"expiresAt": "2024-01-01T12:25:00.000Z",
"metadata": {
"language": "Suomi"
},
"multipart": true,
"responseHeaders": {
"response-content-type": "image/jpeg",
"response-content-disposition": "inline",
"response-cache-control": "max-age=3000"
},
"applicationId": "f85bc802-5481-4581-b972-c4652d595ec7"
},
"createdAt": "2023-05-30T10:30:00Z",
"createdByTrn": "trn:tid:application:f85bc802-5481-4581-b972-c4652d595ec7",
"updatedAt": "2023-05-30T10:30:00Z",
"updatedByTrn": "trn:tid:application:f85bc802-5481-4581-b972-c4652d595ec7"
}
  • Support files will always be single-part uploads. Multipart is not supported.
  • Support files may not be filesets.
  • Maximum of 10 support files can be linked to a parent file.
  • Copy links is not supported for package upload
POST {baseUrl}/spaces/{spaceId}/uploads
  • HEADER:

    • Authorization: Bearer {tid token}
  • BODY:

    • name - Name of file
    • parentId - Parent id for the file where it needs to be created
    • resources - List of support files resources that are part of the main file
Example request body
{
        "name" : "test",
"parentId" : "e492c129-141d-4679-b0a7-829580679b6a",
"resources" : [
{
"name": "THUMB"
}
]
}

After the upload operation is completed, the JSON response includes the id value for the file and URLs for file upload for both main file and list of support files.

Example response
{
"createdAt": "2024-06-24T09:31:19Z",
"createdByTrn": "trn:tid:application:fae7a6aa-cf9b-42ad-945b-a89d1c1ec580",
"fileInputUploadDetails": {
"permissionsLocal": {
"inherits": true,
"acl": [
{
"actor": "trn:tid:application:fae7a6aa-cf9b-42ad-945b-a89d1c1ec580",
"role": "contentManager"
}
]
},
"fileId": "e492c129-141d-4679-b0a7-829580679b6a",
"fileset": false,
"metadata": {
"testkey": "testvalue"
},
"multipart": false,
"name": "Hettingerstad",
"parentId": "24f92ed9-74be-4556-bfb3-ab037fdb08a1",
"path": "/test125/Hettingerstad",
"restrictedAccess": false,
"spaceId": "cbbf270b-a8cb-450b-8192-495cf252d921",
"upload": {
"type": "SINGLEPART",
"url": "https://us-aws-wo.dev.fileservice.trimblecloud.com/fs_s/e492c129-141d-4679-b0a7-829580679b6a.a257f7d4-5fd8-4300-8d9a-1b611771be4b?Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly91cy1hd3Mtd28uZGV2LmZpbGVzZXJ2aWNlLnRyaW1ibGVjbG91ZC5jb20vZnNfcy9lNDkyYzEyOS0xNDFkLTQ2NzktYjBhNy04Mjk1ODA2NzliNmEuYTI1N2Y3ZDQtNWZkOC00MzAwLThkOWEtMWI2MTE3NzFiZTRiIiwiQ29uZGl0aW9uIjp7IkRhdGVMZXNzVGhhbiI6eyJBV1M6RXBvY2hUaW1lIjoxNzE5MjI1MDc5fX19XX0_&Signature=PGejC2lqBmwoBieqdcyE3xUNx6XQ9tb1GJxHCBGmdknA~5KYj11W37m6JebYBJNjfY~d2WFNzLuNZKLLudCM57CmM3pIWaGBinDN3Msb5dz3gmbBVQeGw1pwDQZFV66fdgCmcA6iYzpNeAaqmEZt-AnBqpQbBTA8IC~Y2OlxSnRMwFM5v4iD4e2Uifxj0zymVTEaKKoZhNLVi3x5EqmCMZrCdG3AQncwdqbqoNlRdysNPg0m01jGRNBUdWIDg6oK-GlS5WWdj3NC0BTwxWe-moGFT9YXiAZn3ZTOUpwSIbmDy~uLjAmUVSmdilpho37Pko9LO5WpbBe2ixUnc1a4FQ__&Key-Pair-Id=APKAI6JAFOBXQEFCLCSQ"
}
},
"resources": [
{
"fileId": "b6c3356d-5673-4b77-9ba5-5e579b92ea8a",
"name": "THUMB",
"restrictedAccess": true,
"supportFileKey": "THUMB",
"upload": {
"type": "SINGLEPART",
"url": "https://us-aws-wo.dev.fileservice.trimblecloud.com/fs_s/b6c3356d-5673-4b77-9ba5-5e579b92ea8a.c30d80f2-4400-45d2-a9e6-e021e73974fd?Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly91cy1hd3Mtd28uZGV2LmZpbGVzZXJ2aWNlLnRyaW1ibGVjbG91ZC5jb20vZnNfcy9iNmMzMzU2ZC01NjczLTRiNzctOWJhNS01ZTU3OWI5MmVhOGEuYzMwZDgwZjItNDQwMC00NWQyLWE5ZTYtZTAyMWU3Mzk3NGZkIiwiQ29uZGl0aW9uIjp7IkRhdGVMZXNzVGhhbiI6eyJBV1M6RXBvY2hUaW1lIjoxNzMwMTE3Mzk4fX19XX0_&Signature=NIqtBY9BWqgEmYOP87ceM09Nwve8Daew86Qi0wqxeWwLvQ-0IyrmV-Q8B45tGw14KKqiVC8tDgqSwvx4bLU5crrW-OrtqBmlph3aQuGVEV8AEd1U8lDv~7M80i8NTO5zOGj0Axl44yDIcuu1FxVMhZaCuI9jRvcU50UxzEHQ0IGMOfwIX1jVu-~csPUOpjF~sPIpNQT2HAsToNY8OjC4uMSocxn2XXQ~dAz41moTDsNqW66QWB2VvneDNCAOCrunWGfHg4lydc3lZYTmVFtE5FJGk8v0DJ4I6OkE4Kl4VjJf1CnsldEUeBOTAWzr3mcLIu-t~QN0PM3BBPmLWu0-ww__&Key-Pair-Id=APKAI6JAFOBXQEFCLCSQ"
}
}
],
"id": "a257f7d4-5fd8-4300-8d9a-1b611771be4b",
"updatedAt": "2024-06-24T09:31:19Z",
"updatedByTrn": "trn:tid:application:fae7a6aa-cf9b-42ad-945b-a89d1c1ec580"
}

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

PUT {UPLOAD URL}
  • BODY: {File Content}

Run a GET upload API call to check the job status. The value should be COMPLETED once main file and all support file contents are uploaded.

GET {baseUrl}/spaces/{spaceId}/uploads/{uploadId}
  • HEADER:

    • Authorization: Bearer {tid token}
Example response
{
"id": "e28982f5-ebd8-4a76-97f4-0783fc143f30",
"fileInputUploadDetails": {
"fileId": "e28982f5-ebd8-4a76-97f4-0783fc143f30",
"spaceId": "f85bc802-5481-4581-b972-c4652d595ec7",
"name": "FileName.ext",
"permissionsLocal": {
"inherits": true,
"acl": [
{
"actor": "trn:tid:user:6529d0b3-5856-41ab-88b3-86f7955cddf1",
"role": "contentManager"
},
{
"actor": "trn:tid:user:7529d0b3-5856-41ab-88b3-86f7955cddf1",
"role": "contentManager"
}
]
},
"status": "UPLOADED",
"upload": {
"type": "SINGLEPART"
},
"parentId": "e28982f5-ebd8-4a76-97f4-0783fc143f30",
"path": "testA/testB/FileName.ext",
"fileset": false,
"restrictedAccess": false,
"expiresAt": "2024-01-01T12:25:00.000Z",
"metadata": {
"language": "Suomi"
},
"multipart": false,
"responseHeaders": {
"response-content-type": "image/jpeg",
"response-content-disposition": "inline",
"response-cache-control": "max-age=3000"
},
"applicationId": "f85bc802-5481-4581-b972-c4652d595ec7"
},
"md5": "1231b98eaa246bf6f34d001fa217adec",
"resources": [
{
"fileId": "b6c3356d-5673-4b77-9ba5-5e579b92ea8a",
"md5": "771b301e570f2c8fa233d090e340b777",
"name": "THUMB",
"responseHeaders": {
"response-content-disposition": "attachment; filename=\"THUMB\"; filename*=utf-8''THUMB",
"response-content-type": "binary/octet-stream"
},
"restrictedAccess": true,
"size": 172,
"status": "UPLOADED",
"supportFileKey": "THUMB",
"upload": {
"type": "SINGLEPART"
},
"version": "1.0"
}
],
"createdAt": "2023-05-30T10:30:00Z",
"createdByTrn": "trn:tid:application:f85bc802-5481-4581-b972-c4652d595ec7",
"updatedAt": "2023-05-30T10:30:00Z",
"updatedByTrn": "trn:tid:application:f85bc802-5481-4581-b972-c4652d595ec7"
}

To know more about the upload file API refer here.