Core concepts

The API is small once you understand five objects and how they relate.

​

Company

A company is the tenant boundary for the developer API. An API key belongs to a company and acts within that company’s data only. Cross-company access is not a supported pattern.

​

Bucket

A bucket is a storage container bound to a datacenter location. Each company gets a default bucket at provisioning time. Buckets have their own names, codes, and optional retention policies. The published API can list the buckets a key can reach and read a bucket’s stored size. Bucket creation, configuration, and deletion are dashboard-only: copy the bucketId from the list or the dashboard and use it in every file and folder path. See Buckets.

​

Folder

Folders organize files inside a bucket. They form a tree with a maximum depth of 8 levels. A folder can contain both files and subfolders. Folders are logical containers: a file belongs to a bucket and may also be linked to a folder. Moving a file changes its folder association without re-encrypting or re-uploading content.

​

File

A file has:

• a stable id,
• a display name and an extFile extension,
• a byte size (sizeByte),
• a visibility of private or public,
• a bucket and optional folder location,
• a current version and a history of previous versions,
• optional retention state,
• optional shared users and shared links (managed in the dashboard).

The API never exposes raw storage paths, provider credentials, or encryption key material.

​

Version

Every upload can create a new version of an existing file. Versions preserve prior content and can be listed, downloaded, restored, or permanently deleted, subject to plan version limits. A file’s current version is the live object. Older versions are separate rows. Version operations return a nested payload; see Versions and restore.

​

Retention

Retention makes content immutable until a date. It exists at file level and bucket level. An active retention policy blocks deletion and, at bucket level, can block per-file retention changes. Legal hold is a separate, company-level preservation control. It can also block deletion. Legal hold is managed in the dashboard, not the public API.

​

Trash

Soft-deleting a file or folder marks it deleted and starts the trash display window. During that window the item can be restored. After the window, it disappears from user views and is eventually purged by the platform. Hard deletion is immediate and permanent. Both modes can be blocked by retention or legal hold.

​

Identity and scope

API keys carry scopes and an optional bucket restriction:

• Scopes decide which operations are possible (files:write, folders:read, and so on).
• Bucket restriction decides which buckets those operations may target.

The effective permission is the intersection. A key with broad file scopes but a single-bucket restriction cannot touch other buckets. Continue with: