KEkeboola
Buckets

Create bucket or link a shared bucket

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

post/v2/storage/branch/{branchId}/buckets

Request

Path parameters

branchIdstring required

Query parameters

asyncboolean

Link the shared bucket in a background job. Applies to linking only; ignored when creating a bucket.

Headers

contextstring nullable

Request body

OR

Example request

{
  "name": "my-bucket",
  "stage": "in",
  "description": "Some Description",
  "backend": "snowflake",
  "displayName": "my-bucket",
  "color": "#FF5733"
}

Response

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

uristring required

API URI of the bucket.

idstring required

Bucket identifier ({stage}.{name}).

namestring required

Bucket name (prefixed with c-).

displayNamestring required

Human-readable display name shown in the UI.

idBranchinteger required

ID of the branch the bucket belongs to.

stage'in' | 'out' | 'sys' required

Bucket stage.

descriptionstring required

Bucket description.

tablesstring required

The same URI as uri, kept for backward compatibility.

createdstring required

Creation timestamp, ISO 8601 with a +hhmm offset; "" when none was recorded.

lastChangeDatestring nullable required

Timestamp of the last data change in the bucket, ISO 8601 with a +hhmm offset.

updatedstring nullable required

Timestamp of the last bucket update, ISO 8601 with a +hhmm offset.

isReadOnlyboolean required

Whether the bucket is read-only (linked or external buckets).

dataSizeBytesinteger required

Total data size in bytes.

rowsCountinteger required

Total number of rows.

isMaintenanceboolean required

Whether the bucket is in maintenance mode.

backendstring 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.

hasExternalSchemaboolean required

Whether the bucket is an external (registered) bucket.

databaseNamestring required

Database of a Snowflake external bucket or of a linked bucket's source; "" otherwise.

pathstring required

Dot-separated path of the bucket on the backend.

isSnowflakeSharedDatabaseboolean required

Whether the external bucket uses a Snowflake Secure Data Share.

isLinkedBucketboolean required

Whether this bucket is linked from another project.

colorstring nullable required

CSS color of the bucket.

bucketSharingAllowedboolean required

Whether the bucket can be shared.

backendPathstring[] required

Full path of the bucket on the backend (e.g. database and schema); [] on backends without one.

attributesobject[] required

Deprecated, always an empty array. Kept for backward compatibility.

Example response

{
  "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-my-new-bucket",
  "id": "in.c-my-new-bucket",
  "name": "c-my-new-bucket",
  "displayName": "my-new-bucket",
  "idBranch": 1234,
  "stage": "in",
  "description": "Some Description",
  "tables": "https://connection.keboola.com/v2/storage/buckets/in.c-my-new-bucket",
  "created": "2017-02-13T12:01:05+0100",
  "updated": "2024-11-28T13:03:13+0100",
  "backend": "snowflake",
  "path": "database_name.c-my-new-bucket",
  "bucketSharingAllowed": true,
  "sharingParameters": {
    "projects": [
      {
        "id": 321,
        "name": "Some Project"
      }
    ],
    "users": [
      {
        "id": 5,
        "name": "Jan Developer",
        "email": "jan.dev@keboola.com"
      }
    ]
  },
  "sharedBy": {
    "id": 5,
    "name": "dev@keboola.com",
    "date": "2020-02-03T14:58:29+0100"
  },
  "owner": {
    "id": 123,
    "name": "Jan Developer",
    "email": "jan.dev@keboola.com"
  },
  "sourceBucket": {
    "id": "in.c-main",
    "name": "c-main",
    "displayName": "main",
    "stage": "in",
    "description": "Organization shared data",
    "sharing": "organization-project",
    "created": "2020-01-12T18:28:31+0100",
    "lastChangeDate": "2020-01-12T18:31:49+0100",
    "dataSizeBytes": 1536,
    "rowsCount": 32,
    "backend": "snowflake",
    "path": "database_name.c-main",
    "project": {
      "id": 123,
      "name": "Project name"
    },
    "tables": [
      {
        "id": "in.c-main.languages",
        "name": "languages",
        "displayName": "languages-display-name",
        "path": "/1234-languages"
      }
    ],
    "sharingParameters": {
      "projects": [
        {
          "id": 321,
          "name": "Some Project"
        }
      ],
      "users": [
        {
          "id": 5,
          "name": "Jan Developer",
          "email": "jan.dev@keboola.com"
        }
      ]
    },
    "sharedBy": {
      "id": 5,
      "name": "dev@keboola.com",
      "date": "2020-02-03T14:58:29+0100"
    },
    "owner": {
      "id": 123,
      "name": "Jan Developer",
      "email": "jan.dev@keboola.com"
    },
    "metadata": [
      {
        "id": "19509",
        "key": "some-key",
        "value": "Some value",
        "provider": "test-component",
        "timestamp": "2017-02-13T23:36:10+0100"
      }
    ]
  },
  "backendPath": [
    "KBC_PRJ_123",
    "in.c-my-new-bucket"
  ],
  "attributes": []
}

Changes

No recorded changes to this operation across all 1 revision of this API.