Folders

Folders organize files inside a bucket. The hierarchy is a tree with a maximum depth of 8.

Operations

Operation	Method and path	Required scopes
List bucket folders	`GET /folders/findAll/{bucketId}`	`buckets:read` + `folders:read`
Folder details	`GET /folders/details/{folderId}`	`buckets:read` + `folders:read`
Direct subfolders	`GET /folders/{folderId}/subfolders`	`buckets:read` + `folders:read`
Folder content, paginated	`GET /folders/{folderId}/content`	`buckets:read` + `folders:read`
Create	`POST /folders/create/{bucketId}`	`buckets:write` + `folders:write`
Update	`PUT /folders/update/{folderId}`	`buckets:write` + `folders:write`
Delete	`DELETE /folders/delete/{folderId}`	`buckets:write` + `folders:delete`
Restore from trash	`POST /folders/restore-from-trash/{folderId}`	`buckets:write` + `folders:write`
Copy	`POST /folders/copy/{folderId}`	`buckets:write` + `folders:write`
Move	`POST /folders/move/{folderId}`	`buckets:write` + `folders:write`

Folder details fields

GET /folders/details/{folderId} returns:

Field	Meaning
`id`	Folder identifier
`name`	Display name
`visibility`	Visibility setting
`createdAt`, `updatedAt`, `lastAccessAt`	Timestamps
`totalFiles`	Files directly in the folder
`totalSubfolders`	Immediate subfolders
`totalSizeByte`	Aggregate size
`sharedUsersCount`	Sharing count
`ownerFolder`	Owning folder information
`displayPath`	Human-readable path
`locationLabel`	Location label
`parentId`, `parentName`	Parent reference
`isRoot`	Whether this is the root folder
`accessUrl`, `shareUrl`	Access links

Folder content

GET /folders/{folderId}/content returns a paginated object with subfolders before files:

{
  "folderId": "…",
  "folderName": "Contracts",
  "totalItems": 42,
  "totalFiles": 30,
  "totalFolders": 12,
  "page": 1,
  "limit": 20,
  "totalPages": 3,
  "content": []
}

Use sortBy, sortOrder, searchTerm, page, and limit to control the result.

Subfolders

GET /folders/{folderId}/subfolders is not paginated. It returns the full list plus a parent descriptor:

{
  "data": [],
  "total": 12,
  "parentFolder": { "id": "…", "name": "Contracts", "bucketId": "…" }
}

Prefer folder content when you need pagination on wide trees.

Create and update

Create body:

{ "name": "Contracts", "parentId": "optional-parent-folder-id" }

Update body accepts either or both:

{ "name": "Signed contracts", "parentId": "new-parent-folder-id" }

parentId semantics:

omitted on create: the folder is created at the bucket root,
null on update: move to root,
a UUID: move under that folder.

Delete and restore

Delete body:

{ "trash": "soft" }

`trash`	Effect
`soft` (default)	Moves to trash; restorable during the window
`hard`	Permanent removal

Delete returns data: null. Restore behavior:

a folder that is not in trash returns HTTP 200 with a message stating it is not in trash — this is not an error,
a folder past the trash window returns 410,
a missing folder returns 404.

Copy and move

Copy body requires a destination bucket and optionally a destination folder:

{ "destinationBucketId": "…", "destinationFolderId": "…" }

Move body:

{ "destinationFolderId": "…" }

For move, null means “move to the destination root”, while omitting the field entirely is rejected. Send null explicitly when you mean root.

Both operations answer with HTTP 200 and a data payload describing the result:

Operation	`data` fields
Copy	`originalFolderId`, `newFolderId`, `destinationBucketId`, `foldersCopied`, `filesCopied`, `copiedFileIds`
Move	`folderId`, `destinationFolderId`, `filesInFolder`, `childFoldersCount`

newFolderId is the root of the copy. The copy gets a collision-free name such as <name> (copy); the original folder name is unchanged by a move.

Depth limit

The maximum folder depth is 8. Creating a deeper path fails. Plan flattening before migrating a deep source tree.

Organize folders

Practical guide with examples.

Pagination

List shape and consistency.

Files overview

File operations.

Conventions

Envelopes and identifiers.

Overview

Endpoint Guides

Buckets

Files

Folders

Operations

Folder details fields

Folder content

Subfolders

Create and update

Delete and restore

Copy and move

Depth limit

Organize folders

Pagination

Files overview

Conventions

​Operations

​Folder details fields

​Folder content

​Subfolders

​Create and update

​Delete and restore

​Copy and move

​Depth limit

​Related

Organize folders

Pagination

Files overview

Conventions

Operations

Folder details fields

Folder content

Subfolders

Create and update

Delete and restore

Copy and move

Depth limit

Related