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

> What a bucket is, how retention and scoping work, and why bucket management stays in the dashboard.

A bucket is the storage container that holds folders and files. Every company gets a default bucket at provisioning time.

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

```bash theme={null}
curl "https://api.everabyte.io/api/buckets/all" \
  -H "X-Public-Key: $EVB_PUBLIC_KEY" \
  -H "X-Secret-Key: $EVB_SECRET_KEY"
```

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.

```bash theme={null}
export EVB_BUCKET_ID="00000000-0000-0000-0000-000000000000"
```

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

```bash theme={null}
curl "https://api.everabyte.io/api/buckets/size/$EVB_BUCKET_ID" \
  -H "X-Public-Key: $EVB_PUBLIC_KEY" \
  -H "X-Secret-Key: $EVB_SECRET_KEY"
```

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](https://docs.everabyte.com/api-reference/buckets/overview.md) for full field references.

## What requires the dashboard

| Operation | Why it is not part of the API reference |
| - | - |
| Create bucket | Administrative; enforces plan limits and location selection |
| Update bucket | Changes retention and other tenant-wide settings |
| Delete bucket | Destructive cascade; requires human confirmation |
| Ensure provisioning | Internal lifecycle operation |
| List by datacenter | Administrative view |
| Choose the region or datacenter | Selected at bucket creation |

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](https://docs.everabyte.com/concepts/limits-and-quotas.md).


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