---
title: "Create bucket or link a shared bucket"
method: POST
path: "/v2/storage/buckets"
tags: ["Buckets"]
---

# Create bucket or link a shared bucket

`POST /v2/storage/buckets`

## Request

- Base URL: `https://connection.keboola.com`
- URL: `https://connection.keboola.com/v2/storage/buckets`
- 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/post.ts> (a function with typed inputs; its response is checked against the schema)

Using this API call, you can either create a new bucket in the project, or you can link an existing bucket from another project.

**Create bucket** - send `CreateBucketRequest`. The bucket is created synchronously and returned with `201`.

**Link shared bucket** - send `LinkBucketRequest` (recognized by `sourceProjectId`) to create a new bucket which contains the contents of a [shared bucket](https://help.keboola.com/storage/buckets/sharing/) in a source project. Linking a bucket from another project is only possible if sharing has been enabled in the source project (see the bucket sharing endpoints). With `async=true` the link is created in a background job and `202` with the job detail is returned; otherwise the linked bucket is returned with `201`.

## Query parameters

- `async` boolean

## Headers

- `X-KBC-Backend` object
  - `context` string, nullable

## Request body

- union
  - CreateBucketRequest: Creates a new bucket in the project.
    - `name` string, required: 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.
    - `stage` 'in' | 'out' | 'sys': Assigns the bucket to one of the stages.
    - `description` string: Bucket description. **Deprecated**.
    - `backend` 'snowflake' | 'bigquery': Bucket backend type; the default value is determined by the project settings.
    - `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: Bucket color. Accepts valid CSS color values (max 20 characters).
  - LinkBucketRequest: Links a shared bucket from another project. Recognized by the presence of `sourceProjectId`.
    - `name` string, required: 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.
    - `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.
    - `sourceProjectId` integer, required: ID of the source project from which the bucket is being shared.
    - `sourceBucketId` string, required: ID of the bucket being shared.
    - `stage` 'in' | 'out' | 'sys': Assigns the bucket to one of the stages.

## Response `201`

Bucket created, or shared bucket linked synchronously (`async=false`).

- BucketCreateResponse: 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.
  - `attributes` object[], required: Deprecated, always an empty array. Kept for backward compatibility.

## Other responses

- `202`: Shared bucket link enqueued as a job (`async=true`). To see the job detail use the Job Detail endpoint.
- `400`: Invalid request (`storage.buckets.validation`), a bucket with the same name or display name already exists (`storage.buckets.alreadyExists`), invalid stage (`storage.buckets.invalidStage`), backend not supported or not assigned to the project (`storage.buckets.backendNotSupported`, `storage.buckets.backendNotSupportedByProject`), the bucket cannot be created (`storage.buckets.cannotCreate`), or the shared bucket is already linked (`storage.buckets.alreadyLinked`).
- `403`: The token cannot manage buckets, access to the shared bucket was denied (`accessDenied`), or the acting admin has no project membership role (`manage.users.membershipRoleMissing`).
- `404`: Source bucket to link was not found (`storage.buckets.notFound`).
- `501`: Operation is not supported for Snowflake Partner Connect projects (`storage.buckets.notSupportedForSPCProject`).
- `503`: The project is disabled (`manage.project.disabled`). The body carries `reason` and, when known and still in the future, `estimatedEndTime` together with a `Retry-After` header.

---

[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)