Skip to content
File Service

Create Space

The creation of a space is the initial step in using the file service. A space is a logical container for files and folders. All files and folders must be created within the context of a space.

The Cloud provider in which binary resources are stored is specified at the space level. Once a cloud provider is selected it cannot be changed. Space content cannot be stored across multiple to cloud providers.

Space can be created in either of the two cloud providers listed.

  • AWS
  • AZURE

AWS is the default provider, if no cloud provider is specified, the space will default to AWS storage.

All spaces must be associated with a Trimble Account. The account id should match an identifier from CDH. Validation of account ids is not in place at this time.

Upon creation of a space, a root folder is automatically generated, which can be used to store and organize files and folders within the space.

Additionally, the user who created the space is given the Space Manager role for the space and Content Manager role for the root folder. For information about permissions, refer to the ACL.

Limitations

Section titled “Limitations”

The name of space has the following restrictions

  • Name cannot begin with /
  • Length should be less than 255 characters
  • Name should not be reserved keywords like com, lpt, con, nul, prn, aux, ?, <, >, *, |

Prerequisites

Section titled “Prerequisites”
  • Subscribe to the File service API. To know more about subscribing file service refer here

Request

Section titled “Request”
POST {baseUrl}/spaces

  • HEADER:

    • Authorization: Bearer {tid token}

  • BODY:

    • name - Name of the space
    • provider - Cloud provider where space needs to be created
    • accountId - The CDH account identifier
    • softDeleteRetention - Duration of soft deleted resources being retained before being permanently removed. Values are “30d” (30 days), “180d” (180 days), “1y” (1 year) and “never-delete”. (Optional - default is 30d)
    • permissionsLocal - List of actors and their roles for the space. (Optional)
Example request body
{
    "name": "My space",
    "provider": "aws",
    "accountId": "300000014375014",
    "softDeleteRetention": "30d",
    "permissionsLocal": {
        "acl": [
            {
                "actor": "trn:tid:user:6529d0b3-5856-41ab-88b3-86f7955cddf1",
                "role": "contentManager"
            },
            {
                "actor": "trn:tid:user:f85bc802-5481-4581-b972-c4652d595ec7",
                "role": "contentContributor"
            }
        ]
    }
}

After the space creation operation is completed, the JSON response includes the id value for the space.

Response

Section titled “Response”
Example response
{
    "id": "6b67c873-e1e8-4207-a444-7052004e68d8",
    "resourceTrn": "trn:2:fileservice:<region>:space:6b67c873-e1e8-4207-a444-7052004e68d8",
    "name": "My space",
    "provider": "aws",
    "accountId": "300000014375014",
    "softDeleteRetention": "30d",
    "permissionsLocal": {
        "acl": [
            {
                "actor": "trn:tid:user:6529d0b3-5856-41ab-88b3-86f7955cddf1",
                "role": "contentManager"
            },
            {
                "actor": "trn:tid:user:f85bc802-5481-4581-b972-c4652d595ec7",
                "role": "contentContributor"
            }
        ]
    },
    "createdAt": "2024-06-25T07:06:58Z",
    "createdByTrn": "trn:tid:application:<applicationId>",
    "updatedAt": "2024-06-25T07:06:58Z",
    "updatedByTrn": "trn:tid:application:<applicationId>",
    "rootId": "8c0fbc4c-04e6-4f40-a275-f1510a17509f",
    "rootTrn": "trn:2:fileservice:<region>:folder:8c0fbc4c-04e6-4f40-a275-f1510a17509f",
    "type": "SPACE"
}

To know more about the Create space API refer here.