Organize folders

Folders are optional containers inside a bucket. They form a tree with a maximum depth of 8.

Endpoints

Operation	Endpoint	Capability
List root folders	`GET /folders/findAll/{bucketId}`	`folder:read`
Folder details	`GET /folders/details/{folderId}`	`folder:read`
Direct subfolders	`GET /folders/{folderId}/subfolders`	`folder:read`
Files and subfolders	`GET /folders/{folderId}/content`	`folder:read`
Create	`POST /folders/create/{bucketId}`	`folder:write`
Rename or reparent	`PUT /folders/update/{folderId}`	`folder:write`
Delete	`DELETE /folders/delete/{folderId}`	`folder:delete`
Restore from trash	`POST /folders/restore-from-trash/{folderId}`	`folder:restore`
Copy	`POST /folders/copy/{folderId}`	`folder:write`
Move	`POST /folders/move/{folderId}`	`folder:write`

Create a folder

POST /folders/create/{bucketId}

{
  "name": "contracts",
  "parentId": null
}

Field	Type	Required	Notes
`name`	string	Yes	1–255 characters
`parentId`	string or null	No	Must belong to the same bucket

Unknown fields are rejected. The server also rejects:

a duplicate name under the same parent (400),
a parent in a different bucket (400),
a deleted parent (400),
a tree deeper than 8 levels (400).

The response is the created folder object inside the normal envelope.

List root folders

GET /folders/findAll/{bucketId}?searchTerm=contract&page=1&limit=10&orderBy=asc

Query	Default	Notes
`searchTerm`	none	Case-insensitive name filter
`page`	`1`	1-based
`limit`	`10`	Page size
`orderBy`	`asc`	`asc` or `desc`

Each item includes hasSubfolders, totalSubfolders, sharedUsersCount, and an active sharedLink summary when one exists.

Folder details

GET /folders/details/{folderId}

{
  "status": 200,
  "message": "Folder found",
  "data": {
    "id": "4d1e2f3a-5b6c-4d7e-8f90-1a2b3c4d5e6f",
    "name": "contracts",
    "visibility": "private",
    "createdAt": "2026-09-02T10:14:00.000Z",
    "updatedAt": "2026-09-02T10:14:00.000Z",
    "lastAccessAt": null,
    "totalFiles": 12,
    "totalSubfolders": 2,
    "totalSizeByte": 1843200,
    "sharedUsersCount": 0,
    "ownerFolder": null,
    "displayPath": "/contracts",
    "locationLabel": "Frankfurt (FRA)",
    "parentId": null,
    "parentName": null,
    "isRoot": true,
    "accessUrl": "/folders/details/4d1e2f3a-5b6c-4d7e-8f90-1a2b3c4d5e6f",
    "shareUrl": "/folders/share/4d1e2f3a-5b6c-4d7e-8f90-1a2b3c4d5e6f"
  }
}

Values are illustrative. totalFiles and totalSubfolders are direct counts, not recursive. totalSizeByte sums non-deleted files directly in the folder.

Subfolders

GET /folders/{folderId}/subfolders?searchTerm=&orderBy=asc

Returns:

{
  "status": 200,
  "message": "Subfolders retrieved",
  "data": {
    "data": [
      {
        "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
        "name": "2026",
        "parentId": "4d1e2f3a-5b6c-4d7e-8f90-1a2b3c4d5e6f",
        "bucketId": "0f0b0c7e-6a1f-4b8e-9a3e-1f2c3d4e5f60",
        "visibility": "private",
        "createdAt": "2026-09-03T08:00:00.000Z",
        "updatedAt": "2026-09-03T08:00:00.000Z"
      }
    ],
    "total": 1,
    "parentFolder": {
      "id": "4d1e2f3a-5b6c-4d7e-8f90-1a2b3c4d5e6f",
      "name": "contracts",
      "bucketId": "0f0b0c7e-6a1f-4b8e-9a3e-1f2c3d4e5f60"
    }
  }
}

Subfolders are not paginated by this endpoint; total reflects the filtered list length.

Folder content

GET /folders/{folderId}/content?sortBy=name&sortOrder=asc&searchTerm=&page=1&limit=50

Query	Default	Notes
`sortBy`	`name`	`name` or `createdAt`
`sortOrder`	`asc`	`asc` or `desc`
`searchTerm`	none	Filters both files and folders
`page`	`1`	1-based
`limit`	`50`	Page size

Response:

{
  "status": 200,
  "message": "Folder content retrieved",
  "data": {
    "folderId": "4d1e2f3a-5b6c-4d7e-8f90-1a2b3c4d5e6f",
    "folderName": "contracts",
    "totalItems": 14,
    "totalFiles": 12,
    "totalFolders": 2,
    "page": 1,
    "limit": 50,
    "totalPages": 1,
    "content": [
      {
        "type": "folder",
        "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
        "name": "2026",
        "visibility": "private",
        "deviceId": null,
        "createdAt": "2026-09-03T08:00:00.000Z",
        "updatedAt": "2026-09-03T08:00:00.000Z",
        "totalFiles": 0,
        "totalSubfolders": 0,
        "sharedUsersCount": 0
      },
      {
        "type": "file",
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "name": "master-agreement",
        "sizeByte": 482133,
        "extFile": "pdf",
        "visibility": "private",
        "createdAt": "2026-09-04T11:20:00.000Z",
        "updatedAt": "2026-09-04T11:20:00.000Z",
        "isRetention": false,
        "retentionPeriod": null,
        "sharedUsersCount": 0
      }
    ]
  }
}

Subfolders are placed before files in the combined array. totalFiles and totalFolders reflect the filtered totals, not just the current page.

Rename or reparent

PUT /folders/update/{folderId}

{
  "name": "signed-contracts",
  "parentId": "4d1e2f3a-5b6c-4d7e-8f90-1a2b3c4d5e6f"
}

Both fields are optional, but at least one should be present. Unknown fields are rejected. Setting parentId to null makes the folder a root folder. The server rejects cycles, self-parenting, and depth violations.

Prefer POST /folders/move/{folderId} for moves. It returns a move summary and validates destination rules explicitly. PUT /folders/update is intended for renames and simple reparenting.

Move a folder

POST /folders/move/{folderId}

{
  "destinationFolderId": "4d1e2f3a-5b6c-4d7e-8f90-1a2b3c4d5e6f"
}

Use null to move the folder to the bucket root. A missing field is rejected. A folder cannot move into itself or into one of its descendants. Response:

{
  "status": 200,
  "message": "Folder moved",
  "data": {
    "folderId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "destinationFolderId": "4d1e2f3a-5b6c-4d7e-8f90-1a2b3c4d5e6f",
    "filesInFolder": 12,
    "childFoldersCount": 2
  }
}

Copy a folder

POST /folders/copy/{folderId}

{
  "destinationBucketId": "0f0b0c7e-6a1f-4b8e-9a3e-1f2c3d4e5f60",
  "destinationFolderId": null
}

destinationBucketId is required. The copy includes the entire subtree: child folders and non-deleted files. Source files that are in trash are excluded. Storage capacity must cover the duplicated bytes. Response:

{
  "status": 200,
  "message": "Folder copied",
  "data": {
    "originalFolderId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "newFolderId": "1f2e3d4c-5b6a-4987-8c0d-9e8f7a6b5c4d",
    "destinationBucketId": "0f0b0c7e-6a1f-4b8e-9a3e-1f2c3d4e5f60",
    "foldersCopied": 3,
    "filesCopied": 12,
    "copiedFileIds": [
      "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    ]
  }
}

foldersCopied counts the root plus descendants.

Delete and restore

DELETE /folders/delete/{folderId}
Content-Type: application/json

{ "trash": "soft" }

trash is soft (default) or hard. Soft delete cascades to descendant folders and files. Hard delete is permanent. The delete response has data: null on success. Restore with:

POST /folders/restore-from-trash/{folderId}

Restoring a folder that is not in trash returns HTTP 200 with the message “Folder is not in trash” and the folder ID in data. An elapsed display window returns 410. A missing folder returns 404.

Deleting a folder is a subtree operation. Confirm the child count with folder details before offering delete in your UI.

Common errors

Status	Cause
`400`	Invalid body, duplicate name, depth limit, cycle, or bad destination
`403`	Missing scope, bucket outside key scope, or access denied
`404`	Folder or destination not found
`402`	Insufficient storage for a copy
`410`	Restore window elapsed

Getting Started

Core Concepts

Authentication & Security

Storage Guides

Error Handling

Security & Data Protection

Enterprise & Partners

Resources

Endpoints

Create a folder

List root folders

Folder details

Subfolders

Folder content

Rename or reparent

Move a folder

Copy a folder

Delete and restore

Common errors

​Endpoints

​Create a folder

​List root folders

​Folder details

​Subfolders

​Folder content

​Rename or reparent

​Move a folder

​Copy a folder

​Delete and restore

​Common errors

Endpoints

Create a folder

List root folders

Folder details

Subfolders

Folder content

Rename or reparent

Move a folder

Copy a folder

Delete and restore

Common errors