Skip to main content
A bucket is the storage container that holds folders and files. Every company gets a default bucket at provisioning time.
This reference documents two read-only bucket operations: listing the buckets a key can reach (GET /buckets/all) and reading a bucket’s stored size (GET /buckets/size/{bucketId}). Bucket creation, configuration, and deletion are dashboard operations, not part of the published API contract.

​
Getting a bucket ID

You need a bucketId for every file and folder path. List the buckets your key can reach, or copy the identifier from the dashboard once and treat it as configuration.
Each item in data includes the bucket id, name, code, retentionPeriod, and the opaque datacenterId location binding. A key restricted to specific buckets lists only those buckets.
Do not hard-code a bucket ID across environments: the ID identifies one bucket in one company, and a key outside its scope receives 403 API_BUCKET_SCOPE_DENIED.

​
Reading bucket size

The response reports totalSizeBytes — the sum of non-deleted file sizes in the bucket — and a human-readable totalSize. Files in trash are excluded. Use it for usage tracking in your own accounting; it does not report the plan’s capacity ceiling, which the dashboard shows. An unknown bucket returns 404; a bucket outside a restricted key’s scope returns 403 API_BUCKET_SCOPE_DENIED. See the bucket operations for full field references.

​
What requires the dashboard

If your product needs automated bucket provisioning, discuss an enterprise or partner arrangement.

​
Default bucket

The bucket created automatically at provisioning time has name === code. It is the tenant’s root container and cannot be deleted. Deleting it would leave the company without a storage root.

​
Bucket retention

A bucket can have a retention policy. When active:
  • files in the bucket cannot be soft- or hard-deleted,
  • per-file retention changes are rejected,
  • bucket deletion is blocked.
Bucket retention allows 90d, 120d, 180d, 1Y, 2Y, 3Y, and 5Y. It excludes the shorter 30d and 45d file-level values. Retention is configured in the dashboard; the API cannot change it.

​
Bucket scope and API keys

Bucket restriction is the strongest containment available to a key. Use it when an integration only needs one tenant area:
  • a key for one customer workspace,
  • a key for an ingestion bucket,
  • a key for a report archive.
A restricted key:
  • can only target the buckets it is scoped to,
  • cannot read, write, move, or copy into other buckets,
  • receives 403 API_BUCKET_SCOPE_DENIED on out-of-scope attempts.
Cross-bucket file copies and moves require both buckets to be within the same company and within the key’s allowed set.

​
Capacity planning

Track growth with GET /buckets/size/{bucketId} — the stored-size endpoint — combined with your own accounting. Uploads enforce the company’s remaining capacity; they do not silently truncate. A copy consumes additional capacity equal to the copied bytes. For plan limits, see Limits and quotas.