Keboola Tables API
The Tables API from Keboola — 13 operation(s) for tables.
OpenAPI Specification
openapi: 3.0.0
info:
title: AI Service Actions Tables API
version: 1.0.0
contact:
email: devel@keboola.com
license:
name: MIT
url: https://opensource.org/licenses/MIT
tags:
- name: Tables
paths:
/v2/storage/branch/{branchId}/tables/{id}/columns:
post:
tags:
- Tables
summary: Create columns in a table
description: Adds one or more columns to the specified table.
operationId: post_/v2/storage/branch/{branchId}/tables/{id}/columns::ColumnCreateAction
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:
description: Request payload for creating columns
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BigqueryAddColumnToTableRequest'
- $ref: '#/components/schemas/SnowflakeAddColumnToTableRequest'
- $ref: '#/components/schemas/ColumnCreateRequest'
responses:
'202':
description: Accepted.
'400':
description: Invalid request
/v2/storage/tables/{id}/columns:
post:
tags:
- Tables
summary: Create columns in a table
description: Adds one or more columns to the specified table.
operationId: post_/v2/storage/tables/{id}/columns::ColumnCreateAction
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:
description: Request payload for creating columns
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BigqueryAddColumnToTableRequest'
- $ref: '#/components/schemas/SnowflakeAddColumnToTableRequest'
- $ref: '#/components/schemas/ColumnCreateRequest'
responses:
'202':
description: Accepted.
'400':
description: Invalid request
/v2/storage/branch/{branchId}/tables/{id}/snapshots:
get:
tags:
- Tables
summary: List table snapshots
description: List all snapshots created for a table.
operationId: get_/v2/storage/branch/{branchId}/tables/{id}/snapshots::TableSnapshotsListAction
parameters:
- name: id
in: path
description: Identifier of the table.
required: true
schema:
type: string
pattern: .+
- name: limit
in: query
description: Number of snapshots to return. Omit to return all snapshots.
required: false
schema:
type: integer
- name: offset
in: query
description: Pagination offset.
required: false
schema:
type: integer
- name: branchId
in: path
required: true
schema:
type: string
responses:
'200':
description: List of table snapshots.
content:
application/json:
schema:
type: array
items:
type: object
'404':
description: Table not found.
'403':
description: Access denied.
'503':
description: Bucket or backend is under maintenance.
post:
tags:
- Tables
summary: Create table snapshot
description: 'Create a snapshot of a table. Returns a storage job.
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 [TableSnapshotCreateJobResult](#model-TableSnapshotCreateJobResult).'
operationId: post_/v2/storage/branch/{branchId}/tables/{id}/snapshots::TableSnapshotCreateAction
parameters:
- name: id
in: path
description: Identifier of the table.
required: true
schema:
type: string
pattern: .+
- name: branchId
in: path
required: true
schema:
type: string
- name: X-KBC-Backend
in: header
schema:
schema: BackendConfigurationRequest
properties:
context:
type: string
nullable: true
minLength: 1
type: object
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSnapshotRequest'
responses:
'404':
description: Table not found.
'400':
description: Snapshot not supported for this backend or external bucket.
'403':
description: Access denied.
'503':
description: Bucket or backend is under maintenance.
'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/TableSnapshotCreateJobResult'
x-storage-job-result:
application/json:
schema:
$ref: '#/components/schemas/TableSnapshotCreateJobResult'
/v2/storage/tables/{id}/snapshots:
get:
tags:
- Tables
summary: List table snapshots
description: List all snapshots created for a table.
operationId: get_/v2/storage/tables/{id}/snapshots::TableSnapshotsListAction
parameters:
- name: id
in: path
description: Identifier of the table.
required: true
schema:
type: string
pattern: .+
- name: limit
in: query
description: Number of snapshots to return. Omit to return all snapshots.
required: false
schema:
type: integer
- name: offset
in: query
description: Pagination offset.
required: false
schema:
type: integer
responses:
'200':
description: List of table snapshots.
content:
application/json:
schema:
type: array
items:
type: object
'404':
description: Table not found.
'403':
description: Access denied.
'503':
description: Bucket or backend is under maintenance.
post:
tags:
- Tables
summary: Create table snapshot
description: 'Create a snapshot of a table. Returns a storage job.
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 [TableSnapshotCreateJobResult](#model-TableSnapshotCreateJobResult).'
operationId: post_/v2/storage/tables/{id}/snapshots::TableSnapshotCreateAction
parameters:
- name: id
in: path
description: Identifier of the table.
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: false
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSnapshotRequest'
responses:
'404':
description: Table not found.
'400':
description: Snapshot not supported for this backend or external bucket.
'403':
description: Access denied.
'503':
description: Bucket or backend is under maintenance.
'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/TableSnapshotCreateJobResult'
x-storage-job-result:
application/json:
schema:
$ref: '#/components/schemas/TableSnapshotCreateJobResult'
/v2/storage/branch/{branchId}/tables/{id}/metadata:
get:
tags:
- Tables
summary: List table metadata
description: Returns all metadata records for the specified table.
operationId: get_/v2/storage/branch/{branchId}/tables/{id}/metadata::TableGetMetadataAction
parameters:
- name: id
in: path
description: Identifier of the table.
required: true
schema:
type: string
pattern: '[A-Za-z0-9\.\-_]+'
- name: branchId
in: path
required: true
schema:
type: string
responses:
'200':
description: Table metadata list.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/MetadataItemResponse'
'404':
description: Returned when the table is not found.
'403':
description: Returned when the token lacks read access to the bucket.
post:
tags:
- Tables
summary: Create or update table metadata
description: Creates new metadata records or updates existing ones for the specified table and its columns.
operationId: post_/v2/storage/branch/{branchId}/tables/{id}/metadata::TableCreateOrUpdateMetadataAction
parameters:
- name: id
in: path
description: Identifier of the table.
required: true
schema:
type: string
pattern: '[A-Za-z0-9\.\-_]+'
- name: branchId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CreateTableMetadataRequest'
responses:
'201':
description: Metadata successfully created or updated.
content:
application/json:
schema:
$ref: '#/components/schemas/TableCreateOrUpdateMetadataResponse'
'404':
description: Returned when the table is not found.
'403':
description: Returned when permissions are insufficient or provider cannot be modified.
/v2/storage/tables/{id}/metadata:
get:
tags:
- Tables
summary: List table metadata
description: Returns all metadata records for the specified table.
operationId: get_/v2/storage/tables/{id}/metadata::TableGetMetadataAction
parameters:
- name: id
in: path
description: Identifier of the table.
required: true
schema:
type: string
pattern: '[A-Za-z0-9\.\-_]+'
responses:
'200':
description: Table metadata list.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/MetadataItemResponse'
'404':
description: Returned when the table is not found.
'403':
description: Returned when the token lacks read access to the bucket.
post:
tags:
- Tables
summary: Create or update table metadata
description: Creates new metadata records or updates existing ones for the specified table and its columns.
operationId: post_/v2/storage/tables/{id}/metadata::TableCreateOrUpdateMetadataAction
parameters:
- name: id
in: path
description: Identifier of the table.
required: true
schema:
type: string
pattern: '[A-Za-z0-9\.\-_]+'
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CreateTableMetadataRequest'
responses:
'201':
description: Metadata successfully created or updated.
content:
application/json:
schema:
$ref: '#/components/schemas/TableCreateOrUpdateMetadataResponse'
'404':
description: Returned when the table is not found.
'403':
description: Returned when permissions are insufficient or provider cannot be modified.
/v2/storage/branch/{branchId}/tables/{tableId}/definition:
put:
tags:
- Tables
summary: Update table definition
description: "Updates table and column definition metadata. Async-only - returns 202 with a storage job; poll it for completion. Backend DDL changes are not atomic across multiple column operations. If the async job fails after applying some changes, previously applied changes may remain applied. Re-read the table definition before retrying.\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 [TableCreateResponse](#model-TableCreateResponse).\n\n Parameters of job will be [TableDefinitionUpdateJobParams](#components-schemas-TableDefinitionUpdateJobParams)."
operationId: put_/v2/storage/branch/{branchId}/tables/{tableId}/definition::TableDefinitionUpdateAction
parameters:
- name: tableId
in: path
description: Table string id (e.g. `in.c-main.orders`).
required: true
schema:
type: string
pattern: .+
- name: branchId
in: path
required: true
schema:
type: string
- name: X-KBC-Backend
in: header
schema:
schema: BackendConfigurationRequest
properties:
context:
type: string
nullable: true
minLength: 1
type: object
responses:
'404':
description: Either table, bucket, or column was not found.
'400':
description: The request does not contain any effective definition changes.
'403':
description: Access to the table was denied.
'422':
description: The backend does not support table definition updates.
'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/TableCreateResponse'
x-storage-job-result:
application/json:
schema:
$ref: '#/components/schemas/TableCreateResponse'
x-storage-job-params:
application/json:
schema:
$ref: '#/components/schemas/TableDefinitionUpdateJobParams'
/v2/storage/tables/{tableId}/definition:
put:
tags:
- Tables
summary: Update table definition
description: "Updates table and column definition metadata. Async-only - returns 202 with a storage job; poll it for completion. Backend DDL changes are not atomic across multiple column operations. If the async job fails after applying some changes, previously applied changes may remain applied. Re-read the table definition before retrying.\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 [TableCreateResponse](#model-TableCreateResponse).\n\n Parameters of job will be [TableDefinitionUpdateJobParams](#components-schemas-TableDefinitionUpdateJobParams)."
operationId: put_/v2/storage/tables/{tableId}/definition::TableDefinitionUpdateAction
parameters:
- name: tableId
in: path
description: Table string id (e.g. `in.c-main.orders`).
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
responses:
'404':
description: Either table, bucket, or column was not found.
'400':
description: The request does not contain any effective definition changes.
'403':
description: Access to the table was denied.
'422':
description: The backend does not support table definition updates.
'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/TableCreateResponse'
x-storage-job-result:
application/json:
schema:
$ref: '#/components/schemas/TableCreateResponse'
x-storage-job-params:
application/json:
schema:
$ref: '#/components/schemas/TableDefinitionUpdateJobParams'
/v2/storage/branch/{branchId}/tables/{id}:
get:
tags:
- Tables
summary: Get table detail
description: Retrieve detailed information about a table including metadata and bucket info.
operationId: get_/v2/storage/branch/{branchId}/tables/{id}::TableDetailAction
parameters:
- name: id
in: path
description: Identifier of the table.
required: true
schema:
type: string
pattern: '[A-Za-z0-9\.\-_]+'
- name: branchId
in: path
required: true
schema:
type: string
responses:
'200':
description: Table detail response
content:
application/json:
schema:
$ref: '#/components/schemas/TableDetailResponse'
'404':
description: Returned when the table or bucket is not found.
'403':
description: Access denied to the table.
/v2/storage/tables/{id}:
get:
tags:
- Tables
summary: Get table detail
description: Retrieve detailed information about a table including metadata and bucket info.
operationId: get_/v2/storage/tables/{id}::TableDetailAction
parameters:
- name: id
in: path
description: Identifier of the table.
required: true
schema:
type: string
pattern: '[A-Za-z0-9\.\-_]+'
responses:
'200':
description: Table detail response
content:
application/json:
schema:
$ref: '#/components/schemas/TableDetailResponse'
'404':
description: Returned when the table or bucket is not found.
'403':
description: Access denied to the table.
/v2/storage/branch/{branchId}/tables/{id}/metadata/{metadataId}:
delete:
tags:
- Tables
summary: Delete table metadata
description: Deletes a metadata record for the specified storage table.
operationId: delete_/v2/storage/branch/{branchId}/tables/{id}/metadata/{metadataId}::TableDeleteMetadataAction
parameters:
- name: id
in: path
description: Identifier of the table.
required: true
schema:
type: string
pattern: '[A-Za-z0-9\.\-_]+'
- 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 table or metadata record is not found.
'403':
description: Returned when permissions are insufficient or provider cannot be deleted.
/v2/storage/tables/{id}/metadata/{metadataId}:
delete:
tags:
- Tables
summary: Delete table metadata
description: Deletes a metadata record for the specified storage table.
operationId: delete_/v2/storage/tables/{id}/metadata/{metadataId}::TableDeleteMetadataAction
parameters:
- name: id
in: path
description: Identifier of the table.
required: true
schema:
type: string
pattern: '[A-Za-z0-9\.\-_]+'
- 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 table or metadata record is not found.
'403':
description: Returned when permissions are insufficient or provider cannot be deleted.
/v2/storage/branch/{branchId}/tables/{tableId}/swap:
post:
tags:
- Tables
summary: Swap two tables
description: "Exchanges the physical storage of two tables in the same bucket. Async-only — returns 202 with a storage job; poll it for completion. Aliases are not transferred with table identity: each alias keeps pointing at the same physical position, so after the swap aliases expose the data of the other table. Both tables must live in the same bucket on the same backend connection.\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 [TableSwapResult](#model-TableSwapResult).\n\n Parameters of job will be [SwapJobParams](#components-schemas-SwapJobParams)."
operationId: post_/v2/storage/branch/{branchId}/tables/{tableId}/swap::TableSwapAction
parameters:
- name: tableId
in: path
description: Source table string id (e.g. `in.c-main.orders`).
required: true
schema:
type: string
pattern: .+
- name: branchId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/TableSwapRequest'
responses:
'400':
description: Validation error in the request payload, or the backend does not support swap (`storage.driver.unsupportedOperation`).
'404':
description: Either table or its bucket was not found.
'403':
description: Access to one of the tables was denied.
'422':
description: 'Operation not applicable: source and target are the same table (`storage.tables.sameTableSwap`), either side is an alias (`storage.tables.cannotSwapAlias`), or the tables live in different buckets (`storage.tables.crossBucketSwap`).'
'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/TableSwapResult'
x-storage-job-result:
application/json:
schema:
$ref: '#/components/schemas/TableSwapResult'
x-storage-job-params:
application/json:
schema:
$ref: '#/components/schemas/SwapJobParams'
components:
schemas:
BucketListingCreateJobResult:
required:
- idBucket
- listingId
- listingResourceName
- providerResourceName
properties:
idBucket:
description: Identifier of the bucket the listing was created on.
type: integer
listingId:
description: User-defined listing ID, unique within the project exchange.
type: string
listingResourceName:
description: Fully-qualified GCP Analytics Hub listing resource name.
type: string
providerResourceName:
description: Fully-qualified GCP Analytics Hub data exchange resource name.
type: string
type: object
BucketListingDeleteResponse:
required:
- id
- status
- url
- operationName
- operationParams
- createdTime
- creatorToken
- metrics
properties:
id:
description: Job ID.
type: integer
status:
description: Job status.
type: string
url:
description: URL to retrieve job details.
type: string
tableId:
description: Table identifier if applicable.
type: string
nullable: true
operationName:
description: Name of the operation.
type: string
operationParams:
description: Parameters passed to the operation.
type: object
additionalProperties:
type: mixed
createdTime:
description: Job creation timestamp.
type: string
format: date-time
startTime:
description: Job start timestamp.
type: string
format: date-time
nullable: true
endTime:
description: Job completion timestamp.
type: string
format: date-time
nullable: true
runId:
description: Unique run identifier.
type: string
nullable: true
results:
description: Operation results; content varies.
type: object
nullable: true
creatorToken:
description: Creator token information.
properties:
id:
description: ID of the token that created this job.
type: integer
description:
description: Description of the creator token.
type: string
nullable: true
type: object
metrics:
description: Job execution metrics.
type: object
additionalProperties:
type: mixed
error:
description: Job error information if the job failed.
properties:
code:
description: Error code if job failed.
type: string
nullable: true
message:
description: Error message if job failed.
type: string
nullable: true
exceptionId:
description: Exception identifier.
type: string
nullable: true
type: object
nullable: true
type: object
TableSnapshotCreateJobResult:
required:
- id
- createdTime
- type
- creatorToken
- uri
- dataFileId
properties:
id:
type: string
description:
type: string
nullable: true
createdTime:
type: string
format: date-time
type:
type: string
creatorToken:
properties:
id:
type: integer
description:
type: string
type: object
uri:
type: string
dataFileId:
type: integer
type: object
SourceTableResponse:
required:
- id
- uri
- project
- isAlias
properties:
id:
description: Source table ID
type: string
uri:
description: Source table URI
type: string
project:
required:
- id
- name
properties:
id:
description: Project ID
type: integer
name:
description: Project name
type: string
type: object
isAlias:
description: Whether the source table is itself an alias
type: boolean
type: object
TableCreateOrUpdateMetadataResponse:
required:
- metadata
- columnsMetadata
properties:
metadata:
description: Table-level metadata records.
type: array
items:
$ref: '#/components/schemas/MetadataItemResponse'
columnsMetadata:
description: Column metadata keyed by column name.
type: object
additionalProperties:
type: array
items:
$ref: '#/components/schemas/MetadataItemResponse'
type: object
TableSwapRequest:
required:
- targetTableId
properties:
targetTableId:
type: string
type: object
TableCreateResponse:
required:
- uri
- id
- name
- displayName
- transactional
- primaryKey
- indexType
- indexKey
- distributionType
- distributionKey
- syntheticPrimaryKeyEnabled
- created
- lastImportDate
- lastChangeDate
- rowsCount
- dataSizeBytes
- isAlias
- isAliasable
- isTyped
- tableType
- path
- columns
properties:
uri:
description: Table API URI
type: string
id:
description: Table ID
type: string
name:
description: Table name
type: string
displayName:
description: Table display name
type: string
transactional:
description: Is transactional
type: boolean
primaryKey:
description: Primary key columns
type: array
items:
type: string
indexType:
description: Index type
type: string
nullable: true
indexKey:
description: Index key columns
type: array
items:
type: string
distributionType:
description: Distribution type
type: string
nullable: true
distributionKey:
description: Distribution key columns
type: array
items:
type: string
syntheticPrimaryKeyEnabled:
description: Synthetic primary key enabled
type: boolean
created:
description: Created timestamp
type: string
format: date-time
nullable: true
lastImportDate:
description: Last import date
type: string
format: date-time
nullable: true
lastChangeDate:
description: Last change date
type: string
format: date-time
nullable: true
rowsCount:
description: Rows count
type: integer
nullable: true
dataSizeBytes:
description: Data size in bytes
type: integer
nullable: true
isAlias:
description: Is alias
type: boolean
isAliasable:
description: Is aliasable
type: boolean
isTyped:
description: Is typed table
type: boolean
tableType:
description: Table type
type: string
path:
description: Table path
type: string
columns:
description: List of column names
# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/keboola/refs/heads/main/openapi/keboola-tables-api-openapi.yml