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

> Discover the buckets a key can reach and read their stored size. Bucket creation and configuration stay in the dashboard.

Every file and folder call is scoped to a bucket. Two read-only bucket operations are published: they let a key discover the buckets it may target and read how much each one stores. Everything that changes a bucket — creation, configuration, deletion — remains a dashboard action.

## Operations

| Operation | Method and path | Required scope |
| - | - | - |
| List accessible buckets | `GET /buckets/all` | `buckets:read` |
| Read bucket size | `GET /buckets/size/{bucketId}` | `buckets:read` |

## List accessible buckets

```http theme={null}
GET /buckets/all
```

```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"
```

An illustrative response:

```json theme={null}
{
  "status": 200,
  "message": "Buckets retrieved",
  "data": [
    {
      "id": "0f0b0c7e-6a1f-4b8e-9a3e-1f2c3d4e5f60",
      "name": "company-default",
      "code": "company-default",
      "retentionPeriod": null,
      "datacenterId": "dc-frankfurt-01",
      "createdAt": "2026-09-01T08:00:00.000Z",
      "updatedAt": "2026-09-01T08:00:00.000Z"
    }
  ]
}
```

Values are illustrative. The list is **not paginated**: it returns every bucket the key can reach in one response.

| Field | Meaning |
| - | - |
| `id` | Bucket identifier used in file and folder paths |
| `name` | Human-readable name |
| `code` | Provisioning code; the default bucket uses the same value for name and code |
| `retentionPeriod` | Active bucket-level retention, or `null` |
| `datacenterId` | Location binding. Opaque: do not parse it to infer a region |
| `createdAt`, `updatedAt` | Timestamps |

Notes:

* A key restricted to specific buckets sees **only those buckets** in the list. Out-of-scope buckets are filtered out silently; there is no separate error.
* `datacenterId` is the only location signal on bucket records. Available locations are chosen at bucket creation in the dashboard, and the platform's datacenter and region routes are session-only — they are not reachable with an API key. See [Data residency](https://docs.everabyte.com/security/data-residency.md).
* The default bucket (`name` equal to `code`) is created automatically at provisioning and cannot be deleted.

## Read bucket size

```http theme={null}
GET /buckets/size/{bucketId}
```

```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"
```

An illustrative response:

```json theme={null}
{
  "status": 200,
  "message": "Bucket size checked",
  "data": {
    "totalSize": "1.2 GB",
    "totalSizeBytes": 1288490188
  }
}
```

| Field | Meaning |
| - | - |
| `totalSize` | Human-readable total size |
| `totalSizeBytes` | Total size in bytes |

Notes:

* The size counts **non-deleted files only**. Files in trash are excluded, so the value can drop when a hard delete purges trash.
* The size reflects stored content in the bucket, not the plan's capacity ceiling. Plan capacity is visible in the dashboard.
* An unknown bucket, or one outside the caller's tenant, returns `404`.
* A restricted key asking for a bucket outside its scope returns `403 API_BUCKET_SCOPE_DENIED`.

## What stays in the dashboard

| Operation | Where |
| - | - |
| Create a bucket | Dashboard (plan limits and location selection apply) |
| Update bucket configuration or retention | Dashboard |
| Delete a bucket | Dashboard (destructive cascade; the default bucket cannot be deleted) |
| Choose the region or datacenter | Dashboard, at bucket creation |

> [!WARNING]
>
> Do not build against bucket routes that are not in this reference. Bucket creation, update, deletion, and provisioning are session-only: an API-key call to them fails, and the routes are not a stable contract.

## Related

> **[Buckets, folders, and files](https://docs.everabyte.com/concepts/buckets-folders-files.md)**
>
> The storage hierarchy and how IDs are used.

> **[Files](https://docs.everabyte.com/api-reference/files/overview.md)**
>
> File operations within a bucket.

> **[Folders](https://docs.everabyte.com/api-reference/folders/overview.md)**
>
> Folder operations within a bucket.

> **[Limits and quotas](https://docs.everabyte.com/concepts/limits-and-quotas.md)**
>
> Trial and plan caps that apply to every operation.


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