---
title: "Update a bucket"
method: PUT
path: "/v2/storage/buckets/{bucketId}"
tags: ["Buckets"]
---

# Update a bucket

`PUT /v2/storage/buckets/{bucketId}`

## Request

- Base URL: `https://connection.keboola.com`
- URL: `https://connection.keboola.com/v2/storage/buckets/{bucketId}`
- Auth: one of:
  - API key in header `X-StorageApi-Token`
  - API key in header `X-KBC-ManageApiToken`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/keboola/apis/keboola-storage-api/docs/v2/storage/buckets/:bucketId/put.ts> (a function with typed inputs; its response is checked against the schema)

Updates the display name and the color of a bucket. With `async=true` the update is enqueued as a job (202). The synchronous variant is deprecated.

Initial response returns job details [JobResponse](#model-JobResponse). The result of the asynchronous job can be fetched via `/v2/storage/jobs/{id}`. When the job completes, final result is [BucketUpdateJobResult](#model-BucketUpdateJobResult).

 Parameters of job will be [BucketUpdateJobParams](#components-schemas-BucketUpdateJobParams).

[Deprecated] This endpoint can be used synchronously as well. In that case, the final result is returned directly in the response [BucketUpdateResponse](#model-BucketUpdateResponse).

## Path parameters

- `bucketId` string, required

## Query parameters

- `async` boolean

## Request body

- UpdateBucketRequest
  - `displayName` string: The name of a bucket or a table. - Allowed characters: `A-Z`, `a-z`, `0-9`, dash `-` and underscore `_`. Anything else — a space, a dot, an accented letter — is rejected, not transliterated. - 1 to 96 characters. - Cannot start with an underscore. A dash or a digit as the first character is fine. - Registered (external) buckets follow this same rule, dashes included. - Uniqueness is case-insensitive within a stage: creating `MyBucket` next to `mybucket` fails with `storage.buckets.alreadyExists`, and for tables with `storage.buckets.tableAlreadyExists` or `storage.validation.tableAlreadyExists`. - To turn arbitrary user input into a name that satisfies this rule, call `POST /v2/storage/webalize/display-name` instead of reimplementing the transformation. It unaccents the input, replaces every run of disallowed characters with a single `-`, trims `-` from both ends, strips leading underscores, and truncates to 96 characters.
  - `color` string, nullable: New CSS color code of the bucket (e.g. `#FF5733`, `red`, `rgb(255, 0, 0)`). Pass null to remove the color.

## Response `200`

The updated bucket (synchronous, deprecated).

- BucketUpdateResponse: Bucket object.
  - `uri` string, required: API URI of the bucket.
  - `id` string, required: Bucket identifier (`{stage}.{name}`).
  - `name` string, required: Bucket name (prefixed with `c-`).
  - `displayName` string, required: Human-readable display name shown in the UI.
  - `idBranch` integer, required: ID of the branch the bucket belongs to.
  - `stage` 'in' | 'out' | 'sys', required: Bucket stage.
  - `description` string, required: Bucket description.
  - `tables` string, required: The same URI as `uri`, kept for backward compatibility.
  - `created` string, required: Creation timestamp, ISO 8601 with a `+hhmm` offset; `""` when none was recorded.
  - `lastChangeDate` string, nullable, required: Timestamp of the last data change in the bucket, ISO 8601 with a `+hhmm` offset.
  - `updated` string, nullable, required: Timestamp of the last bucket update, ISO 8601 with a `+hhmm` offset.
  - `isReadOnly` boolean, required: Whether the bucket is read-only (linked or external buckets).
  - `dataSizeBytes` integer, required: Total data size in bytes.
  - `rowsCount` integer, required: Total number of rows.
  - `isMaintenance` boolean, required: Whether the bucket is in maintenance mode.
  - `backend` string, required: Storage backend of the bucket: `snowflake`, `bigquery` or `postgres` (external buckets); older buckets may carry another backend name.
  - `sharing` 'organization' | 'organization-project' | 'specific-projects' | 'specific-users' | 'null', nullable, required: Sharing type of the bucket; `null` when the bucket is not shared.
  - `hasExternalSchema` boolean, required: Whether the bucket is an external (registered) bucket.
  - `databaseName` string, required: Database of a Snowflake external bucket or of a linked bucket's source; `""` otherwise.
  - `path` string, required: Dot-separated path of the bucket on the backend.
  - `isSnowflakeSharedDatabase` boolean, required: Whether the external bucket uses a Snowflake Secure Data Share.
  - `isLinkedBucket` boolean, required: Whether this bucket is linked from another project.
  - `color` string, nullable, required: CSS color of the bucket.
  - `bucketSharingAllowed` boolean, required: Whether the bucket can be shared.
  - `sharingParameters` union: Who the bucket is shared with. Present only when the bucket is shared; an empty array `[]` when it is shared with the organization or its projects.
    - object
      - `projects` object[]: Present when `sharing` is `specific-projects`.
        - `id` integer, required
        - `name` string, required
      - `users` object[]: Present when `sharing` is `specific-users`.
        - `id` integer, required
        - `name` string, required
        - `email` string, required
    - unknown[]
      - unknown
  - `sharedBy` object: Token that shared the bucket. Present only when the bucket is shared.
    - `id` integer, nullable, required
    - `name` string, nullable, required
    - `date` string, required: ISO 8601 with a `+hhmm` offset; `""` when none was recorded.
  - `sharedByActor` ActorResponse, required: Who performed the action and through which credential.
    - `type` 'token' | 'session' | 'pat' | 'system', required: Credential the action came through: a Storage token, a programmatic session, a personal access token, or system work.
    - `id` string, required: Token id as a string, session or personal access token UUID, or the system subject.
    - `name` string, required: Token description, the admin email for a session or personal access token, or the system label, as it was when the action happened.
    - `adminId` integer, nullable, required: Admin behind the credential; null for a token without an admin, for system work, and when the admin was not recorded (an object whose creator is known only from its token columns, including rows backfilled from them).
  - `owner` object, nullable, required: Bucket owner; `null` when no owner is set.
    - `id` integer, required
    - `name` string, required
    - `email` string, required
  - `sourceBucket` SharedBucketResponse: Shared bucket as seen from another project (also used as `sourceBucket` of a linked bucket).
    - `id` string, required: Bucket identifier in the source project.
    - `name` string, required: Bucket name.
    - `displayName` string, required: Bucket display name.
    - `stage` 'in' | 'out' | 'sys', required: Bucket stage.
    - `description` string, required: Bucket description.
    - `sharing` 'organization' | 'organization-project' | 'specific-projects' | 'specific-users' | 'null', nullable, required: Sharing type.
    - `created` string, required: Creation timestamp, ISO 8601 with a `+hhmm` offset; `""` when none was recorded.
    - `lastChangeDate` string, nullable, required: Timestamp of the last data change, ISO 8601 with a `+hhmm` offset.
    - `dataSizeBytes` integer, required
    - `rowsCount` integer, required
    - `backend` string, required: Storage backend of the bucket: `snowflake`, `bigquery` or `postgres` (external buckets); older buckets may carry another backend name.
    - `hasExternalSchema` boolean, required: Whether the bucket is an external (registered) bucket.
    - `databaseName` string, required: Database of a Snowflake external bucket or of a linked bucket's source; `""` otherwise.
    - `path` string, required: Dot-separated path of the bucket on the backend.
    - `project` object, required: Project owning the bucket.
      - `id` integer, required
      - `name` string, required
    - `color` string, nullable, required
    - `tables` object[]: Tables in the shared bucket (filtered aliases are omitted). Absent from a `sourceBucket` inside a table list or search with `include=bucketsWithoutSourceTables`.
      - `id` string, required
      - `name` string, required
      - `displayName` string, required
      - `path` string, required: Internal Storage path of the table (`/{bucket numeric id}-{table name}`); may be `""`.
    - `sharingParameters` union: Who the bucket is shared with. Present only when the bucket is shared; an empty array `[]` when it is shared with the organization or its projects.
      - object
        - `projects` object[]: Present when `sharing` is `specific-projects`.
          - `id` integer, required
          - `name` string, required
        - `users` object[]: Present when `sharing` is `specific-users`.
          - `id` integer, required
          - `name` string, required
          - `email` string, required
      - unknown[]
        - unknown
    - `sharedBy` object: Token that shared the bucket. Present only when the bucket is shared.
      - `id` integer, nullable, required
      - `name` string, nullable, required
      - `date` string, required: ISO 8601 with a `+hhmm` offset; `""` when none was recorded.
    - `sharedByActor` ActorResponse, required: Who performed the action and through which credential.
      - `type` 'token' | 'session' | 'pat' | 'system', required: Credential the action came through: a Storage token, a programmatic session, a personal access token, or system work.
      - `id` string, required: Token id as a string, session or personal access token UUID, or the system subject.
      - `name` string, required: Token description, the admin email for a session or personal access token, or the system label, as it was when the action happened.
      - `adminId` integer, nullable, required: Admin behind the credential; null for a token without an admin, for system work, and when the admin was not recorded (an object whose creator is known only from its token columns, including rows backfilled from them).
    - `owner` object, nullable, required: Bucket owner; `null` when no owner is set.
      - `id` integer, required
      - `name` string, required
      - `email` string, required
    - `metadata` MetadataItemResponse[]: Bucket metadata. Present only on the shared-buckets list with `include` containing `metadata`.
      - `id` string, required: Metadata record identifier
      - `key` string, required: Metadata key
      - `value` string, nullable, required: Metadata value
      - `provider` string, required: Id of the component that created the metadata
      - `timestamp` string, required: When the metadata was created or last updated, ISO 8601 with a `+hhmm` offset
  - `backendPath` string[], required: Full path of the bucket on the backend (e.g. database and schema); `[]` on backends without one.

## Other responses

- `202`: Job accepted; returns job details.
- `400`: The payload is invalid or the display name is already used in the project.
- `403`: Access to the bucket was denied.
- `404`: The bucket was not found.
- `503`: The bucket or its backend is under maintenance.

---

[API](https://skmtc.dev/keboola/apis/keboola-storage-api.md) - [All operations](https://skmtc.dev/keboola/apis/keboola-storage-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keboola/apis/keboola-storage-api/revisions/34b5ceac0317?raw)