Skip to content
File Service

trimble-fileservice

The Trimble File Service provides capabilities for managing file type of resources organized into folders and related metadata in a secure way with predefined ACL roles.

Getting Started

Installation

This SDK is available as a NuGet package from Trimble Artifactory. To install, use the following command:

pip install trimble-fileservice

FileService Endpoints

These are the US region endpoints for File Service:

EnvironmentBase URL Endpoint
Stagehttps://cloud.stage.api.trimblecloud.com/fileservice/api/2.0
Productionhttps://cloud.api.trimble.com/fileservice/api/2.0

For other regions, refer to the Trimble Cloud Console.

Create File Service Client

To create a FileServiceClient, you need to provide a token provider and the File Service endpoint. The token provider is used to authenticate the client with Trimble Identity (TID).

from trimble.id import ClientCredentialTokenProvider, OpenIdEndpointProvider
from trimble.fileservice import FileServiceClient


# We first setup a TID endpoint provider for communications with our authorization server TID
endpoint_provider = OpenIdEndpointProvider("https://id.trimble.com/.well-known/openid-configuration")


# We then set up a token provider to handle the token exchange with TID
token_provider = ClientCredentialTokenProvider(
    endpointProvider=endpoint_provider,
    clientId="client_id",
    clientSecret="client_secret"
).with_scopes(["scopes"])


# Create File Service client
client = FileServiceClient(token_provider=token_provider, base_url="base_url")

Refer to the Trimble ID SDK documentation for more information on setting up the token provider.

Minimal Response Feature

  • The minimal response feature provides a streamlined version of response data by including only essential attributes of an entity.
  • This reduces the response size, leading to faster data transfer and lower bandwidth usage.
  • It is particularly useful when the client does not need all the attributes of an entity.
  • The minimal response feature is applicable for all synchronous operation responses, including methods such as Create, Get, Update, Move, Rename, Restore, Lock, Unlock, Get Version, and List methods.

Spaces

  • A space is a container for files and folders.
  • It is the top-level entity in the file service.
  • A root folder is created automatically when a space is created.

Create

Create a new space.

space = await client.spaces.create(
    name="space_name",
    account_id="1234567890",
    permissions_local={
        "acl": [
            {"actor": "trn:tid:application:<uuid>", "role": "spaceManager"},
            {"actor": "trn:tid:user:<uuid>", "role": "contentManager"},
            {"actor": "trn:tid:device:<uuid>", "role": "contentManager"}
        ]
    },
    provider="aws",
    soft_delete_retention="30d"
)

To create a space and get a minimal response, set the optional complete parameter to False.

space = await client.spaces.create(
    name="space_name",
    account_id="1234567890",
    complete=False
)

Get

Get space by ID.

space = await client.spaces.get(space_id="space_id")

The optional status parameter can be used to filter the spaces based on the status.

spaces = await client.spaces.get(space_id="space_id", status="active,deleted")

To get a space with minimal response, set the optional complete parameter to False.

space = await client.spaces.get(space_id="space_id", complete=False)

Update

Update space by ID. Only the name, ACL details, and soft delete retention can be updated for a space.

# Replace all permissions with new permissions
space = await client.spaces.update(
    space_id="space_id",
    name="new_name",
    permissions_local={
        "acl": [
            {"actor": "trn:tid:user:<uuid>", "role": "contentManager"},
            {"actor": "trn:tid:user:<uuid>", "role": "contentContributor"}
        ]
    }
)


# Or incrementally update permissions
space = await client.spaces.update(
    space_id="space_id",
    name="new_name",
    permissions_local={
        "updateAcl": {
            "add": [
                {"actor": "trn:tid:user:<uuid>", "role": "contentManager"}
            ],
            "remove": [
                {"actor": "trn:tid:user:<uuid>"}
            ]
        }
    }
)

To update a space and get a minimal response, set the optional complete parameter to False.

space = await client.spaces.update(space_id="space_id", name="new_name", complete=False)

Delete

Delete space by ID. By default, it is a non-recursive soft delete operation.

Empty space deletion will not return any job ID. Non-empty space deletion is an asynchronous operation which returns the job ID.

await client.spaces.delete(space_id="space_id")

The optional recursive parameter can be used to delete the space and its contents recursively. The permanent parameter can be used to delete the space permanently.

job_id = await client.spaces.delete(space_id="space_id", recursive=True, permanent=True)

NOTE: A non-empty space can only be deleted with recursive parameter set to true.

Restore

The restore space operation is used to restore a deleted space within 30 days of its deletion. Any resources nested under the restored space or folder will be restored through an asynchronous process.

response = await client.spaces.restore(space_id="space_id")

To restore a space and get a minimal response, set the optional complete parameter to False.

response = await client.spaces.restore(space_id="space_id", complete=False)

Folders

  • A folder is a container for files and other folders.

Create

Create a new folder.

folder = await client.folders.create(
    space_id="space_id",
    name="folder_name",
    parent_id="parent_id",
    permissions_local={
        "inherits": False,
        "acl": [
            {"actor": "trn:tid:user:<uuid>", "role": "contentManager"},
            {"actor": "trn:tid:user:<uuid>", "role": "contentContributor"}
        ]
    }
)

NOTE: To create a folder under the root folder of a space, set the parent_id as the root_id of the space.

To create a folder and get a minimal response, set the optional complete parameter to False.

folder = await client.folders.create(
    space_id="space_id",
    name="folder_name",
    parent_id="parent_id",
    complete=False
)

Get by ID

Get folder by ID.

folder = await client.folders.get(space_id="space_id", folder_id="folder_id")

The optional status parameter can be used to filter the folders based on the status.

folders = await client.folders.get(space_id="space_id", folder_id="folder_id", status="active,deleted")

To get a folder with minimal response, set the optional complete parameter to False.

folder = await client.folders.get(space_id="space_id", folder_id="folder_id", complete=False)

Get by Path

Get folder by path.

folder = await client.folders.get_by_path(space_id="space_id", path="path")

The optional status parameter can be used to filter the folders based on the status.

folders = await client.folders.get_by_path(space_id="space_id", path="path", status="active,deleted")

To get a folder with minimal response, set the optional complete parameter to False.

folder = await client.folders.get_by_path(space_id="space_id", path="path", complete=False)

Update

Update folder by ID. Only the metadata and ACL settings can be updated.

# Replace Acl
folder = await client.folders.update(
    space_id="space_id",
    folder_id="folder_id",
    metadata={"key": "value"},
    permissions_local={
        "inherits": False,
        "acl": [
            {"actor": "trn:tid:user:<uuid>", "role": "contentManager"},
            {"actor": "trn:tid:user:<uuid>", "role": "contentContributor"}
        ]
    }
)


# update Acl
folder = await client.folders.update(
    space_id="space_id",
    folder_id="folder_id",
    permissions_local={
        "updateAcl": {
            "add": [
                {"actor": "trn:tid:user:<uuid>", "role": "contentManager"}
            ]
        }
    }
)

To update a folder and get a minimal response, set the optional complete parameter to False.

folder = await client.folders.update(
    space_id="space_id",
    folder_id="folder_id",
    metadata={"key": "value"},
    complete=False)

Delete

Delete folder by ID. By default, it is a non-recursive soft delete operation.

Empty folder deletion will not return any job ID. Non-empty folder deletion is an asynchronous operation which returns the job ID.

await client.folders.delete(
    space_id="space_id",
    folder_id="folder_id")

The optional recursive parameter can be used to delete the folder and its contents recursively. The permanent parameter can be used to delete the folder permanently.

job_id = await client.folders.delete(
    space_id="space_id",
    folder_id="folder_id",
    recursive=True,
    permanent=True)

NOTE: A non-empty folder can only be deleted with recursive parameter set to true.

Move

Move a folder to a new location within the same space. The move operation is asynchronous and returns a immediate folder with jobID.

response = await client.folders.move(
    space_id="space_id",
    folder_id="folder_id",
    target_parent_id="target_parent_id")

To get a minimal response, set the optional complete parameter to False.

Rename

Rename a folder with a new name. The folder will be renamed to the target name and the folder identifier will remain the same.

response = await client.folders.rename(
    space_id="space_id",
    folder_id="folder_id",
    name="new_name")

To get a minimal response, set the optional complete parameter to False.

Copy

Copy a folder to a new location within the same space. The folder will be copied to the target location and the new folder ID will be generated.

response = await client.folders.copy(
    space_id="space_id",
    folder_id="folder_id",
    target_parent_id="target_parent_id")

To get a minimal response, set the optional complete parameter to False.

The optional name parameter can be used to specify a new name for the copied folder. The optional include_support_files, if true, copies the support files along with the folder. The overwrite_existing parameter, if specified and true, determines whether to overwrite an existing resource by creating a new version with the copied content.

response = await client.folders.copy(
    space_id="space_id",
    folder_id="folder_id",
    target_parent_id="target_parent_id",
    name="new_name",
    include_support_files=True,
    overwrite_existing=True)

Restore

Restore a folder and it’s children from the deleted state. By default, the folder will be restored to its original location.

response = await client.folders.restore(
    space_id="space_id",
    folder_id="folder_id",
    name="new_name")

The optional name parameter can be used to specify a new name for the restored folder and the target_parent_id parameter can be used to restore the folder to a new location.

response = await client.folders.restore(
    space_id="space_id",
    folder_id="folder_id",
    name="new_name",
    target_parent_id="target_parent_id")

To restore a folder and get a minimal response, set the optional complete parameter to False.

response = await client.folders.restore(
    space_id="space_id",
    folder_id="folder_id",
    complete=False)

List Children by ID

List all children of a folder by ID.

NOTE: The list_children_sync method returns a minimal response by default, and there is no option to retrieve a full response.

children = await client.folders.list_children_sync(
    space_id="space_id",
    folder_id="folder_id")
for item in children:
    print(item)

The optional max_results parameter can be used to limit the number of children returned in each page. The status parameter can be used to filter the children based on the status.

children = await client.folders.list_children_sync(space_id="space_id", folder_id="folder_id", maxItems=10, status="active,deleted")
for item in children:
    print(item)

List Children by Path

List all children of a folder by path.

children = await client.folders.list_children_by_path_sync(
    space_id="space_id",
    path="path")
for item in children:
    print(item)

The optional max_results parameter can be used to limit the number of children returned in each page. The status parameter can be used to filter the children based on the status.

children = await client.folders.list_children_by_path_sync(space_id="space_id", path="path", maxItems=10, status="active,deleted")
for item in children:
    print(item)

Get Version by ID

Get details for the specified folder version by ID.

folder = await client.folders.get(space_id="space_id", folder_id="folder_id", version="2")

The optional status parameter can be used to filter the folder versions based on the status.

folder = await client.folders.get(space_id="space_id", folder_id="folder_id", version="2", status="active,deleted")

To get a folder version with minimal response, set the optional complete parameter to False.

folder = await client.folders.get(space_id="space_id", folder_id="folder_id", version="2", complete=False)

Get Version by Path

Get details for the specified folder version by path.

folder = await client.folders.get_by_path(space_id="space_id", path="path", version="version")

The optional status parameter can be used to filter the folder versions based on the status.

folder = await client.folders.get_by_path(space_id="space_id", path="path", version="version", status="active,deleted")

To get a folder version with minimal response, set the optional complete parameter to False.

folder = await client.folders.get_by_path(space_id="space_id", path="path", version="version", complete=False)

List Versions by ID

List all versions of a folder by ID.

versions = await client.folders.list_versions_sync(
    space_id="space_id",
    folder_id="folder_id")
for folder in versions:
    print(folder)

The optional max_results parameter can be used to limit the number of versions returned in each page. The status parameter can be used to filter the versions based on the status.

versions = await client.folders.list_versions_sync(
    space_id="space_id",
    folder_id="folder_id",
    maxItems=10,
    status="active,deleted")
for folder in versions:
    print(folder)

To list folder versions with minimal response, set the optional complete parameter to False.

versions = await client.folders.list_versions_sync(
    space_id="space_id",
    folder_id="folder_id",
    complete=False)
for folder in versions:
    print(folder)

List Versions by Path

List all versions of a folder by path.

versions = await client.folders.list_versions_by_path_sync(
    space_id="space_id",
    path="path")
for folder in versions:
    print(folder)

The optional max_results parameter can be used to limit the number of versions returned in each page. The status parameter can be used to filter the versions based on the status.

versions = await client.folders.list_versions_by_path_sync(
    space_id="space_id",
    path="path",
    maxItems=10,
    status="active,deleted")
for folder in versions:
    print(folder)

To list folder versions with minimal response, set the optional complete parameter to False.

versions = await client.folders.list_versions_by_path_sync(
    space_id="space_id",
    path="path",
    complete=False)
for folder in versions:
    print(folder)

Files

  • A file is a binary object that resides under a folder.

Get by ID

Get file by ID.

file = await client.files.get(space_id="space_id", file_id="file_id")

The optional status parameter can be used to filter the files based on the status, the url_duration parameter can be used to specify the download URL validity duration and the response_content_type parameter can be used to specify the content type of the response. The default value for url_duration is 1 hour.

file = await client.files.get(
    space_id="space_id",
    file_id="file_id",
    status="active,deleted",
    url_duration="120m",
    response_content_type="application/json")

To get a file with minimal response, set the optional complete parameter to False.

file = await client.files.get(
    space_id="space_id",
    file_id="file_id",
    complete=False)

Get by Path

Get file by path.

file = await client.files.get_by_path(
    space_id="space_id",
    path="path")

The optional status parameter can be used to filter the files based on the status, the url_duration parameter can be used to specify the download URL validity duration and the response_content_type parameter can be used to specify the content type of the response. The default value for url_duration is 1 hour.

file = await client.files.get_by_path(
    space_id="space_id",
    path="path",
    status="active,deleted",
    url_duration="120m",
    response_content_type="application/json")

To get a file with minimal response, set the optional complete parameter to False.

file = await client.files.get_by_path(
    space_id="space_id",
    path="path",
    complete=False)

Create File Upload

Generates a pre-signed upload url for the given name and parent ID. The returned upload response or upload ID is used to upload the file.

If multipart is set to true, the file will be uploaded in parts and it is handled by the SDK.

response = await client.files.create_file_upload(
    space_id="space_id",
    name="name",
    parent_id="parent_id",
    multipart=True,
    permissions_local={
        "inherits": False,
        "acl": [
            {"actor": "trn:tid:user:<uuid>", "role": "contentManager"},
            {"actor": "trn:tid:user:<uuid>", "role": "contentContributor"}
        ]
    }
)

The optional url_duration parameter can be used to specify the upload URL validity duration and the include_links parameter can be used to specify whether to include the links from the last version during a file’s major version change. The default value for url_duration is 1 hour.

upload_file_response = await client.files.create_file_upload(
    space_id="space_id",
    name="name",
    parent_id="parent_id",
    url_duration="120m",
    include_links=True)

Create Support File Upload

Generates a pre-signed upload url for the given name and file ID. The returned upload response or upload ID is used to upload the support file.

upload_support_file_response = await client.files.create_support_file_upload(
    space_id="space_id",
    name="name",
    file_id="parent_file_id")

The optional url_duration parameter can be used to specify the upload URL validity duration. The default value for url_duration is 1 hour.

upload_support_file_response = await client.files.create_support_file_upload(
    space_id="space_id",
    name="name",
    file_id="parent_file_id",
    url_duration="120m")

Create Package Upload

Package upload allows for the simultaneous uploading of a main file along with its associated support files. A maximum of 10 support files can be included in the package upload and by default, the support file are linked to the main file.

resources = [
    SupportFileResourceParams(name="support_file_1", support_file_key="KEY1"),
    SupportFileResourceParams(name="support_file_2", support_file_key="KEY2")
]


upload_package_response = await client.files.create_package_upload(space_id="space_id", name="name", parent_id="parent_id", support_file_resources=resources)

Link support files to a file. The support files will be linked to the target main file and main file minor version will be incremented.

Only support files created under the target main file can be linked.

from trimble.fileservice.models import SupportFileLinkParams


links = {
    "key1": SupportFileLinkParams(id="id"),
    "key2": SupportFileLinkParams(id="id", version="version")
}


file = await client.files.create_or_update_links(space_id="space_id", file_id="file_id", file_major_version=3, links=links)

To create or update links and get a minimal response, set the optional complete parameter to False.

file = await client.files.create_or_update_links(space_id="space_id", file_id="file_id", file_major_version=3, links=links, complete=False)

Get Upload Details

Retrieve the file or support file upload details by ID.

upload = await client.files.get_upload_details(space_id="space_id", upload_id="upload_id")

The optional url_duration parameter can be used to specify the upload URL validity duration.

upload = await client.files.get_upload_details(space_id="space_id", upload_id="upload_id", url_duration="120m")

Upload File

Upload a file or support file to an existing upload using upload ID.

file_object = open("file_path", "rb")
await client.files.upload_file(space_id="space_id", upload_id="upload_id", file_object=file_object)

Upload File Object

Upload a file or support to an existing upload using UploadFileResponse or UploadSupportFileResponse object.

file_object = open("file_path", "rb")
await client.files.upload_file_object(upload_response=upload_response, file_object=file_object)

Upload Package

Upload a package to an existing upload using upload ID.

Maximum of 10 support files can be included in the package upload. The support files will be linked to the main file by default.

main_file_object = open("main_file_path", "rb")
support_file_object_1 = open("support_file_1_path", "rb")
support_file_object_2 = open("support_file_2_path", "rb")


support_file_objects = [
    SupportFileResourceUpload(key="KEY1", file_object=support_file_object_1),
    SupportFileResourceUpload(key="KEY2", file_object=support_file_object_2),
]


await client.files.upload_package(space_id="space_id", upload_id="upload_id", file_object=main_file_object, support_files=support_file_objects)

Download File by ID

Download a file or support file by ID.

file_object = open("file_path", "wb")
await client.files.download_file(space_id="space_id", file_id="file_id", file_object=file_object)

Download File by Path

Download a file or support file by path.

file_object = open("file_path", "wb")
await client.files.download_file_by_path(
    space_id="space_id",
    path="path",
    file_object=file_object)

Update

Update file by ID. Only the metadata, ACL and links can be updated.

file = await client.files.update(
    space_id="space_id",
    file_id="file_id",
    metadata={"key": "value"},
    permissions_local={
        "inherits": False,
        "acl": [
            {"actor": "trn:tid:user:<uuid>", "role": "contentManager"},
            {"actor": "trn:tid:user:<uuid>", "role": "contentContributor"}
        ]
    }
)

To update a file and get a minimal response, set the optional complete parameter to False.

file = await client.files.update(
    space_id="space_id",
    file_id="file_id",
    metadata={"key": "value"},
    permissions_local={
        "inherits": False,
        "acl": [
            {"actor": "trn:tid:user:<uuid>", "role": "contentManager"},
            {"actor": "trn:tid:user:<uuid>", "role": "contentContributor"}
        ]
    },
    complete=False
)

Delete

Deletes the file. By default, it is a soft delete operation.

Delete for files that have support files is an asynchronous operation which returns the job ID.

job_id = await client.files.delete(
    space_id="space_id",
    file_id="file_id")

The optional permanent parameter can be used to delete the file permanently.

await client.files.delete(
    space_id="space_id",
    file_id="file_id",
    permanent=True)

Move

Move a file to a new location within the same space. The file will be moved to the target location and the file identifier will remain the same.

The move operation is immediate and the response contains the updated parent ID.

file = await client.files.move(
    space_id="space_id",
    file_id="file_id",
    target_parent_id="target_parent_id")

To move a file and get a minimal response, set the optional complete parameter to False.

file = await client.files.move(
    space_id="space_id",
    file_id="file_id",
    target_parent_id="target_parent_id",
    complete=False)

Rename

Rename a file within the same space. The file identifier will remain the same.

The rename operation is immediate and the response contains the updated file name.

file = await client.files.rename(
    space_id="space_id",
    file_id="file_id",
    name="new_name")

To rename a file and get a minimal response, set the optional complete parameter to False.

file = await client.files.rename(
    space_id="space_id",
    file_id="file_id",
    name="new_name",
    complete=False)

Copy

Copies a file from one folder to another within the given space. The copy operation is asynchronous and returns a job.

response = await client.files.copy(
    space_id="space_id",
    file_id="file_id",
    target_parent_id="target_parent_id")

NOTE: The copy operation is not supported across different spaces and copies only the latest version.

The optional name parameter can be used to specify a new name for the copied file. The optional include_support_files, if true, copies the support files along with the file and creates links between the copied file and the copied support files. The overwrite_existing parameter, if specified and true, determines whether to overwrite an existing resource by creating a new version with the copied content.

response = await client.files.copy(
    space_id="space_id",
    file_id="file_id",
    target_parent_id="target_parent_id",
    name="new_name",
    include_support_files=True,
    overwrite_existing=True)

Restore

Restore a file from the deleted state.

response = await client.files.restore(
    space_id="space_id",
    file_id="file_id")

The optional name parameter can be used to specify a new name for the restored file and the target_parent_id parameter can be used to restore the file to a new location.

file = await client.files.restore(
    space_id="space_id",
    file_id="file_id",
    name="new_name",
    target_parent_id="target_parent_id")

To restore a file and get a minimal response, set the optional complete parameter to False.

file = await client.files.restore(
    space_id="space_id",
    file_id="file_id",
    complete=False)

Lock

Lock a file within a space. Locking a file will prevent other actors from creating a new version or deleting the file.

A locked file will be deleted in a recursive parent deletion. Support files cannot be locked.

file = await client.files.lock(
    space_id="space_id",
    file_id="file_id")

The optional reason parameter can be used to specify the reason for locking the file.

file = await client.files.lock(
    space_id="space_id",
    file_id="file_id",
    reason="Reason for locking the file")

To lock a file and get a minimal response, set the optional complete parameter to False.

file = await client.files.lock(
    space_id="space_id",
    file_id="file_id",
    complete=False)

Unlock

Unlock a file within a space. Unlocking a file will allow other actors to create a new version or delete the file.

The actor who locked the file or an actor with the ‘ContentManager’ role attached to the file or parent resource is allowed to unlock the file.

file = await client.files.unlock(
    space_id="space_id",
    file_id="file_id")

To unlock a file and get a minimal response, set the optional complete parameter to False.

file = await client.files.unlock(
    space_id="space_id",
    file_id="file_id",
    complete=False)

Get Version by ID

Get a specific version of a file by ID.

file = await client.files.get_version(
    space_id="space_id",
    file_id="file_id",
    version="2.0")

The optional status parameter can be used to filter the file versions based on the status, the url_duration parameter can be used to specify the download URL validity duration and the response_content_type parameter can be used to specify the content type of the response. The default value for url_duration is 1 hour.

file = await client.files.get_version(
    space_id="space_id",
    file_id="file_id",
    version="2.0",
    status="active,deleted",
    url_duration="120m",
    response_content_type="application/json")

To get a file version with minimal response, set the optional complete parameter to False.

file = await client.files.get_version(
    space_id="space_id",
    file_id="file_id",
    version="2.0",
    complete=False)

Get Version by Path

Get a specific version of a file by path.

file = await client.files.get_version_by_path(
    space_id="space_id",
    path="path",
    version="2.0")

The optional status parameter can be used to filter the file versions based on the status, the url_duration parameter can be used to specify the download URL validity duration and the response_content_type parameter can be used to specify the content type of the response. The default value for url_duration is 1 hour.

file = await client.files.get_version_by_path(
    space_id="space_id",
    path="path",
    version="2.0",
    status="active,deleted",
    url_duration="120m",
    response_content_type="application/json")

To get a file version with minimal response, set the optional complete parameter to False.

file = await client.files.get_version_by_path(
    space_id="space_id",
    path="path",
    version="2.0",
    complete=False)

List Versions by ID

List all versions of a file by ID.

versions = await client.files.list_versions_sync(
    space_id="space_id",
    file_id="file_id")
for file in versions:
    print(file)

The optional max_results parameter can be used to limit the number of versions returned in each page. The status parameter can be used to filter the versions based on the status.

versions = await client.files.list_versions_sync(
    space_id="space_id",
    file_id="file_id",
    maxItems=10,
    status="active,deleted")
for file in versions:
    print(file)

To list file versions with minimal response, set the optional complete parameter to False.

versions = await client.files.list_versions_sync(
    space_id="space_id",
    file_id="file_id",
    complete=False)
for file in versions:
    print(file)

List Versions by Path

List all versions of a file by path.

versions = await client.files.list_versions_by_path_sync(
    space_id="space_id",
    path="path")
for file in versions:
    print(file)

The optional max_results parameter can be used to limit the number of versions returned in each page. The status parameter can be used to filter the versions based on the status.

versions = await client.files.list_versions_by_path_sync(
    space_id="space_id",
    path="path",
     maxItems=10,
     status="active,deleted")
for file in versions:
    print(file)

To list file versions with minimal response, set the optional complete parameter to False.

versions = await client.files.list_versions_by_path_sync(
    space_id="space_id",
    path="path",
    complete=False)
for file in versions:
    print(file)

List Support Files by ID

Lists all support files of a file by ID.

files = await client.files.list_support_files_sync(
    space_id="space_id",
    file_id="file_id")
for file in files:
    print(file)

The optional max_results parameter can be used to limit the number of support files returned in each page. The status parameter can be used to filter the support files based on the status.

files = await client.files.list_support_files_sync(
    space_id="space_id",
    file_id="file_id",
    maxItems=10,
    status="active,deleted")
for file in files:
    print(file)

To list support files with minimal response, set the optional complete parameter to False.

files = await client.files.list_support_files_sync(
    space_id="space_id",
    file_id="file_id",
    complete=False)
for file in files:
    print(file)

List Support Files by Path

Lists all support files of a file by path.

files = await client.files.list_support_files_by_path_sync(
    space_id="space_id",
    path="path")
for file in files:
    print(file)

The optional max_results parameter can be used to limit the number of support files returned in each page. The status parameter can be used to filter the support files based on the status.

files = await client.files.list_support_files_by_path_sync(
    space_id="space_id",
    path="path",
    maxItems=10,
    status="active,deleted")
for file in files:
    print(file)

To list support files with minimal response, set the optional complete parameter to False.

files = await client.files.list_support_files_by_path_sync(
    space_id="space_id",
    path="path",
    complete=False)
for file in files:
    print(file)

Jobs

  • A job is a background process that is triggered by the user.
  • Async operations will return a job ID which can be used to track the status of the operation.

Get

Get job details by ID.

job = await client.jobs.get(
    job_id="job_id"
    )

Exports

Export is used to zip all children of a folder into a single file. Exports persist for 30 days and capture the state of the folder and its children at the time of creation, with no subsequent changes reflected. It is created in the same cloud provider as the space.

Create

Create an export.

export_id = await client.exports.create(
    space_id="space_id",
    folder_id="folder_id");

Get

Get an export by ID.

export = await client.exports.get(
    space_id="space_id",
    export_id="export_id");

The optional url_duration parameter can be used to specify the download URL validity duration. The default value for url_duration is 1 hour.

export = await client.exports.get(
    space_id="space_id",
    export_id="export_id",
    url_duration="120m");

Resources

The response structure depends on whether the resource is a folder, file or a support file

Get resource by id.

file = await client.resources.get(space_id="space_id", resource_id="resource_id")


folder = await client.resources.get(space_id="space_id", resource_id="resource_id")


support_file = await client.resources.get(space_id="space_id", resource_id="resource_id")


minimal_file = await client.resources.get(space_id="space_id", resource_id="resource_id", complete=False)


minimal_folder = await client.resources.get(space_id="space_id", resource_id="resource_id", complete=False)

Get resource by path.

file = await client.resources.get_by_path(space_id="space_id", path="path")


###
Get resource in batch


```python
# Get resources by IDs
resources = await client.resources.get_in_batch(
    space_id="space_id",
    ids=["resource_id1", "resource_id2"]
)


# Get resources by paths
resources = await client.resources.get_in_batch(
    space_id="space_id",
    paths=["/folder1/file1.txt", "/folder2/file2.txt"]
)