# Update Bucket

`PATCH /storage/buckets/{bucketName}` · Core · Storage & Schema

Updates a bucket's settings; only the fields sent change. A system bucket's settings, its mode included, cannot change (409).

`mode` is the bucket's access preset:
- `private` (default): authenticated access by role tier and the IAM `buckets:<verb>` ceiling.
- `public`: private's rules, plus anonymous read of objects at `GET /@{projectSlug}/storage/public/{bucketName}/{path}`, which answers 302 to a short-lived presigned URL and is rate limited per client IP (429 K9O_RATE_LIMITED). Never anonymous list, upload or delete.
- `custom`: the bucket's storage policy, `policy.buckets.<bucket>` declared in a migration, decides each object action for every caller, PROJECT_ADMIN included; an action the policy does not grant is denied. Managing the bucket and authoring its policy never go through it, so an admin can always change the policy or switch the mode back.

Setting or changing the mode is its own IAM action, buckets:set_mode (PROJECT_ADMIN by default; a buckets:update widening does not include it), and is audited (`data.write.storage.bucket.mode_changed`). `public` needs `confirmPublic: true`; `custom` needs the bucket to have a storage policy already.

The legacy `public` boolean is an alias of mode (true = public, false = private) under the same rules; responses carry both, with `public` derived from `mode`.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `bucketName` | path | yes | The bucket's name. It is unique within the project. Example: `"product-images"`. |
| `projectSlug` | path | yes | The project's slug: the path segment after `@`. It is unique within the org. Example: `"storefront"`. |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `mode` | enum ("private", "public", "custom") | no | A new mode. Moving to `public` needs `confirmPublic: true`; moving to `custom` needs the bucket to have a storage policy. |
| `confirmPublic` | boolean | no | Must be true to move the bucket to `public`. |
| `public` | boolean | no | Older form of `mode`: true is `public`, false is `private`. It must agree with `mode` when both are sent. |
| `fileSizeLimit` | object | no | The largest object an upload may write, in bytes, or null for no bucket limit. |
| _one of_ | | |  |
| _or_ | | |  |
| `allowedMimeTypes` | object | no | MIME types an upload may have, at most 64. An empty array or null allows any type. |
| _one of_ | | |  |
| _or_ | | |  |
| `versioning` | boolean | no | Keep earlier versions of an object when it is overwritten. |
| `deleteAfterDays` | object | no | Delete objects this many days after they were last uploaded (an overwrite starts the count again). From that point the object reads as not found, and it is removed from the bucket within a few hours. Only objects uploaded through the platform are deleted: an object written straight into a customer storage location, or uploaded before per-object records began, is kept. Nothing is deleted while the project is under a legal hold. On a customer storage location, setting it first tests that the platform can write and delete there. Send null to keep objects until deleted. |
| _one of_ | | |  |
| _or_ | | |  |
| `byosBindingId` | object | no | Link the bucket to a storage location (`byos_...`), or null to move it back to platform-managed storage. This is the only setting a system bucket accepts. |
| _one of_ | | |  |
| _or_ | | |  |

```json
{
  "public": true,
  "fileSizeLimit": null,
  "allowedMimeTypes": null,
  "versioning": true,
  "deleteAfterDays": null
}
```

## Responses

- **200**: Success

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes | A storage bucket and its settings. |
| `data.name` | string | yes | The bucket name, unique in the project. |
| `data.mode` | enum ("private", "public", "custom") | yes | Who can reach the bucket's objects. `private`: project roles and IAM policies only. `public`: as private, plus anyone may read (not list, write or delete) objects without signing in. `custom`: the bucket's storage policy decides; the bucket must already have one. |
| `data.public` | boolean | yes | True when `mode` is `public`. Derived from `mode`. |
| `data.fileSizeLimit` | object | yes | The largest object an upload may write, in bytes; null when the bucket sets no limit. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.allowedMimeTypes` | array of string | yes | MIME types an upload may have. Empty means any type. |
| `data.versioning` | boolean | yes | Whether earlier versions of an overwritten object are kept. |
| `data.deleteAfterDays` | object | yes | Objects are deleted this many days after they were last uploaded: from that point they read as not found, and they are removed from the bucket within a few hours. Null keeps them until deleted. Only objects uploaded through the platform are deleted: one written straight into a customer storage location, or uploaded before per-object records began, is kept. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.createdAt` | string (date-time) | yes | When the bucket was created. |
| `data.updatedAt` | string (date-time) | yes | When the bucket's settings last changed. |
| `data.system` | boolean | yes | True for a bucket the platform creates and writes (`k9o-audit-anchors`, `k9o-extension-assets`). A system bucket can't be deleted, its objects can't be written or deleted through the API, and only its storage location can change. |
| `data.byosBindingId` | object | yes | The storage location (`byos_...`) the bucket's objects are kept in; null for platform-managed storage. |
| _one of_ | | |  |
| _or_ | | |  |
| `meta` | object | yes | Request metadata: cost, timing and correlation ids. |


## Errors

| HTTP | Code | When |
|---|---|---|
| 403 | `K9O_ACCESS_DENIED` | The caller does not have permission to update this storage bucket. |
| 404 | `K9O_BUCKET_NOT_FOUND` | No bucket with the specified name exists in this project. |
| 400 | `K9O_INVALID_FIELD_VALUE` | An invalid field: for mode, confirmPublic is missing for public (reason confirm_public_required), the bucket has no storage policy for custom (custom_mode_requires_policy), or mode and the legacy public flag disagree (mode_public_conflict). |
| 403 | `K9O_IAM_POLICY_DENIED` | The bound IAM policy ceiling denies buckets:set_mode: setting or changing a bucket's mode is its own action, PROJECT_ADMIN-only by default; a policy that widens buckets:update does not widen it. |
| 409 | `K9O_STATE_CONFLICT` | Only a system bucket's storage location can change; its mode and other settings are the platform's. Also answered when turning on deleteAfterDays for a bucket on a customer storage location fails the write or delete test there (reason location_write_check_failed or location_delete_check_failed); nothing is changed. |

## Code samples

### cURL

```bash
curl -X PATCH 'https://<org>.api-<region>.k9o.io/@storefront/storage/buckets/product-images' \
  -H 'Authorization: Bearer $K9O_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "public": true,
  "fileSizeLimit": null,
  "allowedMimeTypes": null,
  "versioning": true,
  "deleteAfterDays": null
}'
```

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/storage/buckets/product-images', {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.K9O_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "public": true,
  "fileSizeLimit": null,
  "allowedMimeTypes": null,
  "versioning": true,
  "deleteAfterDays": null
}),
});
const { data, meta } = await res.json();
```

### k9o CLI

```bash
k9o storage buckets update <name>
```

### @k9o/core

```typescript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.storage.updateBucket('product-images', {
  public: true,
  fileSizeLimit: null,
  allowedMimeTypes: null,
  versioning: true,
  deleteAfterDays: null
})
```

### k9o

```python
# k9o = create_client(org_slug="playground", project_slug="storefront", api_key="k9o_…")
response = k9o.storage.update_bucket("product-images", {
    "public": True,
    "fileSizeLimit": None,
    "allowedMimeTypes": None,
    "versioning": True,
    "deleteAfterDays": None
})
```

### sdk-go

```go
// ctx := context.Background()
// client, _ := k9o.NewClient(k9o.ClientOpts{OrgSlug: "playground", ProjectSlug: "storefront", APIKey: "k9o_…"})
data, _, kerr := client.Storage.UpdateBucket(ctx, "product-images", map[string]any{"public": true, "fileSizeLimit": nil, "allowedMimeTypes": nil, "versioning": true, "deleteAfterDays": nil})
```

### k9o

```rust
// let k9o = Client::new(ClientOpts { org_slug: "playground".into(), project_slug: "storefront".into(), api_key: "k9o_…".into() })?;
let resp = k9o.storage.update_bucket("product-images", json!({"public": true, "fileSizeLimit": null, "allowedMimeTypes": null, "versioning": true, "deleteAfterDays": null})).await?
```

### dev.k9o:core

```java
// K9o k9o = K9o.createClient(K9o.Opts.builder().orgSlug("playground").projectSlug("storefront").apiKey("k9o_…").build());
var response = k9o.storage().updateBucket("product-images", Map.of("public", true, "fileSizeLimit", null, "allowedMimeTypes", null, "versioning", true, "deleteAfterDays", null))
```

### K9o.Core

```c#
// var k9o = K9oClient.Create(new K9oOptions { OrgSlug = "playground", ProjectSlug = "storefront", ApiKey = "k9o_…" });
var response = await k9o.Storage.UpdateBucketAsync("product-images", new Dictionary<string, object> { ["public"] = true, ["fileSizeLimit"] = null, ["allowedMimeTypes"] = null, ["versioning"] = true, ["deleteAfterDays"] = null })
```

### k9o

```ruby
# k9o = K9o.create_client(org_slug: "playground", project_slug: "storefront", api_key: "k9o_…")
response = k9o.storage.update_bucket("product-images", { public: true, fileSizeLimit: nil, allowedMimeTypes: nil, versioning: true, deleteAfterDays: nil })
```

### k9o/sdk

```php
// $k9o = K9oClient::create(['org_slug' => 'playground', 'project_slug' => 'storefront', 'api_key' => 'k9o_…']);
$response = $k9o->storage->update_bucket('product-images', ['public' => true, 'fileSizeLimit' => null, 'allowedMimeTypes' => null, 'versioning' => true, 'deleteAfterDays' => null])
```

### K9o

```swift
// let k9o = try K9o.createClient(orgSlug: "playground", projectSlug: "storefront", apiKey: "k9o_…")
let result = try await k9o.storage.updateBucket("product-images", {
  public: true,
  fileSizeLimit: null,
  allowedMimeTypes: null,
  versioning: true,
  deleteAfterDays: null
})
```

### core-kotlin

```kotlin
// val k9o = createClient { orgSlug = "playground"; projectSlug = "storefront"; apiKey = "k9o_…" }
val result = k9o.storage.updateBucket("product-images", {
  public: true,
  fileSizeLimit: null,
  allowedMimeTypes: null,
  versioning: true,
  deleteAfterDays: null
})
```

### k9o (Flutter)

```dart
// final k9o = K9o.createClient(orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…');
final result = await k9o.storage.updateBucket('product-images', {
  public: true,
  fileSizeLimit: null,
  allowedMimeTypes: null,
  versioning: true,
  deleteAfterDays: null
})
```

### @k9o/react-native

```javascript
// const k9o = createClient({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })  // RN, secure storage
const { data } = await k9o.storage.updateBucket('product-images', {
  public: true,
  fileSizeLimit: null,
  allowedMimeTypes: null,
  versioning: true,
  deleteAfterDays: null
})
```


Canonical page: https://docs.kilimanjaro.dev/api-playground/core/update-bucket
