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

# Folders

> Orientation for folder operations: tree structure, listing, details, content, create, update, delete, restore, copy, and move.

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:

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

```json theme={null}
{
  "data": [],
  "total": 12,
  "parentFolder": { "id": "…", "name": "Contracts", "bucketId": "…" }
}
```

Prefer folder content when you need pagination on wide trees.

## Create and update

Create body:

```json theme={null}
{ "name": "Contracts", "parentId": "optional-parent-folder-id" }
```

Update body accepts either or both:

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

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

```json theme={null}
{ "destinationBucketId": "…", "destinationFolderId": "…" }
```

Move body:

```json theme={null}
{ "destinationFolderId": "…" }
```

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

## Related

> **[Organize folders](https://docs.everabyte.com/storage/organize-folders.md)**
>
> Practical guide with examples.

> **[Pagination](https://docs.everabyte.com/api-reference/pagination.md)**
>
> List shape and consistency.

> **[Files overview](https://docs.everabyte.com/api-reference/files/overview.md)**
>
> File operations.

> **[Conventions](https://docs.everabyte.com/api-reference/conventions.md)**
>
> Envelopes and identifiers.


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