Keboola Buckets API
The Buckets API from Keboola — 28 operation(s) for buckets.
OpenAPI Specification
openapi: 3.0.0
info:
title: AI Service Actions Buckets API
version: 1.0.0
contact:
email: devel@keboola.com
license:
name: MIT
url: https://opensource.org/licenses/MIT
tags:
- name: Buckets
paths:
/v2/storage/branch/{branchId}/buckets/register-guide:
get:
tags:
- Buckets
summary: Get bucket registration guide
description: Returns markdown instructions for registering an external bucket.
operationId: get_/v2/storage/branch/{branchId}/buckets/register-guide::BucketRegisterGuideAction
parameters:
- name: branchId
in: path
required: true
schema:
type: string
- name: path[]
in: query
description: Path to the bucket.
required: true
schema:
description: Path to the bucket.
type: array
items:
type: string
minLength: 1
- name: backend
in: query
description: Desired backend of the bucket.
required: true
schema:
description: Desired backend of the bucket.
type: string
enum:
- snowflake
- bigquery
- name: isSnowflakeSharedDatabase
in: query
description: Flag indicating the bucket uses a shared Snowflake database.
required: false
schema:
description: Flag indicating the bucket uses a shared Snowflake database.
type: boolean
nullable: true
responses:
'200':
description: Markdown guide for registering the bucket.
content:
application/json:
schema:
$ref: '#/components/schemas/BucketRegisterGuideResponse'
'400':
description: Returned when the request is invalid or backend is not supported.
'403':
description: Returned when permissions are insufficient.
'501':
description: Returned when the endpoint is called in a non-default branch.
/v2/storage/buckets/register-guide:
get:
tags:
- Buckets
summary: Get bucket registration guide
description: Returns markdown instructions for registering an external bucket.
operationId: get_/v2/storage/buckets/register-guide::BucketRegisterGuideAction
parameters:
- name: path[]
in: query
description: Path to the bucket.
required: true
schema:
description: Path to the bucket.
type: array
items:
type: string
minLength: 1
- name: backend
in: query
description: Desired backend of the bucket.
required: true
schema:
description: Desired backend of the bucket.
type: string
enum:
- snowflake
- bigquery
- name: isSnowflakeSharedDatabase
in: query
description: Flag indicating the bucket uses a shared Snowflake database.
required: false
schema:
description: Flag indicating the bucket uses a shared Snowflake database.
type: boolean
nullable: true
responses:
'200':
description: Markdown guide for registering the bucket.
content:
application/json:
schema:
$ref: '#/components/schemas/BucketRegisterGuideResponse'
'400':
description: Returned when the request is invalid or backend is not supported.
'403':
description: Returned when permissions are insufficient.
'501':
description: Returned when the endpoint is called in a non-default branch.
/v2/storage/branch/{branchId}/buckets:
get:
tags:
- Buckets
summary: List buckets
description: List all buckets in the project.
operationId: get_/v2/storage/branch/{branchId}/buckets::BucketsListAction
parameters:
- name: include
in: query
description: 'Comma-separated list of data to include. Allowed values: attributes, metadata, linkedBuckets.'
required: false
schema:
type: string
- name: branchId
in: path
required: true
schema:
type: string
responses:
'200':
description: List of buckets
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BucketCreateResponse'
/v2/storage/buckets:
get:
tags:
- Buckets
summary: List buckets
description: List all buckets in the project.
operationId: get_/v2/storage/buckets::BucketsListAction
parameters:
- name: include
in: query
description: 'Comma-separated list of data to include. Allowed values: attributes, metadata, linkedBuckets.'
required: false
schema:
type: string
responses:
'200':
description: List of buckets
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BucketCreateResponse'
/v2/storage/branch/{branchId}/buckets/{bucketId}/metadata:
post:
tags:
- Buckets
summary: Create or update bucket metadata
description: Creates new metadata records or updates existing ones for the specified bucket.
operationId: post_/v2/storage/branch/{branchId}/buckets/{bucketId}/metadata::BucketCreateOrUpdateMetadataAction
parameters:
- name: branchId
in: path
required: true
schema:
type: string
- name: bucketId
in: path
required: true
schema:
type: string
pattern: '[^/]+'
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CreateMetadataWithProviderRequest'
responses:
'201':
description: Metadata successfully created or updated.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/MetadataItemResponse'
'404':
description: Returned when the bucket is not found in the project.
/v2/storage/buckets/{bucketId}/metadata:
post:
tags:
- Buckets
summary: Create or update bucket metadata
description: Creates new metadata records or updates existing ones for the specified bucket.
operationId: post_/v2/storage/buckets/{bucketId}/metadata::BucketCreateOrUpdateMetadataAction
parameters:
- name: bucketId
in: path
required: true
schema:
type: string
pattern: '[^/]+'
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CreateMetadataWithProviderRequest'
responses:
'201':
description: Metadata successfully created or updated.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/MetadataItemResponse'
'404':
description: Returned when the bucket is not found in the project.
/v2/storage/branch/{branchId}/buckets/{bucketId}/metadata/{metadataId}:
delete:
tags:
- Buckets
summary: Delete bucket metadata
description: Deletes a metadata record for the specified storage bucket.
operationId: delete_/v2/storage/branch/{branchId}/buckets/{bucketId}/metadata/{metadataId}::BucketDeleteMetadataAction
parameters:
- name: bucketId
in: path
description: Identifier of the bucket.
required: true
schema:
type: string
pattern: '[^/]+'
- name: metadataId
in: path
description: Identifier of the metadata record.
required: true
schema:
type: integer
pattern: '[0-9]+'
- name: branchId
in: path
required: true
schema:
type: string
responses:
'204':
description: Metadata record deleted.
'404':
description: Returned when the bucket or metadata record is not found.
'403':
description: Returned when permissions are insufficient.
/v2/storage/buckets/{bucketId}/metadata/{metadataId}:
delete:
tags:
- Buckets
summary: Delete bucket metadata
description: Deletes a metadata record for the specified storage bucket.
operationId: delete_/v2/storage/buckets/{bucketId}/metadata/{metadataId}::BucketDeleteMetadataAction
parameters:
- name: bucketId
in: path
description: Identifier of the bucket.
required: true
schema:
type: string
pattern: '[^/]+'
- name: metadataId
in: path
description: Identifier of the metadata record.
required: true
schema:
type: integer
pattern: '[0-9]+'
responses:
'204':
description: Metadata record deleted.
'404':
description: Returned when the bucket or metadata record is not found.
'403':
description: Returned when permissions are insufficient.
/v2/storage/branch/{branchId}/buckets/{bucketId}:
get:
tags:
- Buckets
summary: Get bucket detail
description: Retrieve detailed information about a bucket including tables and metadata.
operationId: get_/v2/storage/branch/{branchId}/buckets/{bucketId}::BucketDetailAction
parameters:
- name: bucketId
in: path
description: Identifier of the bucket.
required: true
schema:
type: string
pattern: '[^/]+'
- name: include
in: query
description: 'Comma-separated list of data to include. Allowed values: columns, metadata, columnMetadata.'
required: false
schema:
type: string
- name: branchId
in: path
required: true
schema:
type: string
responses:
'200':
description: Bucket detail response
content:
application/json:
schema:
$ref: '#/components/schemas/BucketDetailResponse'
'404':
description: Returned when the bucket is not found.
'403':
description: Access denied to the bucket.
/v2/storage/buckets/{bucketId}:
get:
tags:
- Buckets
summary: Get bucket detail
description: Retrieve detailed information about a bucket including tables and metadata.
operationId: get_/v2/storage/buckets/{bucketId}::BucketDetailAction
parameters:
- name: bucketId
in: path
description: Identifier of the bucket.
required: true
schema:
type: string
pattern: '[^/]+'
- name: include
in: query
description: 'Comma-separated list of data to include. Allowed values: columns, metadata, columnMetadata.'
required: false
schema:
type: string
responses:
'200':
description: Bucket detail response
content:
application/json:
schema:
$ref: '#/components/schemas/BucketDetailResponse'
'404':
description: Returned when the bucket is not found.
'403':
description: Access denied to the bucket.
/v2/storage/branch/{branchId}/buckets/{bucketId}/tables:
get:
tags:
- Buckets
summary: List tables in a bucket
description: Returns a list of tables in the specified bucket.
operationId: get_/v2/storage/branch/{branchId}/buckets/{bucketId}/tables::BucketGetTablesAction
parameters:
- name: bucketId
in: path
description: Identifier of the bucket.
required: true
schema:
type: string
pattern: '[^/]+'
- name: include
in: query
description: 'Comma-separated list of data to include. Allowed values: attributes, buckets, bucketsWithoutSourceTables, columns, metadata, columnMetadata, sourceMetadata, sourceColumnMetadata.'
required: false
schema:
type: string
- name: branchId
in: path
required: true
schema:
type: string
responses:
'200':
description: List of tables in the bucket.
content:
application/json:
schema:
type: array
items:
type: object
'404':
description: Bucket not found.
'400':
description: Invalid value in the include parameter.
'403':
description: Access denied to the bucket.
'503':
description: Bucket or its backend connection is under maintenance.
/v2/storage/buckets/{bucketId}/tables:
get:
tags:
- Buckets
summary: List tables in a bucket
description: Returns a list of tables in the specified bucket.
operationId: get_/v2/storage/buckets/{bucketId}/tables::BucketGetTablesAction
parameters:
- name: bucketId
in: path
description: Identifier of the bucket.
required: true
schema:
type: string
pattern: '[^/]+'
- name: include
in: query
description: 'Comma-separated list of data to include. Allowed values: attributes, buckets, bucketsWithoutSourceTables, columns, metadata, columnMetadata, sourceMetadata, sourceColumnMetadata.'
required: false
schema:
type: string
responses:
'200':
description: List of tables in the bucket.
content:
application/json:
schema:
type: array
items:
type: object
'404':
description: Bucket not found.
'400':
description: Invalid value in the include parameter.
'403':
description: Access denied to the bucket.
'503':
description: Bucket or its backend connection is under maintenance.
/v2/storage/branch/{branchId}/buckets/{bucketId}/owner:
get:
tags:
- Buckets
summary: Get bucket owner information
description: Retrieve owner details of a bucket.
operationId: get_/v2/storage/branch/{branchId}/buckets/{bucketId}/owner::BucketOwnerDetailAction
parameters:
- name: bucketId
in: path
description: Identifier of the bucket.
required: true
schema:
type: string
pattern: '[^/]+'
- name: branchId
in: path
required: true
schema:
type: string
responses:
'200':
description: Bucket owner detail response
content:
application/json:
schema:
$ref: '#/components/schemas/BucketOwnerDetailResponse'
'404':
description: Returned when the bucket or its owner is not found.
post:
tags:
- Buckets
summary: Update bucket owner
description: Set a new owner for a bucket using user ID or email.
operationId: post_/v2/storage/branch/{branchId}/buckets/{bucketId}/owner::BucketOwnerUpdateAction
parameters:
- name: bucketId
in: path
description: Identifier of the bucket.
required: true
schema:
type: string
pattern: '[^/]+'
- name: branchId
in: path
required: true
schema:
type: string
responses:
'204':
description: Bucket owner updated successfully.
'404':
description: Returned when the bucket or specified owner is not found.
/v2/storage/buckets/{bucketId}/owner:
get:
tags:
- Buckets
summary: Get bucket owner information
description: Retrieve owner details of a bucket.
operationId: get_/v2/storage/buckets/{bucketId}/owner::BucketOwnerDetailAction
parameters:
- name: bucketId
in: path
description: Identifier of the bucket.
required: true
schema:
type: string
pattern: '[^/]+'
responses:
'200':
description: Bucket owner detail response
content:
application/json:
schema:
$ref: '#/components/schemas/BucketOwnerDetailResponse'
'404':
description: Returned when the bucket or its owner is not found.
post:
tags:
- Buckets
summary: Update bucket owner
description: Set a new owner for a bucket using user ID or email.
operationId: post_/v2/storage/buckets/{bucketId}/owner::BucketOwnerUpdateAction
parameters:
- name: bucketId
in: path
description: Identifier of the bucket.
required: true
schema:
type: string
pattern: '[^/]+'
responses:
'204':
description: Bucket owner updated successfully.
'404':
description: Returned when the bucket or specified owner is not found.
/v2/storage/branch/{branchId}/buckets/{id}/tables-async:
post:
tags:
- Buckets
summary: Create a table asynchronously in a bucket
description: Creates a new table in the specified bucket using an asynchronous job. The request supports multiple source types (file, snapshot, time travel, workspace).
operationId: post_/v2/storage/branch/{branchId}/buckets/{id}/tables-async::CreateTableAsyncAction
parameters:
- name: branchId
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
pattern: .+
- name: X-KBC-Backend
in: header
schema:
schema: BackendConfigurationRequest
properties:
context:
type: string
nullable: true
minLength: 1
type: object
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CreateTableAsyncFromFileRequest'
- $ref: '#/components/schemas/CreateTableAsyncFromSnapshotRequest'
- $ref: '#/components/schemas/CreateTableAsyncFromTimeTravelRequest'
- $ref: '#/components/schemas/CreateTableAsyncFromWorkspaceRequest'
responses:
'200':
description: Table creation job accepted. Returns job information.
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'
'404':
description: Bucket or source not found, or permissions are invalid.
'400':
description: Bad request. Validation or business logic error.
'403':
description: Access denied to the resource.
/v2/storage/buckets/{id}/tables-async:
post:
tags:
- Buckets
summary: Create a table asynchronously in a bucket
description: Creates a new table in the specified bucket using an asynchronous job. The request supports multiple source types (file, snapshot, time travel, workspace).
operationId: post_/v2/storage/buckets/{id}/tables-async::CreateTableAsyncAction
parameters:
- name: id
in: path
required: true
schema:
type: string
pattern: .+
- name: X-KBC-Backend
in: header
schema:
schema: BackendConfigurationRequest
properties:
context:
type: string
nullable: true
minLength: 1
type: object
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CreateTableAsyncFromFileRequest'
- $ref: '#/components/schemas/CreateTableAsyncFromSnapshotRequest'
- $ref: '#/components/schemas/CreateTableAsyncFromTimeTravelRequest'
- $ref: '#/components/schemas/CreateTableAsyncFromWorkspaceRequest'
responses:
'200':
description: Table creation job accepted. Returns job information.
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'
'404':
description: Bucket or source not found, or permissions are invalid.
'400':
description: Bad request. Validation or business logic error.
'403':
description: Access denied to the resource.
/v2/storage/branch/{branchId}/buckets/{bucketId}/listing:
get:
tags:
- Buckets
summary: Get bucket listing detail
description: Retrieve the listing configured on a bucket. Data is read from the database — no backend API call is performed.
operationId: get_/v2/storage/branch/{branchId}/buckets/{bucketId}/listing::BucketListingDetailAction
parameters:
- name: bucketId
in: path
description: Identifier of the bucket.
required: true
schema:
type: string
pattern: '[^/]+'
- name: branchId
in: path
required: true
schema:
type: string
responses:
'200':
description: Bucket listing detail.
content:
application/json:
schema:
$ref: '#/components/schemas/BucketListingDetailResponse'
'404':
description: Returned when the bucket is not found or has no listing.
'403':
description: Returned when the token does not have manage privilege on the bucket.
post:
tags:
- Buckets
summary: Create bucket listing
description: "Publishes a BigQuery bucket as an Analytics Hub listing and grants the supplied IAM principals subscriber access. Runs as an async job — the endpoint returns 202 with the job detail.\n\nInitial 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 [BucketListingCreateJobResult](#model-BucketListingCreateJobResult).\n\n Parameters of job will be [BucketListingCreateJobParams](#components-schemas-BucketListingCreateJobParams)."
operationId: post_/v2/storage/branch/{branchId}/buckets/{bucketId}/listing::BucketListingCreateAction
parameters:
- name: bucketId
in: path
description: Identifier of the bucket to publish as a listing.
required: true
schema:
type: string
pattern: '[^/]+'
- name: branchId
in: path
required: true
schema:
type: string
responses:
'400':
description: Bucket is ineligible for a listing, backend is not supported, or a listing already exists.
'404':
description: Bucket not found in the project.
'403':
description: The token does not have MANAGE privilege on the bucket, or it is not an admin-attached token whose admin belongs to the bucket's organization (or holds the share role on the project), or the project lacks the bucket-exposure feature flag. Same gate is enforced on PATCH and DELETE for the same route.
'501':
description: Bucket listings are not supported on Snowflake Partner Connect projects.
'202':
description: Job accepted; returns job details.
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'
x-storage-job-result:
application/json:
schema:
$ref: '#/components/schemas/BucketListingCreateJobResult'
x-storage-job-result:
application/json:
schema:
$ref: '#/components/schemas/BucketListingCreateJobResult'
x-storage-job-params:
application/json:
schema:
$ref: '#/components/schemas/BucketListingCreateJobParams'
delete:
tags:
- Buckets
summary: Delete bucket listing
description: "Initiate removal of the listing for the specified storage bucket. The listing is removed from the Analytics Hub exchange and the listing record is deleted. The underlying exchange is retained so that subsequent listings in the same project can reuse it.\n\nInitial 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 [BucketListingDeleteResponse](#model-BucketListingDeleteResponse).\n\n Parameters of job will be [BucketListingDeleteJobParams](#components-schemas-BucketListingDeleteJobParams)."
operationId: delete_/v2/storage/branch/{branchId}/buckets/{bucketId}/listing::BucketListingDeleteAction
parameters:
- name: bucketId
in: path
description: Identifier of the bucket whose listing should be removed.
required: true
schema:
type: string
pattern: '[^/]+'
- name: branchId
in: path
required: true
schema:
type: string
responses:
'403':
description: The token does not have MANAGE privilege on the bucket, or it is not an admin-attached token whose admin belongs to the bucket's organization (or holds the share role on the project), or the project lacks the bucket-exposure feature flag. Same gate is enforced on POST and PATCH for the same route.
'404':
description: Returned when the bucket or its listing is not found.
'202':
description: Job accepted; returns job details.
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'
x-storage-job-result:
application/json:
schema:
$ref: '#/components/schemas/BucketListingDeleteResponse'
x-storage-job-result:
application/json:
schema:
$ref: '#/components/schemas/BucketListingDeleteResponse'
x-storage-job-params:
application/json:
schema:
$ref: '#/components/schemas/BucketListingDeleteJobParams'
patch:
tags:
- Buckets
summary: Update bucket listing
description: "Update metadata and/or subscribers of an existing bucket listing. Only provided fields are updated, but the request body must include at least one of `exposureName`, `exposureDescription`, or `bigquery.subscribers` — an empty JSON object is rejected with 400. The `bigquery.listingId` is immutable and cannot be changed.\n\nInitial 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 [BucketListingUpdateJobResponse](#model-BucketListingUpdateJobResponse).\n\n Parameters of job will be [BucketListingUpdateJobParams](#components-schemas-BucketListingUpdateJobParams)."
operationId: patch_/v2/storage/branch/{branchId}/buckets/{bucketId}/listing::BucketListingUpdateAction
parameters:
- name: bucketId
in: path
description: Identifier of the bucket whose listing should be updated.
required: true
schema:
type: string
pattern: '[^/]+'
- name: branchId
in: path
required: true
schema:
type: string
responses:
'400':
description: Returned when the request body is invalid.
'403':
description: The token does not have MANAGE privilege on the bucket, or it is not an admin-attached token whose admin belongs to the bucket's organization (or holds the share role on the project), or the project lacks the bucket-exposure feature flag. Same gate is enforced on POST and DELETE for the same route.
'404':
description: Returned when the bucket or listing does not exist.
'501':
description: Returned when the operation is not supported for Snowflake partner connect projects.
'202':
description: Job accepted; returns job details.
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'
x-storage-job-result:
application/json:
schema:
$ref: '#/components/schemas/BucketListingUpdateJobResponse'
x-storage-job-result:
application/json:
schema:
$ref: '#/components/schemas/BucketListingUpdateJobResponse'
x-storage-job-params:
application/json:
schema:
$ref: '#/components/schemas/BucketListingUpdateJobParams'
/v2/storage/buckets/{bucketId}/listing:
get:
tags:
- Buckets
summary: Get bucket listing detail
description: Retrieve the listing configured on a bucket. Data is read from the database — no backend API call is performed.
operationId: get_/v2/storage/buckets/{bucketId}/listing::BucketListingDetailAction
parameters:
- name: bucketId
in: path
description: Identifier of the bucket.
required: true
schema:
type: string
pattern: '[^/]+'
responses:
'200':
description: Bucket listing detail.
content:
application/json:
schema:
$ref: '#/components/schemas/BucketListingDetailResponse'
'404':
description: Returned when the bucket is not found or has no listing.
'403':
description: Returned when the token does not have manage privilege on the bucket.
post:
tags:
- Buckets
summary: Create bucket listing
description: "Publishes a BigQuery bucket as an Analytics Hub listing and grants the supplied IAM principals subscriber access. Runs as an async job — the endpoint returns 202 with the job detail.\n\nInitial 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 [BucketListingCreateJobResult](#model-BucketListingCreateJobResult).\n\n Parameters of job will be [BucketListingCreateJobParams](#components-schemas-BucketListingCreateJobParams)."
operationId: post_/v2/storage/buckets/{bucketId}/listing::BucketListingCreateAction
parameters:
- name: bucketId
in: path
description: Identifier of the bucket to publish as a listing.
required: true
schema:
type: string
pattern: '[^/]+'
responses:
'400':
description: Bucket is ineligible for a listing, backend is not supported, or a listing already exists.
'404':
description: Bucket not found in the project.
'403':
description: The token does not have MANAGE privilege on the bucket, or it is not an admin-attached token whose admin belongs to the bucket's organization (or holds the share role on the project), or the project lacks the bucket-exposure feature flag. Same gate is enforced on PATCH and DELETE for the same route.
'501':
description: Bucket listings are not supported on Snowflake Partner Connect projects.
'202':
description: Job accepted; returns job details.
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'
x-storage-job-result:
application/json:
schema:
$ref: '#/components/schemas/BucketListingCreateJobResult'
x-storage-job-result:
application/json:
schema:
$ref: '#/components/schemas/BucketListingCreateJobResult'
x-storage-job-params:
application/json:
schema:
$ref: '#/components/schemas/BucketListingCreateJobParams'
delete:
tags:
- Buckets
summary: Delete bucket listing
description: "Initiate removal of the list
# --- truncated at 32 KB (92 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/keboola/refs/heads/main/openapi/keboola-buckets-api-openapi.yml