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

# Buckets, folders, and files

> How the storage hierarchy works, how IDs are used, and what list responses include.

## Hierarchy

```text theme={null}
Company
└── Bucket                 storage container, bound to a datacenter
    ├── Folder             optional, up to 8 levels deep
    │   ├── Subfolder
    │   └── File
    └── File               root-level file
```

A file always belongs to a bucket. A file may also belong to a folder. A folder always belongs to exactly one bucket.

## Buckets

A bucket has:

| Field | Meaning |
| - | - |
| `id` | Stable identifier used in API paths |
| `name` | Human-readable name |
| `code` | Provisioning code; the default bucket uses the same value for name and code |
| `retentionPeriod` | Active bucket retention, or `null` |
| `datacenterId` | Location binding |
| `createdAt`, `updatedAt` | Timestamps |

You can list the buckets a key can reach with `GET /buckets/all`, and read one bucket's stored size with `GET /buckets/size/{bucketId}`. Bucket creation, configuration, and deletion are dashboard operations: copy the `bucketId` and use it in the file and folder paths. See the [bucket operations](https://docs.everabyte.com/api-reference/buckets/overview.md).

## Folders

A folder has `id`, `name`, `visibility`, `parentId`, timestamps, and derived counters. Folder details add:

| Field | Meaning |
| - | - |
| `displayPath` | Slash-separated path for display |
| `locationLabel` | Region label, when resolvable |
| `isRoot` | True when the folder has no parent |
| `totalFiles`, `totalSubfolders` | Direct counts |
| `totalSizeByte` | Sum of non-deleted files directly in the folder |
| `sharedUsersCount` | Number of users with explicit access |
| `ownerFolder` | Owning folder context |
| `accessUrl`, `shareUrl` | Relative dashboard-style URLs |

Folder content is a combined, paginated list of subfolders and files. Each item carries a `type` of `folder` or `file`.

The folder tree has a maximum depth of **8**. Creating a folder deeper than that fails with `400`.

## Files

A file record exposed by list endpoints includes:

| Field | Meaning |
| - | - |
| `id` | Stable identifier |
| `name` | Display name, without extension |
| `extFile` | Extension, without the dot |
| `sizeByte` | Size in bytes |
| `readableSize` | Human-readable size in list responses |
| `visibility` | `private` or `public` |
| `retentionPeriod` | Active retention, when set |
| `isRetention` | Whether retention is currently active |
| `createdAt`, `updatedAt` | Timestamps |
| `tags` | Tag names, when present |
| `sharedUsersCount` | Number of explicit user shares |
| `sharedLink` | Active public link summary, when present |

List responses also include a `downloadUrl` of the form `/api/files/download/{fileId}`. This is a legacy display path; the documented download route is `GET /files/{fileId}/stream`.

## Listing root-level content vs folder content

Use the right endpoint for the level you are rendering:

| You want | Endpoint |
| - | - |
| The buckets a key can reach | `GET /buckets/all` |
| Files at the root of a bucket | `GET /files/findAll/{bucketId}` |
| Folders at the root of a bucket | `GET /folders/findAll/{bucketId}` |
| Files and folders inside one folder | `GET /folders/{folderId}/content` |
| Only direct subfolders | `GET /folders/{folderId}/subfolders` |
| Trashed files | `GET /files/deleted-files/{bucketId}` |

Root-level lists are paginated separately for files and folders. Folder content combines both types and paginates the combined result.

## Identifiers

Use opaque IDs exactly as returned. Do not construct IDs, infer ordering from them, or treat a name as unique. Folder creation rejects a duplicate name under the same parent, but files can share display names.

## Names and extensions

File names are returned without the extension, and the extension is returned separately in `extFile`. When you reconstruct a filename for display or download, join them with a dot only when `extFile` is non-empty.

The streaming download sets `X-File-Name` as a URL-encoded filename and `Content-Disposition` for safe saving. Prefer those headers over reconstructing a name yourself.

## Visibility

`visibility` controls whether a public share link can expose the file. It does not make a file anonymously readable by itself. Anonymous access requires a share link, which is created and managed in the dashboard, not through the published API surface.

## What the API does not expose

* Raw object keys or storage paths
* Provider names or credentials
* Encryption keys or envelopes
* Other companies' resources
* Bucket creation, update, or deletion


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