# Buckets

## List

`GET /workspaces/{workspaceId}/buckets` · `buckets:read`

If the key has `bucketIds`, only those buckets are returned.

```json
{
  "buckets": [
    {
      "id": "...",
      "workspaceId": "...",
      "name": "my-bucket",
      "displayName": "Main Storage",
      "provider": "aws",
      "protocol": "s3",
      "region": "us-east-1",
      "isHosted": false,
      "thumbnails": true,
      "connected": true,
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}
```

## Create (BYO)

`POST /workspaces/{workspaceId}/buckets` · `buckets:write`

Minimal body: `{ "name": "bucket-name", "displayName?", "provider?", ... }` (same fields as the in-app create flow for non-hosted S3).

## Get / patch / delete

- `GET .../buckets/{bucketId}` · `buckets:read`
- `PATCH .../buckets/{bucketId}` · `buckets:write`
- `DELETE .../buckets/{bucketId}` · `buckets:delete`

Bucket allowlist applies to bucket-scoped routes.