trimblecloud-fileservice

File Service SDK for Java

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 Maven package in Trimble Artifactory.

To install, add the following dependency to your project:

Maven

<dependency>
    <groupId>trimblecloud</groupId>
    <artifactId>trimblecloud-fileservice</artifactId>
    <version>2.0.0</version>
</dependency>

Gradle

implementation group: 'trimblecloud', name: 'trimblecloud-fileservice', version: '2.0.0'

Compatibility

Compatible with Java 8 and above.

File Service Endpoints

These are the US region endpoints for File Service:

Environment	Base URL Endpoint
Stage	https://cloud.stage.api.trimblecloud.com/fileservice/api/2.0/
Production	https://cloud.api.trimble.com/fileservice/api/2.0/

For other regions, refer to the Trimble Cloud Console.

SDK Design Patterns

Builder Pattern

NOTE:: This SDK uses the Builder Pattern for all objects. Use .builder() to construct request objects and configurations. Direct constructor calls are not supported as constructors are intentionally private to ensure API stability.

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).

import com.trimble.id.ITokenProvider;
import com.trimble.id.FixedTokenProvider;

import trimblecloud.fileservice.FileServiceClient;

// Set up a token provider to handle the token exchange with TID
ITokenProvider tokenProvider = new FixedTokenProvider("<ACCESS_TOKEN>");

// Create a FileService client
FileServiceClient fileServiceClient = new FileServiceClient(tokenProvider, new URI("<FILESERVICE_ENDPOINT>"));

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

To configure the client with custom settings, you can use the ClientConfiguration class.

ClientConfiguration clientConfig = ClientConfiguration.builder()
        .httpTimeout(Duration.ofMinutes(10))
        .retryInterval(Duration.ofSeconds(2))
        .retries(2)
        .build();

// Create a FileService client with custom configuration
FileServiceClient fileServiceClient = new FileServiceClient(tokenProvider, new URI("<FILESERVICE_ENDPOINT>"), clientConfig);

Dispose Client

Disposes the client and releases any resources associated with it.

fileServiceClient.dispose();

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, GetVersion and List methods.

Exception Handling

TCPServiceException

TCPServiceException is the most common exception that you’ll experience when using the File Service Java SDK. TCPServiceException provides you with information such as:

• HTTP status code
• Request ID
• Error message

When using CompletableFuture.get() to call methods of the SDK, the exception is sometimes wrapped in an ExecutionException.

SDKClientException

SDKClientException indicates that a problem occurred inside the Java client code, either while trying to send a request to File Service or while trying to parse a response from File Service.

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.

Space Permissions

Spaces use ACL (Access Control List) for permission management. You can:

• Grant permissions to users, applications, or groups using different actor types
• Set time-limited access using accessExpiresAt
• Configure space membership boundaries to control participation
• Use both replaceAcl (replace all permissions) and updateAcl (add/remove specific permissions) when updating spaces

Create

Create a new space.

List<Acl> aclList = new ArrayList<>();
aclList.add(Acl.builder()
        .actor(new AclApplicationIdentity(UUID.fromString("<APPLICATION_ID>")))
        .role(AclRole.CONTENT_MANAGER)
        .build());

// To grant anonymous access with limited viewing capabilities and anonymous only takes Limited Viewer role
aclList.add(Acl.builder()
        .actor("anonymous")
        .role(AclRole.LIMITED_VIEWER)
        .build());

SpacePermissionsLocal permissionsLocal = SpacePermissionsLocal.builder()
        .acl(aclList)
        .build();

CreateSpaceRequest request = CreateSpaceRequest.builder()
        .name("<SPACE_NAME>")
        .accountId("<ACCOUNT_ID>")
        .permissionsLocal(permissionsLocal)
        .build();

CompletableFuture<Response<Space>> spaceResponse = client.spaces().create(request);

Create a new space and return a minimal response.

CreateSpaceRequest request = CreateSpaceRequest.builder()
    .name("<SPACE_NAME>")
    .accountId("<ACCOUNT_ID>")
    .build();

CompletableFuture<Response<MinimalSpace>> spaceResponse = client.spaces().createWithMinimalResponse(request);

Space Membership Boundary

When creating a space with specific membership requirements, you can configure space membership boundaries to control access and participation.

// Create space with membership boundary configuration
List<Acl> aclList = new ArrayList<>();
aclList.add(Acl.builder()
        .actor(new AclApplicationIdentity(UUID.fromString("<APPLICATION_ID>")))
        .role(AclRole.CONTENT_MANAGER)
        .build());

SpaceMembershipBoundary spaceMembershipBoundary = SpaceMembershipBoundary.builder()
                .group("<GROUP_ID>")
                .allowLimitedViewer(true)
                .build();

SpacePermissionsLocal permissionsLocal = SpacePermissionsLocal.builder()
        .acl(aclList)
        .spaceMembershipBoundary("<BOUNDARY_CONFIGURATION>")
        .build();

CreateSpaceRequest request = CreateSpaceRequest.builder()
        .name("<SPACE_NAME>")
        .accountId("<ACCOUNT_ID>")
        .permissionsLocal(permissionsLocal)
        .build();

CompletableFuture<Response<Space>> spaceResponse = client.spaces().create(request);

The space membership boundary defines the scope and limitations for user participation within the space, enabling fine-grained control over access permissions and collaborative workflows.

Get

Get space by ID.

CompletableFuture<Response<Space>> spaceResponse = client.spaces().get(<spaceId>);

Get space by ID with a minimal response.

CompletableFuture<Response<MinimalSpace>> spaceResponse = client.spaces().getWithMinimalResponse(<spaceId>);

Filter by status

CompletableFuture<Response<Space>> spaceResponse = client.spaces().get(<spaceId>, Status.DELETED);

Filter by status and get a minimal response.

CompletableFuture<Response<MinimalSpace>> spaceResponse = client.spaces().getWithMinimalResponse(<spaceId>, Status.DELETED);

Update

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

// Here, the existing permissions are replaced with the new ACL list.
List<Acl> aclList = new ArrayList<>();
aclList.add(Acl.builder()
        .actor(new AclApplicationIdentity(UUID.fromString("<APPLICATION_ID>")))
        .role(AclRole.CONTENT_MANAGER)
        .build()
);

UpdateSpacePermissionsLocal permissionsLocal = UpdateSpacePermissionsLocal.builder().replaceAcl(aclList).build();

UpdateSpaceRequest request = UpdateSpaceRequest.builder()
        .name("<NEW_NAME>")
        .permissionsLocal(permissionsLocal)
        .build();

CompletableFuture<Response<Space>> spaceResponse = client.spaces().update(<spaceId>, request);

// To add or remove permissions, use the updateAcl field.
List<Acl> addAclList = new ArrayList<>();
addAclList.add(Acl.builder()
        .actor(new AclApplicationIdentity(UUID.fromString("<APPLICATION_ID>")))
        .role(AclRole.CONTENT_CONTRIBUTOR)
        .build()
);

List<Acl> removeAclList = new ArrayList<>();
removeAclList.add(Acl.builder()
        .actor(new AclApplicationIdentity(UUID.fromString("<APPLICATION_ID>")))
        .role(AclRole.CONTENT_MANAGER)
        .build()
);

UpdateSpaceAcl updateAcl = UpdateSpaceAcl.builder()
        .add(addAclList)
        .remove(removeAclList)
        .build();

UpdateSpacePermissionsLocal permissionsLocal = UpdateSpacePermissionsLocal.builder().updateAcl(updateAcl).build();

UpdateSpaceRequest request = UpdateSpaceRequest.builder()
        .name("<NEW_NAME>")
        .permissionsLocal(permissionsLocal)
        .build();

CompletableFuture<Response<Space>> spaceResponse = client.spaces().update(<spaceId>, request);

ACL with Expiry

Access Control Lists (ACLs) can be configured with expiration dates to provide time-limited access to resources. This feature allows you to grant temporary permissions that automatically expire.

// Create ACL with expiry date (access expires in 30 days)
Date expiryDate = new Date(System.currentTimeMillis() + (30L * 24 * 60 * 60 * 1000)); // 30 days from now

List<Acl> aclListWithExpiry = new ArrayList<>();
aclListWithExpiry.add(Acl.builder()
        .actor(new AclUserIdentity(UUID.fromString("<USER_ID>")))
        .role(AclRole.CONTENT_CONTRIBUTOR)
        .accessExpiresAt(expiryDate)  // Temporary access that expires
        .build());

UpdateSpacePermissionsLocal permissionsLocal = UpdateSpacePermissionsLocal.builder()
        .replaceAcl(aclListWithExpiry)
        .build();

UpdateSpaceRequest request = UpdateSpaceRequest.builder()
        .permissionsLocal(permissionsLocal)
        .build();

CompletableFuture<Response<Space>> spaceResponse = client.spaces().update(<spaceId>, request);

The accessExpiresAt field specifies when the ACL entry will automatically expire, providing fine-grained temporal control over permissions. After expiry, the user will no longer have the specified access rights.

Update space by ID and return a minimal response.

UpdateSpaceRequest request = UpdateSpaceRequest.builder().name("<NEW_NAME>").build();

CompletableFuture<Response<MinimalSpace>> spaceResponse = client.spaces().updateWithMinimalResponse(<spaceId>, request);

Update Storage Mode

Update the storage mode of a space using the update method. The storage mode controls upload and file creation operations.

UpdateSpaceRequest request = UpdateSpaceRequest.builder()
        .storageMode("read-only")  // Supported values: active, read-only
        .build();

CompletableFuture<Response<Space>> spaceResponse = client.spaces().update(<spaceId>, request);

Delete

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

Delete an empty space by ID (soft delete):

CompletableFuture<Response<JobInfo>> spaceResponse = client.spaces().delete(<spaceId>);

Delete a space with parameters:

DeleteSpaceParams params = DeleteSpaceParams.builder().permanent(false).recursive(true).build();

CompletableFuture<Response<JobInfo>> spaceResponse = client.spaces().delete(spaceId, params);

Parameter	Description
recursive	This needs to be set to true in order to delete a space that is not empty.
permanent	If specified and true, the space with all metadata and contents is deleted permanently.

NOTE: JobInfo contains the Job ID for the successful deletion of a non-empty space.

Restore

Restore space operation is used to restore a deleted space within 30 days of its deletion.

CompletableFuture<Response<RestoreSpace>> spaceResponse = client.spaces().restore(<spaceId>);

NOTE: Job ID and restored space response. Job ID is present only for non-empty space restore.

Restore a space and get a minimal response.

CompletableFuture<Response<RestoreMinimalSpace>> spaceResponse = client.spaces().restoreWithMinimalResponse(<spaceId>);

List Children

List all files and folders directly under a space (root level), along with the space information itself.

CompletableFuture<Response<SpaceList>> response = client.spaces().listChildren(<spaceId>);

List space children with minimal response:

CompletableFuture<Response<MinimalSpaceList>> response = client.spaces().listChildrenWithMinimalResponse(<spaceId>);

List space children with additional parameters:

ListSpaceChildrenParams params = ListSpaceChildrenParams.builder()
        .pageSize(100)
        .sortOrder("asc")
        .resourceType(ListChildrenResourceType.FILE)  // Filter by resource type: FILE, FOLDER
        .sinceTime(Date.from(Instant.now().minus(2, ChronoUnit.HOURS)))
        .build();

CompletableFuture<Response<SpaceList>> response = client.spaces().listChildren(<spaceId>, params);

List space children with parameters and minimal response:

ListSpaceChildrenParams params = ListSpaceChildrenParams.builder()
        .pageSize(100)
        .sortOrder("asc")
        .resourceType(ListChildrenResourceType.FOLDER)  // Filter to show only folders
        .build();

CompletableFuture<Response<MinimalSpaceList>> response = client.spaces().listChildrenWithMinimalResponse(<spaceId>, params);

List Public Resources

List all resources with anonymous access within a space. This returns a paginated list of files and folders that have been explicitly granted anonymous access through ACL permissions. Only resources in spaces with allowAnonymousShares enabled will be returned.

CompletableFuture<Response<SpaceList>> response = client.spaces().listPublicResources(<spaceId>);

List public resources with minimal response:

CompletableFuture<Response<MinimalSpaceList>> response = client.spaces().listPublicResourcesWithMinimalResponse(<spaceId>);

List public resources with additional parameters:

ListPublicResourcesParams params = ListPublicResourcesParams.builder()
        .pageSize(100)
        .nextPageToken("<NEXT_PAGE_TOKEN>")
        .build();

CompletableFuture<Response<SpaceList>> response = client.spaces().listPublicResources(<spaceId>, params);

List public resources with parameters and minimal response:

ListPublicResourcesParams params = ListPublicResourcesParams.builder()
        .pageSize(100)
        .nextPageToken("<NEXT_PAGE_TOKEN>")
        .build();

CompletableFuture<Response<MinimalSpaceList>> response = client.spaces().listPublicResourcesWithMinimalResponse(<spaceId>, params);

Folders

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

Folder Permissions

Folders use ACL (Access Control List) for permission management. You can:

• Grant permissions to users, applications, or groups using different actor types
• Control permission inheritance from parent folders using the inherits flag
• Set time-limited access using accessExpiresAt
• Use both replaceAcl (replace all permissions) and updateAcl (add/remove specific permissions) when updating folders

Create

Create a new folder under the given parentId.

CreateFolderRequest request = CreateFolderRequest.builder()
        .parentId(<parentId>)
        .name("<FOLDER_NAME>")
        .build();

CompletableFuture<Response<Folder>> folderResponse = client.folders().create(<spaceId>, request);

Create a new folder with ACL permissions.

List<Acl> aclList = new ArrayList<>();
aclList.add(Acl.builder()
        .actor(new AclApplicationIdentity(UUID.fromString("<APPLICATION_ID>")))
        .role(AclRole.CONTENT_MANAGER)
        .build());

aclList.add(Acl.builder()
        .actor(new AclUserIdentity(UUID.fromString("<USER_ID>")))
        .role(AclRole.CONTENT_CONTRIBUTOR)
        .build());

FolderPermissionsLocal permissionsLocal = FolderPermissionsLocal.builder()
        .inherits(true)
        .acl(aclList)
        .build();

CreateFolderRequest request = CreateFolderRequest.builder()
        .parentId(<parentId>)
        .name("<FOLDER_NAME>")
        .permissionsLocal(permissionsLocal)
        .build();

CompletableFuture<Response<Folder>> folderResponse = client.folders().create(<spaceId>, request);

Create a new folder under the given parentId and return a minimal response.

CreateFolderRequest request = CreateFolderRequest.builder()
        .parentId(<parentId>)
        .name("<FOLDER_NAME>")
        .build();

CompletableFuture<Response<MinimalFolder>> folderResponse = client.folders().createWithMinimalResponse(<spaceId>, request);

Create Batch

Create multiple folders in a single request. A maximum of 50 folders can be created in a single request.

CreateNestedFolderChildren nestedChild = CreateNestedFolderChildren.builder()
        .name("Nested Child Folder")
        .build();

CreateBatchFolderChildren parentFolder = CreateBatchFolderChildren.builder()
        .parentId(<parentId>)
        .name("Parent Folder")
        .children(Arrays.asList(nestedChild))
        .build();

CreateBatchFolderRequest request = CreateBatchFolderRequest.builder()
        .spaceId(<spaceId>)
        .folders(Arrays.asList(parentFolder))
        .build();

CompletableFuture<Response<FolderBatch>> folderResponse = client.folders().createBatch(request);

Create multiple folders with minimal response.

CreateNestedFolderChildren nestedChild = CreateNestedFolderChildren.builder()
        .name("Nested Child Folder")
        .build();

CreateBatchFolderChildren parentFolder = CreateBatchFolderChildren.builder()
        .parentId(<parentId>)
        .name("Parent Folder")
        .children(Arrays.asList(nestedChild))
        .build();

CreateBatchFolderRequest request = CreateBatchFolderRequest.builder()
        .spaceId(<spaceId>)
        .folders(Arrays.asList(parentFolder))
        .build();

CompletableFuture<Response<MinimalFolderBatch>> folderResponse = client.folders().createBatchWithMinimalResponse(request);

Get by ID

Get folder by ID.

CompletableFuture<Response<Folder>> folderResponse = client.folders().get(<spaceId>, <folderId>, Status.ACTIVE_DELETED);

Get folder by ID with a minimal response.

CompletableFuture<Response<MinimalFolder>> folderResponse = client.folders().getWithMinimalResponse(<spaceId>, <folderId>, Status.ACTIVE_DELETED);

Get by Path

Get folder by path.

CompletableFuture<Response<Folder>> folderResponse = client.folders().get(<spaceId>, "<PATH>");

Get folder by path with a minimal response.

CompletableFuture<Response<MinimalFolder>> folderResponse = client.folders().getWithMinimalResponse(<spaceId>, "<PATH>");

Update

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

HashMap<String, Object> metadata = new HashMap<>();
metadata.put("key", "value");

UpdateFolderRequest request = UpdateFolderRequest.builder().metadata(metadata).build();

CompletableFuture<Response<Folder>> folderResponse = client.folders().update(<spaceId>, <folderId>, request);

Update folder permissions by replacing the entire ACL list.

List<Acl> aclList = new ArrayList<>();
aclList.add(Acl.builder()
        .actor(new AclApplicationIdentity(UUID.fromString("<APPLICATION_ID>")))
        .role(AclRole.CONTENT_MANAGER)
        .build());

UpdateFolderPermissionsLocal permissionsLocal = UpdateFolderPermissionsLocal.builder()
        .replaceAcl(aclList)
        .build();

UpdateFolderRequest request = UpdateFolderRequest.builder()
        .permissionsLocal(permissionsLocal)
        .build();

CompletableFuture<Response<Folder>> folderResponse = client.folders().update(<spaceId>, <folderId>, request);

Update folder permissions by adding and removing specific ACL entries.

List<Acl> addAclList = new ArrayList<>();
addAclList.add(Acl.builder()
        .actor(new AclUserIdentity(UUID.fromString("<USER_ID>")))
        .role(AclRole.CONTENT_CONTRIBUTOR)
        .build());

List<Acl> removeAclList = new ArrayList<>();
removeAclList.add(Acl.builder()
        .actor(new AclApplicationIdentity(UUID.fromString("<APPLICATION_ID>")))
        .role(AclRole.CONTENT_MANAGER)
        .build());

UpdateFolderAcl updateAcl = UpdateFolderAcl.builder()
        .add(addAclList)
        .remove(removeAclList)
        .build();

UpdateFolderPermissionsLocal permissionsLocal = UpdateFolderPermissionsLocal.builder()
        .updateAcl(updateAcl)
        .build();

UpdateFolderRequest request = UpdateFolderRequest.builder()
        .permissionsLocal(permissionsLocal)
        .build();

CompletableFuture<Response<Folder>> folderResponse = client.folders().update(<spaceId>, <folderId>, request);

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

HashMap<String, Object> metadata = new HashMap<>();
metadata.put("key", "value");

UpdateFolderRequest request = UpdateFolderRequest.builder().metadata(metadata).build();

RequestHeader requestHeader = RequestHeader.builder()
        .ifMatch("1")
        .build();

CompletableFuture<Response<Folder>> folderResponse = client.folders().update(<spaceId>, <folderId>, request, requestHeader);

Update folder and returns a minimal response.

HashMap<String, Object> metadata = new HashMap<>();
metadata.put("key", "value");

UpdateFolderRequest request = UpdateFolderRequest.builder().metadata(metadata).build();

CompletableFuture<Response<MinimalFolder>> folderResponse = client.folders().updateWithMinimalResponse(<spaceId>, <folderId>, request);

Delete

Delete Folder by ID.

DeleteFolderRequest request = DeleteFolderRequest.builder()
        .spaceId(<spaceId>)
        .folderId(<folderId>)
        .build();

CompletableFuture<Response<JobInfo>> folderResponse = client.folders().delete(request);

Delete Folder by ID with request header.

RequestHeader requestHeader = RequestHeader.builder()
        .ifMatch("1")
        .build();
DeleteFolderRequest request = DeleteFolderRequest.builder()
        .spaceId(<spaceId>)
        .folderId(<folderId>)
        .build();

CompletableFuture<Response<JobInfo>> folderResponse = client.folders().delete(request, requestHeader);

Delete Folder by ID.

DeleteFolderParams params = DeleteFolderParams.builder()
    .permanent(false)
    .recursive(true).build();

CompletableFuture<Response<JobInfo>> folderResponse = client.folders().delete(<spaceId>, <folderId>, params);

Parameter	Description
recursive	This needs to be set to true in order to delete a folder that is not empty.
permanent	If specified and true, the folder with all metadata and contents is deleted permanently.

NOTE: JobInfo has the Job ID for a successful deletion of a non-empty folder.

Move

Moves a folder to a new location within the same space.

MoveFolderRequest request = MoveFolderRequest.builder()
        .spaceId(spaceId)
        .folderId(folderId)
        .targetParentId(UUID.fromString(<targetParentId>))
        .build();

CompletableFuture<Response<FolderJobResponse>> folderResponse = client.folders().move(request);

Moves a folder to a new location within the same space with request header.

MoveFolderRequest request = MoveFolderRequest.builder()
        .spaceId(spaceId)
        .folderId(folderId)
        .targetParentId(UUID.fromString(<targetParentId>))
        .build();

RequestHeader requestHeader = RequestHeader.builder()
        .ifMatch("1")
        .build();

CompletableFuture<Response<FolderJobResponse>> folderResponse = client.folders().move(request, requestHeader);

Move a folder to a new location within the same space.

CompletableFuture<Response<FolderJobResponse>> response = client.folders().move(<spaceId>, <folderId>, <targetParentId>);

Move a folder to a new location within the same space and return a minimal response.

CompletableFuture<Response<MinimalFolderJobResponse>> response = client.folders().moveWithMinimalResponse(<spaceId>, <folderId>, <targetParentId>);

Rename

Rename a folder with a new name.

RenameFolderRequest request = RenameFolderRequest.builder()
        .spaceId(spaceId)
        .folderId(folderId)
        .name("new_name")
        .build();

CompletableFuture<Response<FolderJobResponse>> folderResponse = client.folders().rename(request);

Rename a folder with a new name with request header.

RenameFolderRequest request = RenameFolderRequest.builder()
        .spaceId(spaceId)
        .folderId(folderId)
        .name("new_name")
        .build();

RequestHeader requestHeader = RequestHeader.builder()
        .ifMatch("1")
        .build();

CompletableFuture<Response<FolderJobResponse>> folderResponse = client.folders().rename(request, requestHeader);

Rename a folder with a new name.

CompletableFuture<Response<FolderJobResponse>> response = client.folders().rename(<spaceId>, <folderId>, "<NEW_NAME>");

Rename a folder with a new name and return a minimal response.

CompletableFuture<Response<MinimalFolderJobResponse>> response = client.folders().renameWithMinimalResponse(<spaceId>, <folderId>, "<NEW_NAME>");

Copy

Copies a folder to a new location within the same space.

CopyFolderRequest request = CopyFolderRequest.builder()
        .spaceId(spaceId)
        .folderId(folderId)
        .targetParentId(UUID.fromString(<targetParentId>))
        .build();

CompletableFuture<Response<FolderJobResponse>> folderResponse = client.folders().copy(request);

Copies a folder to a new location within the same space with request header.

CopyFolderRequest request = CopyFolderRequest.builder()
        .spaceId(spaceId)
        .folderId(folderId)
        .targetParentId(UUID.fromString(<targetParentId>))
        .build();

RequestHeader requestHeader = RequestHeader.builder()
        .ifMatch("*")
        .build();

CompletableFuture<Response<FolderJobResponse>> folderResponse = client.folders().copy(request, requestHeader);

Copy a folder to a new location within the same space.

CompletableFuture<Response<FolderJobResponse>> response = client.folders().copy(<spaceId>, <folderId>, <targetParentId>);

With Parameters

CopyFolderParams params = CopyFolderParams.builder()
    .includeSupportFiles(true)
    .overwriteExisting(true).build();

CompletableFuture<Response<FolderJobResponse>> response = client.folders().copy(<spaceId>, <folderId>, <targetParentId>, params);

Copy a folder to a new location within the same space and return a minimal response.

CompletableFuture<Response<MinimalFolderJobResponse>> response = client.folders().copyWithMinimalResponse(<spaceId>, <folderId>, <targetParentId>);

Restore

Restore a folder and its children from the deleted state to their original location.

RestoreFolderRequest request = RestoreFolderRequest.builder()
        .spaceId(spaceId)
        .folderId(folderId)
        .targetParentId(UUID.fromString(<targetParentId>))
        .build();

CompletableFuture<Response<FolderJobResponse>> folderResponse = client.folders().restore(request);

Restore a folder and its children from the deleted state to their original location with request header.

RestoreFolderRequest request = RestoreFolderRequest.builder()
        .spaceId(spaceId)
        .folderId(folderId)
        .targetParentId(UUID.fromString(<targetParentId>))
        .build();

RequestHeader requestHeader = RequestHeader.builder()
        .ifMatch("1")
        .build();

CompletableFuture<Response<FolderJobResponse>> folderResponse = client.folders().restore(request, requestHeader);

Restore a folder and its children from the deleted state to their original location.

RestoreFolderParams params = RestoreFolderParams.builder().name("<NEW_NAME>").build();

CompletableFuture<Response<FolderJobResponse>> response = client.folders().restore(<spaceId>, <folderId>, params);

NOTE: Job ID is present only for non-empty folder restore.

Restore a folder and its children from the deleted state to their original location and return a minimal response.

CompletableFuture<Response<MinimalFolderJobResponse>> response = client.folders().restoreWithMinimalResponse(<spaceId>, <folderId>);

Checkout

Checkout a folder within a space. Checking out a folder will prevent other actors from creating a new version or performing other mutation operations on the folder.

CheckoutFolderRequest request = CheckoutFolderRequest.builder()
        .spaceId(<spaceId>)
        .folderId(<folderId>)
        .reason("Working on folder structure updates")
        .build();

CompletableFuture<Response<Folder>> folderResponse = client.folders().checkout(request);

Checkout a folder with a request header.

CheckoutFolderRequest request = CheckoutFolderRequest.builder()
        .spaceId(<spaceId>)
        .folderId(<folderId>)
        .reason("Working on folder structure updates")
        .build();

RequestHeader requestHeader = RequestHeader.builder()
        .ifMatch("1")
        .build();

CompletableFuture<Response<Folder>> folderResponse = client.folders().checkout(request, requestHeader);

Checkout a folder and return a minimal response.

CheckoutFolderRequest request = CheckoutFolderRequest.builder()
        .spaceId(<spaceId>)
        .folderId(<folderId>)
        .reason("Working on folder structure updates")
        .build();

CompletableFuture<Response<MinimalFolder>> folderResponse = client.folders().checkoutWithMinimalResponse(request);

After checkout, the folder response will include checkout information:

• checkedOutBy: Identity of the user who checked out the folder
• checkedOutAt: Timestamp when the folder was checked out
• reason: Reason provided for the checkout

Checkin

Checkin a folder within a space. Checking in a folder will allow other actors to create a new version or perform other mutation operations on the folder.

CheckinFolderRequest request = CheckinFolderRequest.builder()
        .spaceId(<spaceId>)
        .folderId(<folderId>)
        .build();

CompletableFuture<Response<Folder>> folderResponse = client.folders().checkin(request);

Checkin a folder and return a minimal response.

CheckinFolderRequest request = CheckinFolderRequest.builder()
        .spaceId(<spaceId>)
        .folderId(<folderId>)
        .build();

CompletableFuture<Response<MinimalFolder>> folderResponse = client.folders().checkinWithMinimalResponse(request);

After checkin, the checkout information will be cleared from the folder response.

List

Lists all children of a folder by ID.

CompletableFuture<Response<FileAndFolderList>> folderResponse = client.folders().listChildren(<spaceId>, <folderId>);

Lists all children of a folder by ID with a minimal response.

CompletableFuture<Response<MinimalFileAndFolderList>> folderResponse = client.folders().listChildrenWithMinimalResponse(<spaceId>, <folderId>);

List Children with Parameters

List children of a folder with custom parameters including sorting, recursive options, and resource type filtering.

ListFolderChildrenParams params = ListFolderChildrenParams.builder()
        .sortBy("name")           // Sort by: name, updatedAt, size (default: name)
        .sortOrder("asc")         // Sort order: asc, desc (default: asc)
        .recursive(true)          // Recursive retrieval: true, false (default: false)
        .resourceType(ListChildrenResourceType.FILE)     // Filter by resource type: FILE, FOLDER
        .pageSize(50)
        .build();

CompletableFuture<Response<FileAndFolderList>> folderResponse = client.folders().listChildren(<spaceId>, <folderId>, params);

List children with parameters and minimal response.

ListFolderChildrenParams params = ListFolderChildrenParams.builder()
        .sortBy("updatedAt")      // Sort by updated timestamp
        .sortOrder("desc")        // Descending order (newest first)
        .recursive(false)         // Only immediate children
        .resourceType(ListChildrenResourceType.FOLDER)   // Filter to show only folders
        .build();

CompletableFuture<Response<MinimalFileAndFolderList>> folderResponse = client.folders().listChildrenWithMinimalResponse(<spaceId>, <folderId>, params);

Get Version

Get details for the specified folder version.

CompletableFuture<Response<Folder>> folderResponse = client.folders().getVersion(<spaceId>,<folderId>, <version>);

Get details for the specified folder version with status filter.

CompletableFuture<Response<Folder>> folderResponse = client.folders().getVersion(<spaceId>,<folderId>, <version>, Status.ACTIVE_DELETED);

Get details for the specified folder version with a minimal response.

CompletableFuture<Response<MinimalFolder>> folderResponse = client.folders().getVersionWithMinimalResponse(<spaceId>,<folderId>, <version>);

List versions

List all versions for a folder in a space by ID.

CompletableFuture<Response<FolderList>> folderResponse = client.folders().listVersions(<spaceId>, <folderId>);

List all versions of a folder by ID with a minimal response.

CompletableFuture<Response<MinimalFolderList>> folderResponse = client.folders().listVersionsWithMinimalResponse(<spaceId>, <folderId>);

List by path

Lists all children of a folder in a space by path.

CompletableFuture<Response<FileAndFolderList>> folderResponse = client.folders().listChildren(<spaceId>, "<PATH>");

Lists all children of a folder in a space by path with a minimal response.

CompletableFuture<Response<MinimalFileAndFolderList>> folderResponse = client.folders().listChildrenWithMinimalResponse(<spaceId>, "<PATH>");

List Children by path with Parameters

List children of a folder with custom parameters including sorting, recursive options, and resource type filtering.

ListFolderChildrenParams params = ListFolderChildrenParams.builder()
        .sortBy("name")           // Sort by: name, updatedAt, size (default: name)
        .sortOrder("asc")         // Sort order: asc, desc (default: asc)
        .recursive(true)          // Recursive retrieval: true, false (default: false)
        .resourceType(ListChildrenResourceType.FILE)     // Filter by resource type: FILE, FOLDER
        .pageSize(50)
        .build();

CompletableFuture<Response<FileAndFolderList>> folderResponse = client.folders().listChildren(<spaceId>, "<PATH>", params);

List children by path with parameters and minimal response.

ListFolderChildrenParams params = ListFolderChildrenParams.builder()
        .sortBy("updatedAt")      // Sort by updated timestamp
        .sortOrder("desc")        // Descending order (newest first)
        .recursive(false)         // Only immediate children
        .resourceType(ListChildrenResourceType.FOLDER)   // Filter to show only folders
        .build();

CompletableFuture<Response<MinimalFileAndFolderList>> folderResponse = client.folders().listChildrenWithMinimalResponse(<spaceId>, "<PATH>", params);

Get Version by Path

Get folder details for the given folder version by path.

CompletableFuture<Response<Folder>> folderResponse = client.folders().getVersion(<spaceId>,"<PATH>", <version>);

Get folder details for the given folder version by path with status filter.

CompletableFuture<Response<Folder>> folderResponse = client.folders().getVersion(<spaceId>,"<PATH>", <version>, Status.ACTIVE_DELETED);

Get folder details for the given folder version by path with a minimal response.

CompletableFuture<Response<MinimalFolder>> folderResponse = client.folders().getVersionWithMinimalResponse(<spaceId>,"<PATH>", <version>);

List Versions by Path

List all versions of a folder by path.

CompletableFuture<Response<FolderList>> folderResponse = client.folders().listVersions(<spaceId>, "<PATH>");

List all versions of a folder by path with a minimal response.

CompletableFuture<Response<MinimalFolderList>> folderResponse = client.folders().listVersionsWithMinimalResponse(<spaceId>, "<PATH>");

Files

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

File Permissions:

Note: When updating file permissions, use FileAcl with fileAclBuilder() for version-specific access. The standard Acl is deprecated for file permissions and maintained for backward compatibility only.

Get by Path

Get file by path.

CompletableFuture<Response<File>> fileResponse = client.files().get(<spaceId>, <path>);

Get file by path with parameters.

GetFileParams params = GetFileParams.builder().status(Status.ACTIVE_DELETED).urlDuration("80m").build();

CompletableFuture<Response<File>> fileResponse = client.files().get(<spaceId>,<path>, params);

Get file by path with a minimal response.

CompletableFuture<Response<MinimalFile>> fileResponse = client.files().getWithMinimalResponse(<spaceId>, <path>);

Get file by path with parameters and a minimal response.

GetFileParams params = GetFileParams.builder().status(Status.ACTIVE_DELETED).urlDuration("80m").build();

CompletableFuture<Response<MinimalFile>> fileResponse = client.files().getWithMinimalResponse(<spaceId>,<path>, params);

Get by ID

Get file by ID.

CompletableFuture<Response<File>> fileResponse = client.files().get(<spaceId>, <fileId>);

Get file by ID with parameters.

GetFileParams params = GetFileParams.builder().status(Status.ACTIVE_DELETED).urlDuration("80m").build();

CompletableFuture<Response<File>> fileResponse = client.files().get(<spaceId>,<fileId>, params);

Get file by ID with a minimal response.

CompletableFuture<Response<MinimalFile>> fileResponse = client.files().getWithMinimalResponse(<spaceId>, <fileId>);

Get file by ID with parameters and a minimal response.

GetFileParams params = GetFileParams.builder().status(Status.ACTIVE_DELETED).urlDuration("80m").build();

CompletableFuture<Response<MinimalFile>> fileResponse = client.files().getWithMinimalResponse(<spaceId>,<fileId>, params);

Update

Updates a file’s metadata, ACL settings, or links.

HashMap<String, Object> metadata = new HashMap<>();
metadata.put("key", "value");

UpdateFileRequest request = UpdateFileRequest.builder().metadata(metadata).build();

CompletableFuture<Response<File>> fileResponse = client.files().update(<spaceId>, <fileId>, request);

To update file permissions with version-specific access use FileAcl and fileAclBuilder. Acl for File permissions local is deprecated.

List<FileAcl> fileAclList = new ArrayList<>();
Date expiryDate = new Date(System.currentTimeMillis() + (30L * 24 * 60 * 60 * 1000));
fileAclList.add(FileAcl.builder()
        .actor(new AclApplicationIdentity(UUID.fromString("<APPLICATION_ID>")))
        .role(AclRole.CONTENT_VIEWER)
        .versions(Arrays.asList("1", "2"))  // Allow access to specific versions only
        .accessExpiresAt(expiryDate)
        .build());
UpdateFilePermissionsLocal permissionsLocal = UpdateFilePermissionsLocal.fileAclBuilder()
        .replaceFileAcl(fileAclList)
        .build();

UpdateFileRequest request = UpdateFileRequest.builder()
        .permissionsLocal(permissionsLocal)
        .build();

CompletableFuture<Response<File>> fileResponse = client.files().update(<spaceId>, <fileId>, request);

Update file permissions by adding and removing specific FileAcl entries:

List<FileAcl> addFileAclList = new ArrayList<>();
addFileAclList.add(FileAcl.builder()
        .actor(new AclApplicationIdentity(UUID.fromString("<APPLICATION_ID>")))
        .role(AclRole.CONTENT_CONTRIBUTOR)
        .versions(Arrays.asList("3"))  // Grant access to version 3
        .build());

List<AclActor> removeAclList = new ArrayList<>();
removeAclList.add(new AclApplicationIdentity(UUID.fromString("<APPLICATION_ID>")));

UpdateFileAcl updateAcl = UpdateFileAcl.fileAclBuilder()
        .addFileAcl(addFileAclList)
        .remove(removeAclList)
        .build();

UpdateFilePermissionsLocal permissionsLocal = UpdateFilePermissionsLocal.fileAclBuilder()
        .updateAcl(updateAcl)
        .build();

UpdateFileRequest request = UpdateFileRequest.builder()
        .permissionsLocal(permissionsLocal)
        .build();

CompletableFuture<Response<File>> fileResponse = client.files().update(<spaceId>, <fileId>, request);

Update a file with expiration date:

UpdateFileRequest request = UpdateFileRequest.builder()
        .metadata(metadata)
        .expiresAt(expirationDate)  // File will be automatically removed at this time
        .build();

CompletableFuture<Response<File>> fileResponse = client.files().update(<spaceId>, <fileId>, request);

Updates a file’s metadata, ACL settings, or links with request header.

HashMap<String, Object> metadata = new HashMap<>();
metadata.put("key", "value");

UpdateFileRequest request = UpdateFileRequest.builder().metadata(metadata).build();

RequestHeader requestHeader = RequestHeader.builder()
        .ifMatch("1.5")
        .build();

CompletableFuture<Response<File>> fileResponse = client.files().update(<spaceId>, <fileId>, request, requestHeader);

Updates the file and return a minimal response.

HashMap<String,Object> metadata = new HashMap<String, Object>();
metadata.put("key", "value");

UpdateFileRequest request = UpdateFileRequest.builder().metadata(metadata).build();

CompletableFuture<Response<MinimalFile>> fileResponse = client.files().updateWithMinimalResponse(<spaceId>, <fileId>, request);

Delete

Deletes the file.

CompletableFuture<Response<JobInfo>> fileResponse = client.files().delete(<spaceId>, <fileId>);

Deletes the file.

CompletableFuture<Response<JobInfo>> fileResponse = client.files().delete(<spaceId>, <fileId>, <permanent>);

Deletes a file.

DeleteFileRequest request = DeleteFileRequest.builder()
        .spaceId(spaceId)
        .fileId(fileId)
        .build();

CompletableFuture<Response<JobInfo>> fileResponse = client.files().delete(request);

Deletes a file with request header.

DeleteFileRequest request = DeleteFileRequest.builder()
        .spaceId(spaceId)
        .fileId(fileId)
        .build();

RequestHeader requestHeader = RequestHeader.builder()
        .ifMatch("1.5")
        .build();

CompletableFuture<Response<JobInfo>> fileResponse = client.files().delete(request, requestHeader);

Move

Moves a file to a new location within the same space.

MoveFileRequest request = MoveFileRequest.builder()
        .spaceId(spaceId)
        .fileId(fileId)
        .targetParentId(UUID.fromString(<targetParentId>))
        .build();

CompletableFuture<Response<File>> fileResponse = client.files().move(request);

Moves a file to a new location within the same space with request header.

MoveFileRequest request = MoveFileRequest.builder()
        .spaceId(spaceId)
        .fileId(fileId)
        .targetParentId(UUID.fromString(<targetParentId>))
        .build();

RequestHeader requestHeader = RequestHeader.builder()
        .ifMatch("1.5")
        .build();

CompletableFuture<Response<File>> fileResponse = client.files().move(request, requestHeader);

Move a file to a new location within the same space.

CompletableFuture<Response<File>> fileResponse = client.files().move(<spaceId>, <fileId>, <targetParentId>);

Move a file to a new location within the same space and returns a minimal response.

CompletableFuture<Response<MinimalFile>> fileResponse = client.files().moveWithMinimalResponse(<spaceId>, <fileId>, <targetParentId>);

Rename

Renames a file within the same space.

RenameFileRequest request = RenameFileRequest.builder()
        .spaceId(spaceId)
        .fileId(fileId)
        .name("new_name")
        .build();

CompletableFuture<Response<File>> fileResponse = client.files().rename(request);

Renames a file within the same space with request header.

RenameFileRequest request = RenameFileRequest.builder()
        .spaceId(spaceId)
        .fileId(fileId)
        .name("new_name")
        .build();

RequestHeader requestHeader = RequestHeader.builder()
        .ifMatch("1.5")
        .build();

CompletableFuture<Response<File>> fileResponse = client.files().rename(request, requestHeader);

Rename a file within the same space.

CompletableFuture<Response<File>> fileResponse = client.files().rename(<spaceId>, <fileId>, "<NEW_NAME>");

Rename a file within the same space and returns a minimal response.

CompletableFuture<Response<MinimalFile>> fileResponse = client.files().renameWithMinimalResponse(<spaceId>, <fileId>, "<NEW_NAME>");

Copy

Copies a file from one folder to another within the given space.

CopyFileRequest request = CopyFileRequest.builder()
        .spaceId(spaceId)
        .fileId(fileId)
        .targetParentId(UUID.fromString(<targetParentId>))
        .build();

CompletableFuture<Response<FileJobResponse>> fileResponse = client.files().copy(request);

Copies a file from one folder to another within the given space with request header.

CopyFileRequest request = CopyFileRequest.builder()
        .spaceId(spaceId)
        .fileId(fileId)
        .targetParentId(UUID.fromString(<targetParentId>))
        .build();

RequestHeader requestHeader = RequestHeader.builder()
        .ifMatch("*")
        .build();

CompletableFuture<Response<FileJobResponse>> fileResponse = client.files().copy(request, requestHeader);

Copies a file from one folder to another within the given space.

CopyFileParams params = CopyFileParams.builder().name("<NEW_NAME>").build();

CompletableFuture<Response<FileJobResponse>> response = client.files().copy(<spaceId>, <fileId>, <targetParentId>, params);

Copies a file from one folder to another within the given space and returns a minimal response.

CompletableFuture<Response<MinimalFileJobResponse>> response = client.files().copyWithMinimalResponse(<spaceId>, <fileId>, <targetParentId>);

Copy by Version

Copies a specific version of a file to a new location within the same space.

CopyFileRequest request = CopyFileRequest.builder()
        .spaceId(spaceId)
        .fileId(fileId)
        .targetParentId(UUID.fromString(<targetParentId>))
        .version(<version>)
        .build();

CompletableFuture<Response<FileJobResponse>> fileResponse = client.files().copy(request);

Restore

Restores a file from the deleted state.

RestoreFileRequest request = RestoreFileRequest.builder()
        .spaceId(spaceId)
        .fileId(fileId)
        .build();

CompletableFuture<Response<FileJobResponse>> fileResponse = client.files().restore(request);

Restores a file from the deleted state with request header.

RestoreFileRequest request = RestoreFileRequest.builder()
        .spaceId(spaceId)
        .fileId(fileId)
        .build();

RequestHeader requestHeader = RequestHeader.builder()
        .ifMatch("1.5")
        .build();

CompletableFuture<Response<FileJobResponse>> fileResponse = client.files().restore(request, requestHeader);

Restore a file from the deleted state.

CompletableFuture<Response<FileJobResponse>> response = client.files().restore(<spaceId>, <fileId>);

Restore a file from the deleted state. with parameters.

RestoreFileParams params = RestoreFileParams.builder().name("<NEW_NAME>").build();

CompletableFuture<Response<FileJobResponse>> response = client.files().restore(<spaceId>, <fileId>, params);

Restore a file from the deleted state and returns a minimal response.

CompletableFuture<Response<MinimalFileJobResponse>> response = client.files().restoreWithMinimalResponse(<spaceId>, <fileId>);

Get Version by ID

Get a specific version of a file by ID.

CompletableFuture<Response<File>> fileResponse = client.files().getVersion(<spaceId>, <fileId>, <version>);

Get a specific version of a file by ID with parameters.

GetFileParams params = GetFileParams.builder().status(Status.ACTIVE_DELETED).urlDuration("80m").build();

CompletableFuture<Response<File>> fileResponse = client.files().getVersion(<spaceId>,<fileId>, <version>, params);

Get a specific version of a file by ID with a minimal response.

GetFileParams params = GetFileParams.builder().status(Status.ACTIVE_DELETED).urlDuration("80m").build();

CompletableFuture<Response<MinimalFile>> fileResponse = client.files().getVersionWithMinimalResponse(<spaceId>,<fileId>, <version>, params);

List Versions

Get all versions of a file by ID.

CompletableFuture<Response<FileList>> fileResponse = client.files().listVersions(<spaceId>, <fileId>);

Get all versions of a file by ID with parameters.

ListFileParams params = ListFileParams.builder().status(Status.ACTIVE_DELETED).build();

CompletableFuture<Response<FileList>> fileResponse = client.files().listVersions(<spaceId>, <fileId>, params);

Get all versions of a file by ID with a minimal response.

ListFileParams params = ListFileParams.builder().status(Status.ACTIVE_DELETED).build();

CompletableFuture<Response<MinimalFileList>> fileResponse = client.files().listVersionsWithMinimalResponse(<spaceId>, <fileId>, params);

List Resources

Lists all resources (support files) of a file by ID.

CompletableFuture<Response<FileList>> fileResponse = client.files().listResources(<spaceId>, <fileId>);

Lists all resources (support files) of a file by ID with parameters.

ListFileParams params = ListFileParams.builder().status(Status.ACTIVE_DELETED).build();

CompletableFuture<Response<FileList>> fileResponse = client.files().listResources(<spaceId>, <fileId>, params);

Lists all resources (support files) of a file by ID with a minimal response.

ListFileParams params = ListFileParams.builder().status(Status.ACTIVE_DELETED).build();

CompletableFuture<Response<MinimalFileList>> fileResponse = client.files().listResourcesWithMinimalResponse(<spaceId>, <fileId>, params);

Get Version by Path

Get a specific version of a file by path.

CompletableFuture<Response<File>> fileResponse = client.files().getVersion(<spaceId>, <path>, <version>);

Get a specific version of a file by path with parameters.

GetFileParams params = GetFileParams.builder().status(Status.ACTIVE_DELETED).urlDuration("80m").build();

CompletableFuture<Response<File>> fileResponse = client.files().getVersion(<spaceId>,<path>, <version>, params);

Get a specific version of a file by path with a minimal response.

GetFileParams params = GetFileParams.builder().status(Status.ACTIVE_DELETED).urlDuration("80m").build();

CompletableFuture<Response<MinimalFile>> fileResponse = client.files().getVersionWithMinimalResponse(<spaceId>,<path>, <version>, params);

List Versions by Path

Get all versions of a file by path.

CompletableFuture<Response<FileList>> fileResponse = client.files().listVersions(<spaceId>, <path>);

Get all versions of a file by path with parameters.

ListFileParams params = ListFileParams.builder().status(Status.ACTIVE_DELETED).build();

CompletableFuture<Response<FileList>> fileResponse = client.files().listVersions(<spaceId>, <path>, params);

Get all versions of a file by path with a minimal response.

ListFileParams params = ListFileParams.builder().status(Status.ACTIVE_DELETED).build();

CompletableFuture<Response<MinimalFileList>> fileResponse = client.files().listVersionsWithMinimalResponse(<spaceId>, <path>, params);

List Resources by path

Lists all resources (support files) of a file by path.

CompletableFuture<Response<FileList>> fileResponse = client.files().listResources(<spaceId>, <path>);

Lists all resources (support files) of a file by path with parameters.

ListFileParams params = ListFileParams.builder().status(Status.ACTIVE_DELETED).build();

CompletableFuture<Response<FileList>> fileResponse = client.files().listResources(<spaceId>, <path>, params);

Lists all resources (support files) of a file by path with a minimal response.

ListFileParams params = ListFileParams.builder().status(Status.ACTIVE_DELETED).build();

CompletableFuture<Response<MinimalFileList>> fileResponse = client.files().listResourcesWithMinimalResponse(<spaceId>, <path>, params);

List Fileset Manifest

List all files from inside the unpacked fileset by file ID.

CompletableFuture<Response<ManifestFileList>> manifestResponse = client.files().listManifest(<spaceId>, <fileId>);

List manifest files with parameters.

ListManifestParams params = ListManifestParams.builder()
        .pageSize(25)
        .nextPageToken("<NEXT_PAGE_TOKEN>")
        .urlDuration("60m")
        .build();

CompletableFuture<Response<ManifestFileList>> manifestResponse = client.files().listManifest(<spaceId>, <fileId>, params);

Create File Upload

Generates a pre-signed upload url for the given name and parentId.

CreateFileUploadRequest request = CreateFileUploadRequest.builder()
                .parentId(parentId) // // Set the parentId to the folder you want to upload the file to
                .name("test_file")
                .multipart(true)
                .build();

CompletableFuture<Response<UploadDetails>> fileUploadResponse = client.files().createFileUpload(<spaceId>, request);

Create file upload with ACL permissions:

List<Acl> aclList = new ArrayList<>();
aclList.add(Acl.builder()
        .actor(new AclApplicationIdentity(UUID.fromString("<APPLICATION_ID>")))
        .role(AclRole.CONTENT_VIEWER)
        .build());

FilePermissionsLocal permissionsLocal = FilePermissionsLocal.builder()
        .inherits(true)
        .acl(aclList)
        .build();

CreateFileUploadRequest request = CreateFileUploadRequest.builder()
        .parentId(parentId)
        .name("test_file")
        .multipart(true)
        .permissionsLocal(permissionsLocal)
        .build();

CompletableFuture<Response<UploadDetails>> fileUploadResponse = client.files().createFileUpload(<spaceId>, request);

Create file upload with version-specific ACL permissions using FileAcl:

List<FileAcl> fileAclList = new ArrayList<>();
Date expiryDate = new Date(System.currentTimeMillis() + (30L * 24 * 60 * 60 * 1000));
fileAclList.add(FileAcl.builder()
        .actor(new AclApplicationIdentity(UUID.fromString("<APPLICATION_ID>")))
        .role(AclRole.CONTENT_VIEWER)
        .versions(Arrays.asList("1", "2"))  // Allow access to specific versions only
        .accessExpiresAt(expiryDate)
        .build());

FilePermissionsLocal permissionsLocal = FilePermissionsLocal.fileAclBuilder()
        .inherits(true)
        .fileAcl(fileAclList)
        .build();

CreateFileUploadRequest request = CreateFileUploadRequest.builder()
        .parentId(parentId)
        .name("test_file")
        .multipart(true)
        .permissionsLocal(permissionsLocal)
        .build();

CompletableFuture<Response<UploadDetails>> fileUploadResponse = client.files().createFileUpload(<spaceId>, request);

Generates a pre-signed upload url for the given name and parentId with request header.

CreateFileUploadRequest request = CreateFileUploadRequest.builder()
                .parentId(parentId)
                .name("test_file")
                .multipart(true)
                .build();

RequestHeader requestHeader = RequestHeader.builder()
        .ifMatch("*")
        .build();

CompletableFuture<Response<UploadDetails>> fileUploadResponse = client.files().createFileUpload(<spaceId>, request, requestHeader);

Create Support File Upload

Generates a pre-signed upload url for the given name and parentId.

CreateSupportFileUploadRequest request = CreateSupportFileUploadRequest.builder()
        .parentId(parentId) // Here parentId must be the ID of a file.
        .name("test_support_file")
        .build();

CompletableFuture<Response<UploadDetails>> uploadResponse = client.files().createSupportFileUpload(<spaceId>, request);

Generates a pre-signed upload url for the given name and parentId with request header.

CreateSupportFileUploadRequest request = CreateSupportFileUploadRequest.builder()
        .parentId(parentId) // Here parentId must be the ID of a file.
        .name("test_support_file")
        .build();

RequestHeader requestHeader = RequestHeader.builder()
        .ifMatch("*")
        .build();

CompletableFuture<Response<UploadDetails>> uploadResponse = client.files().createSupportFileUpload(<spaceId>, request, requestHeader);

Create Package Upload

Creates a package upload. The package upload is used for transactional uploads of a file and its related support files. A maximum of 10 support files can be included in the package upload and by default, the support file links are added to the main file.

List<SupportFileResource> supportFiles = new ArrayList<>();
supportFiles.add(SupportFileResource.builder().name("support_file_1").build());
supportFiles.add(SupportFileResource.builder().name("support_file_2").supportFileKey("KEY").build());

CreatePackageUploadRequest request = CreatePackageUploadRequest.builder()
        .spaceId(spaceId)
        .parentId(parentId)
        .name("test_file")
        .supportFileResources(supportFiles)
        .build();

CompletableFuture<Response<UploadDetails>> uploadResponse = client.files().createPackageUpload(request);

Create package upload with ACL permissions:

List<SupportFileResource> supportFiles = new ArrayList<>();
supportFiles.add(SupportFileResource.builder().name("support_file_1").build());
supportFiles.add(SupportFileResource.builder().name("support_file_2").supportFileKey("KEY").build());

List<FileAcl> fileAclList = new ArrayList<>();
fileAclList.add(FileAcl.builder()
        .actor(new AclApplicationIdentity(UUID.fromString("<APPLICATION_ID>")))
        .role(AclRole.CONTENT_VIEWER)
        .versions(Arrays.asList("1", "2"))
        .build());

FilePermissionsLocal permissionsLocal = FilePermissionsLocal.fileAclBuilder()
        .inherits(true)
        .fileAcl(fileAclList)
        .build();

CreatePackageUploadRequest request = CreatePackageUploadRequest.builder()
        .spaceId(spaceId)
        .parentId(parentId)
        .name("test_file")
        .supportFileResources(supportFiles)
        .permissionsLocal(permissionsLocal)
        .build();

CompletableFuture<Response<UploadDetails>> uploadResponse = client.files().createPackageUpload(request);

Creates a package upload with request header.

List<SupportFileResource> supportFiles = new ArrayList<>();
supportFiles.add(SupportFileResource.builder().name("support_file_1").build());
supportFiles.add(SupportFileResource.builder().name("support_file_2").supportFileKey("KEY").build());

CreatePackageUploadRequest request = CreatePackageUploadRequest.builder()
        .spaceId(spaceId)
        .parentId(parentId)
        .name("test_file")
        .supportFileResources(supportFiles)
        .build();

RequestHeader requestHeader = RequestHeader.builder()
        .ifMatch("*")
        .build();

CompletableFuture<Response<UploadDetails>> uploadResponse = client.files().createPackageUpload(request, requestHeader);

Create or Update Links

Link support files to a file.

SupportFileDetails supportFileDetails = SupportFileDetails.builder()
        .id(supportFileId).build();

HashMap<String, SupportFileDetails> links = new HashMap<String, SupportFileDetails>();
links.put("key", supportFileDetails);

SupportFileLinkRequest request = SupportFileLinkRequest.builder()
        .links(links)
        .build();

CompletableFuture<Response<File>> uploadResponse = client.files().createOrUpdateLinks(<spaceId>, <fileId>, <fileMajorVersion>, request);

Link support files to a file and return a minimal response.

SupportFileDetails supportFileDetails = SupportFileDetails.builder()
        .id(supportFileId).build();

HashMap<String, SupportFileDetails> links = new HashMap<String, SupportFileDetails>();
links.put("key", supportFileDetails);

SupportFileLinkRequest request = SupportFileLinkRequest.builder()
        .links(links)
        .build();

CompletableFuture<Response<MinimalFile>> uploadResponse = client.files().createOrUpdateLinksWithMinimalResponse(<spaceId>, <fileId>, <fileMajorVersion>, request);

Upload

Upload a file to the given uploadId. Can be used to upload file or support file.

For multipart uploads, the file is divided and uploaded in segments to pre-signed URLs. Once all parts are uploaded, the upload status is set to COMPLETED.

• maxConcurrentRequests defaults to 4 but can be adjusted.
• chunkSize is set at 5MB by default (5 * 1024 * 1024 bytes).

TransferFileConfiguration transferFileConfiguration = TransferFileConfiguration.builder()
        .chunkSize(10 * 1024 * 1024)
        .maxConcurrentRequests(6).build();

java.io.File file = new java.io.File("path_to_file");

CompletableFuture<Boolean> isUploaded = client.files().upload(<spaceId>, <uploadId>, file, transferFileConfiguration);

Upload Package

Upload a file along with support files to the given package upload ID.

java.io.File mainFile = new java.io.File("path_to_file");

List<SupportFileResourceUploadItem> supportFileResources = new ArrayList<>();
supportFileResources.add(SupportFileResourceUploadItem.builder().supportFileKey("key_1")
        .supportFile(new java.io.File("path_to_file")).build());
supportFileResources.add(SupportFileResourceUploadItem.builder().supportFileKey("key_2")
        .supportFile(new java.io.File("path_to_file")).build());

CompletableFuture<Boolean> isUploaded = client.files().upload(<spaceId>, <uploadId>, mainFile, supportFileResources);

Complete Multipart

Mark the multipart file upload status to be COMPLETED.

PartETag part1 = PartETag.builder().eTag("etag1").partNumber(1).build();
PartETag part2 = PartETag.builder().eTag("etag2").partNumber(2).build();
ArrayList<PartETag> parts = new ArrayList<>();
parts.add(part1);
parts.add(part2);

CreateCompleteMultipartRequest partETags = CreateCompleteMultipartRequest.builder()
        .spaceId(<spaceId>)
        .uploadId(<uploadId>).parts(parts).build();

CompletableFuture<Response<UploadDetails>> fileResponse = client.files().completeMultipart(partETags);

Download

Download a file by ID.

java.io.File file = new java.io.File("path_to_file");

CompletableFuture<Boolean> downloadResponse = client.files().download(<spaceId>, <fileId>, file);

Download a file by ID with configuration.

java.io.File file = new java.io.File("path_to_file");

TransferFileConfiguration transferFileConfiguration = TransferFileConfiguration.builder()
        .chunkSize(10 * 1024 * 1024)
        .maxConcurrentRequests(6).build();

CompletableFuture<Boolean> downloadResponse = client.files().download(
        <spaceId>,
        <fileId>, file, transferFileConfiguration);

Poll for Upload Status

Poll the upload status by Id. If the status is COMPLETED or FAILED, it returns the uploadResponse. Otherwise, it waits for delay second and recursively calls itself to poll again.

CompletableFuture<Response<UploadDetails>> uploadResponse = client.files().waitForUpload(<spaceId>, <uploadId>,
        <poll_interval>,
        <timeout_interval>, callback -> {
            // Get upload details, polling the upload until it is completed or failed.
        });

Get Upload Details

Retrieve the upload details by ID.

CompletableFuture<Response<UploadDetails>> uploadResponse = client.files().getUploadDetails(<spaceId>, <uploadId>);

Retrieve the upload details by ID with custom URL duration.

CompletableFuture<Response<UploadDetails>> uploadResponse = client.files().getUploadDetails(<spaceId>, <uploadId>, "120m");

Retrieve the upload details with optimized polling.

GetUploadDetailsParams params = GetUploadDetailsParams.builder()
        .longPoll(true)          // Enable long polling
        .fastCheck(true)         // Use 0.1s interval for first 7 calls, then 1s
        .build();

CompletableFuture<Response<UploadDetails>> uploadResponse = client.files().getUploadDetails(<spaceId>, <uploadId>, params);

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.

LockFileRequest request = LockFileRequest.builder()
        .spaceId(<spaceId>)
        .fileId(<fileId>)
        .reason("Reason for locking the file").build();

CompletableFuture<Response<File>> fileResponse = client.files().lock(request);

Lock a file and return a minimal response.

LockFileRequest request = LockFileRequest.builder()
        .spaceId(<spaceId>)
        .fileId(<fileId>)
        .reason("Reason for locking the file").build();

CompletableFuture<Response<MinimalFile>> fileResponse = client.files().lockWithMinimalResponse(request);

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.

UnlockFileRequest request = UnlockFileRequest.builder()
        .spaceId(<spaceId>)
        .fileId(<fileId>).build();

CompletableFuture<Response<File>> fileResponse = client.files().unlock(request);

Unlock a file and return a minimal response.

UnlockFileRequest request = UnlockFileRequest.builder()
        .spaceId(<spaceId>)
        .fileId(<fileId>).build();

CompletableFuture<Response<MinimalFile>> fileResponse = client.files().unlockWithMinimalResponse(request);

Checkout

Checkout a file within a space. Checking out a file will prevent other actors from creating a new version or performing other mutation operations.

CheckoutFileRequest request = CheckoutFileRequest.builder()
        .spaceId(<spaceId>)
        .fileId(<fileId>)
        .build();

CompletableFuture<Response<File>> fileResponse = client.files().checkout(request);

Checkout a file with a request header.

CheckoutFileRequest request = CheckoutFileRequest.builder()
        .spaceId(<spaceId>)
        .fileId(<fileId>)
        .build();

RequestHeader requestHeader = RequestHeader.builder()
        .ifMatch("1.5")
        .build();

CompletableFuture<Response<File>> fileResponse = client.files().checkout(request, requestHeader);

Checkout a file and return a minimal response.

CheckoutFileRequest request = CheckoutFileRequest.builder()
        .spaceId(<spaceId>)
        .fileId(<fileId>)
        .build();

CompletableFuture<Response<MinimalFile>> fileResponse = client.files().checkoutWithMinimalResponse(request);

Checkout a file with a request header and return a minimal response.

CheckoutFileRequest request = CheckoutFileRequest.builder()
        .spaceId(<spaceId>)
        .fileId(<fileId>)
        .build();

RequestHeader requestHeader = RequestHeader.builder()
        .ifMatch("1.5")
        .build();

CompletableFuture<Response<MinimalFile>> fileResponse = client.files().checkoutWithMinimalResponse(request, requestHeader);

Checkin

Checkin a file within a space. Checking in a file will allow other actors to create a new version or perform other mutation operations.

CheckinFileRequest request = CheckinFileRequest.builder()
        .spaceId(<spaceId>)
        .fileId(<fileId>)
        .build();

CompletableFuture<Response<File>> fileResponse = client.files().checkin(request);

Checkin a file and return a minimal response.

CheckinFileRequest request = CheckinFileRequest.builder()
        .spaceId(<spaceId>)
        .fileId(<fileId>)
        .build();

CompletableFuture<Response<MinimalFile>> fileResponse = client.files().checkinWithMinimalResponse(request);

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 for a given job ID.

CompletableFuture<Response<Job>> jobResponse = client.jobs().get(<jobId>);

Get job details with optimized polling.

GetJobParams params = GetJobParams.builder()
        .longPoll(true)      // Enable long polling
        .fastCheck(true)     // Use 0.1s interval for first 7 calls, then 1s
        .build();

CompletableFuture<Response<Job>> jobResponse = client.jobs().get(<jobId>, params);

Poll for Job Status

Poll the job status by Id. If the status is COMPLETED or FAILED, it returns the jobResponse. Otherwise, it waits for delay second and recursively calls itself to poll again.

CompletableFuture<Response<Job>> jobResponse = client.jobs().waitForJob(<jobId>, <delay>, <timeout>);
CompletableFuture<Response<Job>> jobResponse = client.jobs().waitForJob(<jobId>,
        <poll_interval>,
        <timeout_interval>, callback -> {
            // Get job details, polling the job until it is completed or failed.
        });

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 for the given folder ID.

CreateExportRequest request = CreateExportRequest.builder()
        .spaceId(<spaceId>)
        .folderId(<folderId>)
        .build();

CompletableFuture<Response<ExportInfo>> exportInfoResponse = client.exports().create(request);

The includeTopLevel parameter controls whether the exported ZIP file includes the top-level folder as the first subfolder or only its children. By default, it is set to true.

// Export only the children of the folder
CreateExportRequest request = CreateExportRequest.builder()
        .spaceId(<spaceId>)
        .folderId(<folderId>)
        .includeTopLevel(false)
        .build();

CompletableFuture<Response<ExportInfo>> exportInfoResponse = client.exports().create(request);

Get

Get export by ID. This uses the default urlDuration of 60 minutes for the export download URL.

CompletableFuture<Response<Export>> exportResponse = client.exports().get(<exportId>);

The urlDuration parameter can be used to specify the download URL validity duration. It can be set in days (d), hours (h), or minutes (m). Minimum value is 5 minutes (5m), maximum value is 7 days (7d).

Example: 300m, 10h, 2d

CompletableFuture<Response<Export>> exportResponse = client.exports().get(<exportId>, "120m");

Resources

Resources represent a folder, file, or support file

Get Resource by ID

Retrieve a resource by its ID.

CompletableFuture<Response<Resource>> resourceResponse = client.resources().get(spaceId, resourceId);

Retrieve a resource by its ID with filtering parameters.

GetResourceParams params = GetResourceParams.builder()
        .status(Status.ACTIVE)
        .urlDuration("60m")
        .build();

CompletableFuture<Response<Resource>> resourceResponse = client.resources().get(spaceId, resourceId, params);

Retrieve a minimal resource by its ID.

CompletableFuture<Response<MinimalResource>> resourceResponse = client.resources().getWithMinimalResponse(spaceId, resourceId);

Retrieve a minimal resource by its ID with filtering parameters.

GetResourceParams params = GetResourceParams.builder()
        .status(Status.ACTIVE)
        .urlDuration("60m")
        .build();

CompletableFuture<Response<MinimalResource>> resourceResponse = client.resources().getWithMinimalResponse(spaceId, resourceId, params);

Get Resource by Path

Retrieve a resource by its path.

CompletableFuture<Response<Resource>> resourceResponse = client.resources().get(spaceId, path);

Retrieve a resource by its path with filtering parameters.

GetResourceParams params = GetResourceParams.builder()
        .status(Status.ACTIVE)
        .urlDuration("60m")
        .build();

CompletableFuture<Response<Resource>> resourceResponse = client.resources().get(spaceId, path, params);

Retrieve a minimal resource by its path.

CompletableFuture<Response<MinimalResource>> resourceResponse = client.resources().getWithMinimalResponse(spaceId, path);

Retrieve a minimal resource by its path with filtering parameters.

GetResourceParams params = GetResourceParams.builder()
        .status(Status.ACTIVE)
        .urlDuration("60m")
        .build();

CompletableFuture<Response<MinimalResource>> resourceResponse = client.resources().getWithMinimalResponse(spaceId, path, params);

Get Resources in Batch

Retrieve multiple resources in a batch by specifying a list of IDs or paths.

BatchResourceRequest request = BatchResourceRequest.builder()
        .ids(Arrays.asList(UUID.fromString("<RESOURCE_ID_1>"), UUID.fromString("<RESOURCE_ID_2>")))
        .build();

CompletableFuture<Response<ResourceBatch>> resourceBatchResponse = client.resources().getBatch(spaceId, request);

Retrieve multiple resources in a batch with filtering parameters.

BatchResourceRequest request = BatchResourceRequest.builder()
        .ids(Arrays.asList(UUID.fromString("<RESOURCE_ID_1>"), UUID.fromString("<RESOURCE_ID_2>")))
        .build();

GetResourceParams params = GetResourceParams.builder()
        .status(Status.ACTIVE)
        .urlDuration("60m")
        .build();

CompletableFuture<Response<ResourceBatch>> resourceBatchResponse = client.resources().getBatch(spaceId, request, params);

Retrieve multiple minimal resources in a batch.

BatchResourceRequest request = BatchResourceRequest.builder()
        .ids(Arrays.asList(UUID.fromString("<RESOURCE_ID_1>"), UUID.fromString("<RESOURCE_ID_2>")))
        .build();

CompletableFuture<Response<MinimalResourceBatch>> resourceBatchResponse = client.resources().getBatchWithMinimalResponse(spaceId, request);

Retrieve multiple minimal resources in a batch with filtering parameters.

BatchResourceRequest request = BatchResourceRequest.builder()
        .ids(Arrays.asList(UUID.fromString("<RESOURCE_ID_1>"), UUID.fromString("<RESOURCE_ID_2>")))
        .build();

GetResourceParams params = GetResourceParams.builder()
        .status(Status.ACTIVE)
        .urlDuration("60m")
        .build();

CompletableFuture<Response<MinimalResourceBatch>> resourceBatchResponse = client.resources().getBatchWithMinimalResponse(spaceId, request, params);