Buckets, folders, and files

Hierarchy

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.

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

Getting Started

Core Concepts

Authentication & Security

Storage Guides

Error Handling

Security & Data Protection

Enterprise & Partners

Resources

Hierarchy

Buckets

Folders

Files

Listing root-level content vs folder content

Identifiers

Names and extensions

Visibility

What the API does not expose

​Hierarchy

​Buckets

​Folders

​Files

​Listing root-level content vs folder content

​Identifiers

​Names and extensions

​Visibility

​What the API does not expose

Hierarchy

Buckets

Folders

Files

Listing root-level content vs folder content

Identifiers

Names and extensions

Visibility

What the API does not expose