> ## Documentation Index
> Fetch the complete documentation index at: https://docs.everabyte.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Organize folders

> Create, rename, move, copy, and delete folders, and read their contents.

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

```http theme={null}
POST /folders/create/{bucketId}
```

```json theme={null}
{
  "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

```http theme={null}
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

```http theme={null}
GET /folders/details/{folderId}
```

```json theme={null}
{
  "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

```http theme={null}
GET /folders/{folderId}/subfolders?searchTerm=&orderBy=asc
```

Returns:

```json theme={null}
{
  "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

```http theme={null}
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:

```json theme={null}
{
  "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

```http theme={null}
PUT /folders/update/{folderId}
```

```json theme={null}
{
  "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.

> [!NOTE]
>
> 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

```http theme={null}
POST /folders/move/{folderId}
```

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```http theme={null}
POST /folders/copy/{folderId}
```

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```http theme={null}
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:

```http theme={null}
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`.

> [!WARNING]
>
> 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.