{ "openapi": "3.0.0", "info": { "title": "Keboola Storage API", "description": "Storage API provides an interface for sending data to Keboola Connection (KBC). The following are the most\nimportant features of the API:\n- Importing CSV data into Table Storage\n- Exporting CSV data from Table Storage\n- Loading arbitrary files into File Storage\n- Managing tables including keys and indexes\n- Managing buckets including sharing\n- Managing component configurations\n\nThe CSV files interchanged with Storage must adhere to the\n[RFC4180 Specification](http://tools.ietf.org/html/rfc4180) and must use the `UTF-8` encoding.\nThe files can be sent uncompressed or gzipped. You can find more information about working\nwith these files in [our manual](https://help.keboola.com/storage/tables/csv-files/).\n\nFor a list of available clients and their features, see the\n[Developers Documentation](https://developers.keboola.com/integrate/storage/).\nIn it you will also find more complex examples of\n[working with the API](https://developers.keboola.com/integrate/storage/api/).\nThis documentation assumes that you are already familiar with the\n[Keboola Connection Storage component](https://help.keboola.com/storage/).\n\n## HTTP Response Codes\nThe response from Storage API will have an\n[HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) that will help\nyou determine if the request was successful. In case of an error, the HTTP status code\nwill help you determine the cause of the error. The status codes used by Storage API are\nlisted in the below tables.\n\n### Success responses\n| Code | Description |\n| ---- | ----------- |\n| 200 `OK` | The request was successful. |\n| 201 `Created` | The request was successful and a new resource was created. |\n| 202 `Accepted` | Used for asynchronous tasks (see *Synchronous and Asynchronous Calls*). A job resource is returned. The actual result must be obtained in another API call. |\n| 204 `No Content` | The request was successful but there is nothing to return. Usually used as a response of DELETE requests. |\n\n### Error responses\n| Code | Description |\n| ---- | ----------- |\n| 400 `Bad Request` | The request was invalid. Usually caused by invalid input data (missing arguments, invalid arguments values, etc.). The cause of the error is described in the response. |\n| 401 `Unauthorized` | Authentication failed. |\n| 403 `Forbidden` | You don't have access to the resource. |\n| 404 `Not Found` | You're asking for something that doesn't exist. |\n| 500 `Internal Server Error` | Something went wrong. We are sorry, it is our fault and we will make our best to fix it! Feel free to [send us a ticket](mailto:support@keboola.com). |\n| 503 `Temporary Unavailable` | This response is typically returned when the system is under maintenance. The maintenance reason and expected maintenance end time are also returned in the response. |\n\n## Authentication\nAuthentication is done via Storage API **Token**. There are multiple options\nfor [obtaining a Storage API Token](https://help.keboola.com/storage/tokens/).\nThe token must be sent as a value of the `X-StorageApi-Token` HTTP header with each API call.\n\nMost API calls work within a *KBC Project*. The project is always derived from the token used for the API call.\nSo the token includes both authentication and authorization to a single project.\n\n## Synchronous and Asynchronous Calls\nCalls that represent potentially long-running actions are performed asynchronously.\nThese are for example: loading table data, snapshotting, exporting table data, table structure modifications, etc.\nAll asynchronous calls return the HTTP Response code `202` and a Job Resource (see the *Jobs* section).\nTo obtain the actual result of the call, you have to monitor the job status by\n[polling the Job Resource URL](https://developers.keboola.com/integrate/storage/api/import-export/#python-example).\n\n## Partial Response\nSome API calls that list objects are returning related resources by default. For example,\nthe table list also returns the table bucket properties and table attributes. You can use the `include` parameter\nto return only the required resources in the response.\n\n## HTTP headers\nSome API calls support custom HTTP headers.\n\nSupported HTTP headers are:\n- `X-StorageApi-Token (string)`: storage api authentication token\n- `X-KBC-RunId (string)`: id mainly used to match component run with storage job\n- `X-KBC-Backend (json string)`: header used to customize underlying backend configuration. Supported options are `context` and `size` (supported options differ for each backend). Example: `'{\"context\":\"custom-wlm-group\",\"size\":\"XL\"}'`\n\n## Development branch URL prefix\nSelected endpoints can be called with a `/branch/{branchId}/` URL prefix. Using `default` as the branch id\nis the same as calling the endpoint without the prefix, e.g. `GET /v2/storage/tokens/verify` is the same as\n`GET /v2/storage/branch/default/tokens/verify`. See the *Development Branches* section.\n", "version": "2.0" }, "servers": [ { "url": "https://connection.keboola.com", "description": "AWS US East" }, { "url": "https://connection.eu-central-1.keboola.com", "description": "AWS EU Central" }, { "url": "https://connection.north-europe.azure.keboola.com", "description": "Azure North Europe" }, { "url": "https://connection.us-east4.gcp.keboola.com", "description": "GCP US East" }, { "url": "https://connection.europe-west3.gcp.keboola.com", "description": "GCP EU West" } ], "paths": { "/v2/storage/branch/{branchId}/tokens/verify": { "get": { "tags": [ "Tokens and Permissions" ], "summary": "Token verification", "description": "Checks the token privileges and returns information about the project to which the token belongs (`owner`)\nand the associated administrator (`admin`) with organization (if any). If the project is configured with pay as you go billing,\na `payAsYouGo` section with details is available under `owner` info. This call can be executed by all tokens.", "operationId": "get_/v2/storage/branch/{branchId}/tokens/verify::TokenVerifyAction", "parameters": [ { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Token verification response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenVerifyResponse" }, "example": { "id": "44", "created": "2017-02-13T10:27:50+0100", "refreshed": "2017-11-13T16:48:28+0100", "description": "", "uri": "https://connection.keboola.com/v2/storage/tokens/44", "isMasterToken": true, "canManageBuckets": true, "canManageTokens": true, "canReadAllFileUploads": true, "canPurgeTrash": true, "canManageProtectedDefaultBranch": false, "canCreateJobs": false, "canReadAllProjectEvents": true, "canManageDevBranches": true, "expires": null, "isExpired": false, "isDisabled": false, "dailyCapacity": 0, "actor": null, "bucketPermissions": { "in.c-test": "manage" }, "owner": { "id": 58, "name": "Buckets 5", "type": "production", "region": "us-east-1", "created": "2022-08-18T08:47:07+0200", "expires": null, "features": [], "dataSizeBytes": 112128, "rowsCount": 1036, "hasMysql": false, "hasSynapse": false, "hasSnowflake": true, "hasExasol": false, "hasTeradata": false, "hasBigquery": false, "defaultBackend": "snowflake", "hasTryModeOn": "0", "limits": { "storage.dataSizeBytes": { "name": "storage.dataSizeBytes", "value": 50000000000 }, "storage.jobsParallelism": { "name": "storage.jobsParallelism", "value": 10 } }, "metrics": { "storage.dataSizeBytes": { "name": "storage.dataSizeBytes", "value": 112128 }, "storage.rowsCount": { "name": "storage.rowsCount", "value": 1036 } }, "isDisabled": false, "billedMonthlyPrice": null, "dataRetentionTimeInDays": 7, "assignedBackends": [ "snowflake" ], "timezone": null, "isBYODB": false, "usersCount": 2, "fileStorageProvider": "aws" }, "isBYODB": false, "organization": { "id": "123", "created": "2017-02-13T12:01:05+01:00" }, "admin": { "name": "John Doe", "id": 124, "features": [], "isOrganizationMember": true, "role": "admin", "isActivated": true }, "adminOwner": { "id": 124, "name": "John Doe", "email": "john.doe@keboola.com" } } } } }, "401": { "description": "The token is missing, invalid, expired or disabled." } } } }, "/v2/storage/tokens/verify": { "get": { "tags": [ "Tokens and Permissions" ], "summary": "Token verification", "description": "Checks the token privileges and returns information about the project to which the token belongs (`owner`)\nand the associated administrator (`admin`) with organization (if any). If the project is configured with pay as you go billing,\na `payAsYouGo` section with details is available under `owner` info. This call can be executed by all tokens.", "operationId": "get_/v2/storage/tokens/verify::TokenVerifyAction", "responses": { "200": { "description": "Token verification response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenVerifyResponse" }, "example": { "id": "44", "created": "2017-02-13T10:27:50+0100", "refreshed": "2017-11-13T16:48:28+0100", "description": "", "uri": "https://connection.keboola.com/v2/storage/tokens/44", "isMasterToken": true, "canManageBuckets": true, "canManageTokens": true, "canReadAllFileUploads": true, "canPurgeTrash": true, "canManageProtectedDefaultBranch": false, "canCreateJobs": false, "canReadAllProjectEvents": true, "canManageDevBranches": true, "expires": null, "isExpired": false, "isDisabled": false, "dailyCapacity": 0, "actor": null, "bucketPermissions": { "in.c-test": "manage" }, "owner": { "id": 58, "name": "Buckets 5", "type": "production", "region": "us-east-1", "created": "2022-08-18T08:47:07+0200", "expires": null, "features": [], "dataSizeBytes": 112128, "rowsCount": 1036, "hasMysql": false, "hasSynapse": false, "hasSnowflake": true, "hasExasol": false, "hasTeradata": false, "hasBigquery": false, "defaultBackend": "snowflake", "hasTryModeOn": "0", "limits": { "storage.dataSizeBytes": { "name": "storage.dataSizeBytes", "value": 50000000000 }, "storage.jobsParallelism": { "name": "storage.jobsParallelism", "value": 10 } }, "metrics": { "storage.dataSizeBytes": { "name": "storage.dataSizeBytes", "value": 112128 }, "storage.rowsCount": { "name": "storage.rowsCount", "value": 1036 } }, "isDisabled": false, "billedMonthlyPrice": null, "dataRetentionTimeInDays": 7, "assignedBackends": [ "snowflake" ], "timezone": null, "isBYODB": false, "usersCount": 2, "fileStorageProvider": "aws" }, "isBYODB": false, "organization": { "id": "123", "created": "2017-02-13T12:01:05+01:00" }, "admin": { "name": "John Doe", "id": 124, "features": [], "isOrganizationMember": true, "role": "admin", "isActivated": true }, "adminOwner": { "id": 124, "name": "John Doe", "email": "john.doe@keboola.com" } } } } }, "401": { "description": "The token is missing, invalid, expired or disabled." } } } }, "/v2/storage/branch/{branchId}/buckets/register-guide": { "get": { "tags": [ "Buckets" ], "summary": "Register bucket - guide", "description": "**EXPERIMENTAL**\n\nReturns a guide on how exactly you should register the external bucket. The text is Markdown formatted. Available for **Snowflake** and **BigQuery** backend only. Requires the `external-buckets` and `input-mapping-read-only-storage` project features and is available in the default branch only.", "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 schema. Snowflake: `[\"database-name\", \"schema-name\"]`; BigQuery: `[\"dataset-name\"]`.", "required": true, "schema": { "description": "Path to the schema. Snowflake: `[\"database-name\", \"schema-name\"]`; BigQuery: `[\"dataset-name\"]`.", "type": "array", "items": { "type": "string", "minLength": 1 }, "example": [ "my-database-name", "my-schema-name" ] }, "example": [ "my-database-name", "my-schema-name" ] }, { "name": "backend", "in": "query", "description": "Bucket backend type; the default value is determined by the project settings.", "required": false, "schema": { "description": "Bucket backend type; the default value is determined by the project settings.", "type": "string", "example": "snowflake", "nullable": true, "enum": [ "snowflake", "bigquery" ] }, "example": "snowflake" }, { "name": "isSnowflakeSharedDatabase", "in": "query", "description": "Render the guide for a Snowflake shared database.", "required": false, "schema": { "description": "Render the guide for a Snowflake shared database.", "type": "boolean", "example": false, "nullable": true }, "example": false } ], "responses": { "200": { "description": "Markdown guide for registering the bucket.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketRegisterGuideResponse" }, "example": { "markdown": "* Log into Snowflake as account with at least following permissions\n * grant usage on the schema and database\n * grant select on all tables in the schema and future tables in the schema\n* Execute following queries\n\n```snowflake\nGRANT USAGE ON DATABASE \"my-database-name\" TO ROLE \"KEBOOLA_123\" WITH GRANT OPTION;\nGRANT USAGE ON SCHEMA \"my-database-name\".\"my-schema-name\" TO ROLE \"KEBOOLA_123\" WITH GRANT OPTION;\n\nGRANT SELECT ON ALL TABLES IN SCHEMA \"my-database-name\".\"my-schema-name\" TO ROLE \"KEBOOLA_123\" WITH GRANT OPTION;\nGRANT SELECT ON FUTURE TABLES IN SCHEMA \"my-database-name\".\"my-schema-name\" TO ROLE \"KEBOOLA_123\" WITH GRANT OPTION;\n```\n" } } } }, "400": { "description": "Invalid request, the project lacks the `input-mapping-read-only-storage` or `external-buckets` feature (`manage.project.missingFeatureFlag`), or the backend is not supported or not assigned to the project (`storage.backendNotAllowed`)." }, "403": { "description": "The token cannot manage buckets." }, "501": { "description": "The endpoint is available in the default branch only." } } } }, "/v2/storage/buckets/register-guide": { "get": { "tags": [ "Buckets" ], "summary": "Register bucket - guide", "description": "**EXPERIMENTAL**\n\nReturns a guide on how exactly you should register the external bucket. The text is Markdown formatted. Available for **Snowflake** and **BigQuery** backend only. Requires the `external-buckets` and `input-mapping-read-only-storage` project features and is available in the default branch only.", "operationId": "get_/v2/storage/buckets/register-guide::BucketRegisterGuideAction", "parameters": [ { "name": "path[]", "in": "query", "description": "Path to the schema. Snowflake: `[\"database-name\", \"schema-name\"]`; BigQuery: `[\"dataset-name\"]`.", "required": true, "schema": { "description": "Path to the schema. Snowflake: `[\"database-name\", \"schema-name\"]`; BigQuery: `[\"dataset-name\"]`.", "type": "array", "items": { "type": "string", "minLength": 1 }, "example": [ "my-database-name", "my-schema-name" ] }, "example": [ "my-database-name", "my-schema-name" ] }, { "name": "backend", "in": "query", "description": "Bucket backend type; the default value is determined by the project settings.", "required": false, "schema": { "description": "Bucket backend type; the default value is determined by the project settings.", "type": "string", "example": "snowflake", "nullable": true, "enum": [ "snowflake", "bigquery" ] }, "example": "snowflake" }, { "name": "isSnowflakeSharedDatabase", "in": "query", "description": "Render the guide for a Snowflake shared database.", "required": false, "schema": { "description": "Render the guide for a Snowflake shared database.", "type": "boolean", "example": false, "nullable": true }, "example": false } ], "responses": { "200": { "description": "Markdown guide for registering the bucket.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketRegisterGuideResponse" }, "example": { "markdown": "* Log into Snowflake as account with at least following permissions\n * grant usage on the schema and database\n * grant select on all tables in the schema and future tables in the schema\n* Execute following queries\n\n```snowflake\nGRANT USAGE ON DATABASE \"my-database-name\" TO ROLE \"KEBOOLA_123\" WITH GRANT OPTION;\nGRANT USAGE ON SCHEMA \"my-database-name\".\"my-schema-name\" TO ROLE \"KEBOOLA_123\" WITH GRANT OPTION;\n\nGRANT SELECT ON ALL TABLES IN SCHEMA \"my-database-name\".\"my-schema-name\" TO ROLE \"KEBOOLA_123\" WITH GRANT OPTION;\nGRANT SELECT ON FUTURE TABLES IN SCHEMA \"my-database-name\".\"my-schema-name\" TO ROLE \"KEBOOLA_123\" WITH GRANT OPTION;\n```\n" } } } }, "400": { "description": "Invalid request, the project lacks the `input-mapping-read-only-storage` or `external-buckets` feature (`manage.project.missingFeatureFlag`), or the backend is not supported or not assigned to the project (`storage.backendNotAllowed`)." }, "403": { "description": "The token cannot manage buckets." }, "501": { "description": "The endpoint is available in the default branch only." } } } }, "/v2/storage/branch/{branchId}/buckets": { "get": { "tags": [ "Buckets" ], "summary": "List all buckets", "description": "All buckets are returned.\n\n[Buckets](https://help.keboola.com/storage/buckets/) are containers for one or more data tables. Access to buckets can be limited by access tokens. Each bucket has a *backend* in which all tables are created: Snowflake (default) or BigQuery.", "operationId": "get_/v2/storage/branch/{branchId}/buckets::BucketsListAction", "parameters": [ { "name": "include", "in": "query", "description": "Comma-separated list of resources to include for each bucket: `metadata` (bucket metadata), `linkedBuckets` (buckets in other projects linked to this bucket, returned as `linkedBy`).", "required": false, "schema": { "type": "string" }, "example": "metadata,linkedBuckets" }, { "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/BucketListItemResponse" } }, "example": [ { "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-main", "id": "in.c-main", "name": "c-main", "displayName": "main", "idBranch": 1234, "stage": "in", "description": "Main user storage", "tables": "https://connection.keboola.com/v2/storage/buckets/in.c-main", "created": "2017-02-13T12:01:05+0100", "lastChangeDate": "2024-11-28T13:03:13+0100", "updated": "2024-11-28T13:03:13+0100", "isReadOnly": false, "dataSizeBytes": 1536, "rowsCount": 32, "isMaintenance": false, "backend": "snowflake", "sharing": null, "hasExternalSchema": false, "databaseName": null, "path": "database_name.c-main", "isSnowflakeSharedDatabase": false, "isLinkedBucket": false, "color": null, "bucketSharingAllowed": true, "sharedByActor": null, "owner": { "id": 123, "name": "Jan Developer", "email": "jan.dev@keboola.com" }, "backendPath": [ "KBC_PRJ_123", "in.c-main" ], "attributes": [], "linkedBy": [ { "id": "in.c-linked-bucket", "created": "2017-02-13T12:01:05+0100", "project": { "id": "321", "name": "Some Project" } } ] }, { "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-organizationData", "id": "in.c-organizationData", "name": "c-organizationData", "displayName": "organization", "idBranch": 1234, "stage": "in", "description": "Source bucket description", "tables": "https://connection.keboola.com/v2/storage/buckets/in.c-organizationData", "created": "2020-01-12T18:28:31+0100", "lastChangeDate": "2020-01-12T18:31:49+0100", "updated": "2024-11-28T13:03:13+0100", "isReadOnly": true, "dataSizeBytes": 1536, "rowsCount": 32, "isMaintenance": false, "backend": "snowflake", "sharing": null, "hasExternalSchema": false, "databaseName": null, "path": "database_name.c-organizationData", "isSnowflakeSharedDatabase": false, "isLinkedBucket": true, "color": "#FF0000", "bucketSharingAllowed": false, "sharedByActor": null, "owner": null, "sourceBucket": { "id": "in.c-main", "name": "c-main", "displayName": "main", "stage": "in", "description": "Organization shared data", "sharing": "organization", "created": "2020-01-12T18:28:31+0100", "lastChangeDate": "2020-01-12T18:31:49+0100", "dataSizeBytes": 1536, "rowsCount": 32, "backend": "snowflake", "hasExternalSchema": false, "databaseName": null, "path": "database_name.c-main", "project": { "id": 123, "name": "Project name" }, "color": null, "tables": [ { "id": "in.c-main.languages", "name": "languages", "displayName": "languages", "path": "database_name.c-main.languages" } ], "sharingParameters": [], "sharedBy": { "id": 5, "name": "dev@keboola.com", "date": "2020-02-03T14:58:29+0100" }, "sharedByActor": { "type": "token", "id": "5", "name": "dev@keboola.com", "adminId": null }, "owner": null }, "backendPath": [ "KBC_PRJ_123", "in.c-main" ], "attributes": [] } ] } } } } }, "post": { "tags": [ "Buckets" ], "summary": "Create bucket or link a shared bucket", "description": "Using this API call, you can either create a new bucket in the project, or you can link an existing bucket from another project.\n\n**Create bucket** - send `CreateBucketRequest`. The bucket is created synchronously and returned with `201`.\n\n**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`.", "operationId": "post_/v2/storage/branch/{branchId}/buckets::BucketCreateAction", "parameters": [ { "name": "async", "in": "query", "description": "Link the shared bucket in a background job. Applies to linking only; ignored when creating a bucket.", "required": false, "schema": { "type": "boolean", "default": false }, "example": false }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-KBC-Backend", "in": "header", "schema": { "schema": "BackendConfiguration", "properties": { "context": { "type": "string", "nullable": true, "minLength": 1 } }, "type": "object" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateBucketRequest" }, { "$ref": "#/components/schemas/LinkBucketRequest" } ] }, "example": { "name": "my-new-bucket", "stage": "in", "description": "Some Description" } } } }, "responses": { "201": { "description": "Bucket created, or shared bucket linked synchronously (`async=false`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketCreateResponse" }, "example": { "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", "lastChangeDate": null, "updated": "2024-11-28T13:03:13+0100", "isReadOnly": false, "dataSizeBytes": 0, "rowsCount": 0, "isMaintenance": false, "backend": "snowflake", "sharing": null, "hasExternalSchema": false, "databaseName": null, "path": "database_name.c-my-new-bucket", "isSnowflakeSharedDatabase": false, "isLinkedBucket": false, "color": null, "bucketSharingAllowed": true, "sharedByActor": null, "owner": null, "backendPath": [ "KBC_PRJ_123", "in.c-my-new-bucket" ], "attributes": [] } } } }, "202": { "description": "Shared bucket link enqueued as a job (`async=true`). To see the job detail use the Job Detail endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "bucketLink", "operationParams": { "bucketName": "organizationData", "displayName": "organizationData", "bucketStage": "in", "sourceProjectId": 105, "sourceBucketId": "in.c-API-sharing", "devBranchId": 4230, "queue": "main" }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "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": { "description": "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": { "description": "Source bucket to link was not found (`storage.buckets.notFound`)." }, "501": { "description": "Operation is not supported for Snowflake Partner Connect projects (`storage.buckets.notSupportedForSPCProject`)." }, "503": { "description": "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." } } } }, "/v2/storage/buckets": { "get": { "tags": [ "Buckets" ], "summary": "List all buckets", "description": "All buckets are returned.\n\n[Buckets](https://help.keboola.com/storage/buckets/) are containers for one or more data tables. Access to buckets can be limited by access tokens. Each bucket has a *backend* in which all tables are created: Snowflake (default) or BigQuery.", "operationId": "get_/v2/storage/buckets::BucketsListAction", "parameters": [ { "name": "include", "in": "query", "description": "Comma-separated list of resources to include for each bucket: `metadata` (bucket metadata), `linkedBuckets` (buckets in other projects linked to this bucket, returned as `linkedBy`).", "required": false, "schema": { "type": "string" }, "example": "metadata,linkedBuckets" } ], "responses": { "200": { "description": "List of buckets.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BucketListItemResponse" } }, "example": [ { "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-main", "id": "in.c-main", "name": "c-main", "displayName": "main", "idBranch": 1234, "stage": "in", "description": "Main user storage", "tables": "https://connection.keboola.com/v2/storage/buckets/in.c-main", "created": "2017-02-13T12:01:05+0100", "lastChangeDate": "2024-11-28T13:03:13+0100", "updated": "2024-11-28T13:03:13+0100", "isReadOnly": false, "dataSizeBytes": 1536, "rowsCount": 32, "isMaintenance": false, "backend": "snowflake", "sharing": null, "hasExternalSchema": false, "databaseName": null, "path": "database_name.c-main", "isSnowflakeSharedDatabase": false, "isLinkedBucket": false, "color": null, "bucketSharingAllowed": true, "sharedByActor": null, "owner": { "id": 123, "name": "Jan Developer", "email": "jan.dev@keboola.com" }, "backendPath": [ "KBC_PRJ_123", "in.c-main" ], "attributes": [], "linkedBy": [ { "id": "in.c-linked-bucket", "created": "2017-02-13T12:01:05+0100", "project": { "id": "321", "name": "Some Project" } } ] }, { "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-organizationData", "id": "in.c-organizationData", "name": "c-organizationData", "displayName": "organization", "idBranch": 1234, "stage": "in", "description": "Source bucket description", "tables": "https://connection.keboola.com/v2/storage/buckets/in.c-organizationData", "created": "2020-01-12T18:28:31+0100", "lastChangeDate": "2020-01-12T18:31:49+0100", "updated": "2024-11-28T13:03:13+0100", "isReadOnly": true, "dataSizeBytes": 1536, "rowsCount": 32, "isMaintenance": false, "backend": "snowflake", "sharing": null, "hasExternalSchema": false, "databaseName": null, "path": "database_name.c-organizationData", "isSnowflakeSharedDatabase": false, "isLinkedBucket": true, "color": "#FF0000", "bucketSharingAllowed": false, "sharedByActor": null, "owner": null, "sourceBucket": { "id": "in.c-main", "name": "c-main", "displayName": "main", "stage": "in", "description": "Organization shared data", "sharing": "organization", "created": "2020-01-12T18:28:31+0100", "lastChangeDate": "2020-01-12T18:31:49+0100", "dataSizeBytes": 1536, "rowsCount": 32, "backend": "snowflake", "hasExternalSchema": false, "databaseName": null, "path": "database_name.c-main", "project": { "id": 123, "name": "Project name" }, "color": null, "tables": [ { "id": "in.c-main.languages", "name": "languages", "displayName": "languages", "path": "database_name.c-main.languages" } ], "sharingParameters": [], "sharedBy": { "id": 5, "name": "dev@keboola.com", "date": "2020-02-03T14:58:29+0100" }, "sharedByActor": { "type": "token", "id": "5", "name": "dev@keboola.com", "adminId": null }, "owner": null }, "backendPath": [ "KBC_PRJ_123", "in.c-main" ], "attributes": [] } ] } } } } }, "post": { "tags": [ "Buckets" ], "summary": "Create bucket or link a shared bucket", "description": "Using this API call, you can either create a new bucket in the project, or you can link an existing bucket from another project.\n\n**Create bucket** - send `CreateBucketRequest`. The bucket is created synchronously and returned with `201`.\n\n**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`.", "operationId": "post_/v2/storage/buckets::BucketCreateAction", "parameters": [ { "name": "async", "in": "query", "description": "Link the shared bucket in a background job. Applies to linking only; ignored when creating a bucket.", "required": false, "schema": { "type": "boolean", "default": false }, "example": false }, { "name": "X-KBC-Backend", "in": "header", "schema": { "schema": "BackendConfiguration", "properties": { "context": { "type": "string", "nullable": true, "minLength": 1 } }, "type": "object" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateBucketRequest" }, { "$ref": "#/components/schemas/LinkBucketRequest" } ] }, "example": { "name": "my-new-bucket", "stage": "in", "description": "Some Description" } } } }, "responses": { "201": { "description": "Bucket created, or shared bucket linked synchronously (`async=false`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketCreateResponse" }, "example": { "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", "lastChangeDate": null, "updated": "2024-11-28T13:03:13+0100", "isReadOnly": false, "dataSizeBytes": 0, "rowsCount": 0, "isMaintenance": false, "backend": "snowflake", "sharing": null, "hasExternalSchema": false, "databaseName": null, "path": "database_name.c-my-new-bucket", "isSnowflakeSharedDatabase": false, "isLinkedBucket": false, "color": null, "bucketSharingAllowed": true, "sharedByActor": null, "owner": null, "backendPath": [ "KBC_PRJ_123", "in.c-my-new-bucket" ], "attributes": [] } } } }, "202": { "description": "Shared bucket link enqueued as a job (`async=true`). To see the job detail use the Job Detail endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "bucketLink", "operationParams": { "bucketName": "organizationData", "displayName": "organizationData", "bucketStage": "in", "sourceProjectId": 105, "sourceBucketId": "in.c-API-sharing", "devBranchId": 4230, "queue": "main" }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "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": { "description": "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": { "description": "Source bucket to link was not found (`storage.buckets.notFound`)." }, "501": { "description": "Operation is not supported for Snowflake Partner Connect projects (`storage.buckets.notSupportedForSPCProject`)." }, "503": { "description": "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." } } } }, "/v2/storage/branch/{branchId}/buckets/{bucketId}/metadata": { "get": { "tags": [ "Metadata" ], "summary": "List bucket metadata", "description": "Lists all metadata associated with the specified bucket.\n\nMetadata are timestamped key-value pairs separated by the provider, where the provider is the originating component.", "operationId": "get_/v2/storage/branch/{branchId}/buckets/{bucketId}/metadata::BucketMetadataAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Id of the bucket.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bucket metadata list.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } }, "example": [ { "id": "123", "key": "attribute_key", "value": "attribute_value", "provider": "keboola.some-komponent", "timestamp": "2016-09-19T13:02:11+0200" }, { "id": "124", "key": "another_attribute_key", "value": "attribute_value", "provider": "keboola.some-komponent", "timestamp": "2016-09-19T13:02:11+0200" } ] } } }, "404": { "description": "Returned when the bucket is not found in the project (`storage.buckets.notFound`)." } } }, "post": { "tags": [ "Metadata" ], "summary": "Create or update bucket metadata", "description": "Sets multiple metadata with one call. If the given key and provider combination already exist\nfor the bucket, the data will be updated with the new value and timestamp. All metadata associated\nwith the bucket are returned in the response.\n\nMetadata are timestamped key-value pairs separated by the provider, where the provider is the originating component.", "operationId": "post_/v2/storage/branch/{branchId}/buckets/{bucketId}/metadata::BucketCreateOrUpdateMetadataAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Id of the bucket.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateMetadataWithProviderRequest" } ] } } } }, "responses": { "201": { "description": "All metadata associated with the bucket.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } }, "example": [ { "id": "19509", "key": "some-key", "value": "Some value", "provider": "test-component", "timestamp": "2017-02-13T23:36:10+0100" } ] } } }, "403": { "description": "Returned when the token has no write access to the bucket." }, "404": { "description": "Returned when the bucket is not found in the project (`storage.buckets.notFound`)." } } } }, "/v2/storage/buckets/{bucketId}/metadata": { "get": { "tags": [ "Metadata" ], "summary": "List bucket metadata", "description": "Lists all metadata associated with the specified bucket.\n\nMetadata are timestamped key-value pairs separated by the provider, where the provider is the originating component.", "operationId": "get_/v2/storage/buckets/{bucketId}/metadata::BucketMetadataAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Id of the bucket.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" } ], "responses": { "200": { "description": "Bucket metadata list.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } }, "example": [ { "id": "123", "key": "attribute_key", "value": "attribute_value", "provider": "keboola.some-komponent", "timestamp": "2016-09-19T13:02:11+0200" }, { "id": "124", "key": "another_attribute_key", "value": "attribute_value", "provider": "keboola.some-komponent", "timestamp": "2016-09-19T13:02:11+0200" } ] } } }, "404": { "description": "Returned when the bucket is not found in the project (`storage.buckets.notFound`)." } } }, "post": { "tags": [ "Metadata" ], "summary": "Create or update bucket metadata", "description": "Sets multiple metadata with one call. If the given key and provider combination already exist\nfor the bucket, the data will be updated with the new value and timestamp. All metadata associated\nwith the bucket are returned in the response.\n\nMetadata are timestamped key-value pairs separated by the provider, where the provider is the originating component.", "operationId": "post_/v2/storage/buckets/{bucketId}/metadata::BucketCreateOrUpdateMetadataAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Id of the bucket.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateMetadataWithProviderRequest" } ] } } } }, "responses": { "201": { "description": "All metadata associated with the bucket.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } }, "example": [ { "id": "19509", "key": "some-key", "value": "Some value", "provider": "test-component", "timestamp": "2017-02-13T23:36:10+0100" } ] } } }, "403": { "description": "Returned when the token has no write access to the bucket." }, "404": { "description": "Returned when the bucket is not found in the project (`storage.buckets.notFound`)." } } } }, "/v2/storage/branch/{branchId}/buckets/{bucketId}": { "get": { "tags": [ "Buckets" ], "summary": "Bucket Detail", "description": "Obtains information about a bucket, including its metadata, tables, scheduled tasks, listing and buckets linked to it.", "operationId": "get_/v2/storage/branch/{branchId}/buckets/{bucketId}::BucketDetailAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-ga" }, { "name": "include", "in": "query", "description": "Comma-separated list of resources to include for each table: `metadata` (table metadata), `columns` (table columns), `columnMetadata` (column metadata), `sourceMetadata` (for alias tables, source table metadata in `sourceTable.metadata`; works across projects for linked buckets), `sourceColumnMetadata` (for alias tables, source column metadata in `sourceTable.columnMetadata`).", "required": false, "schema": { "type": "string" }, "example": "columns,metadata" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bucket detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketDetailResponse" }, "example": { "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-ga", "id": "in.c-ga", "name": "c-ga", "displayName": "ga", "idBranch": 1234, "stage": "in", "description": "Google Analytics", "tables": [ { "id": "in.c-ga.sessions", "name": "sessions", "displayName": "sessions" } ], "created": "2017-02-13T12:01:05+0100", "lastChangeDate": "2024-11-28T13:03:13+0100", "updated": "2024-11-28T13:03:13+0100", "isReadOnly": false, "dataSizeBytes": 1536, "rowsCount": 32, "isMaintenance": false, "backend": "snowflake", "sharing": null, "hasExternalSchema": false, "databaseName": null, "path": "database_name.c-ga", "isSnowflakeSharedDatabase": false, "isLinkedBucket": false, "color": null, "bucketSharingAllowed": true, "sharedByActor": null, "owner": { "id": 123, "name": "Jan Developer", "email": "jan.dev@keboola.com" }, "backendPath": [ "KBC_PRJ_123", "in.c-ga" ], "attributes": [], "metadata": [ { "id": "206180828", "key": "KBC.createdBy.component.id", "value": "keboola.ex-db-snowflake", "provider": "user", "timestamp": "2019-08-12T14:36:08+0200" } ], "scheduledTasks": [ { "uuid": "0197e22b-379d-7c62-bc6d-88e50c3d0c75", "job": "bucketRefresh", "relatedEntity": "bucket", "relatedId": "in.c-ga", "cronExpression": "32 16 * * *", "createdAt": "2025-07-14T00:13:00+02:00" } ], "listing": null, "linkedBy": [ { "id": "in.c-linked-bucket", "created": "2017-02-13T12:01:05+0100", "project": { "id": "321", "name": "Some Project" } } ] } } } }, "404": { "description": "The bucket was not found (`storage.buckets.notFound`)." }, "403": { "description": "The token does not have read access to the bucket." } } }, "put": { "tags": [ "Buckets" ], "summary": "Update a bucket", "description": "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.\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 [BucketUpdateJobResult](#model-BucketUpdateJobResult).\n\n Parameters of job will be [BucketUpdateJobParams](#components-schemas-BucketUpdateJobParams).\n\n[Deprecated] This endpoint can be used synchronously as well. In that case, the final result is returned directly in the response [BucketUpdateResponse](#model-BucketUpdateResponse).", "operationId": "put_/v2/storage/branch/{branchId}/buckets/{bucketId}::BucketUpdateAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Identifier of the bucket to update.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" } }, { "name": "async", "in": "query", "description": "When true, the update is performed asynchronously as a job.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateBucketRequest" } ] } } } }, "responses": { "200": { "description": "The updated bucket (synchronous, deprecated).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketUpdateResponse" } } } }, "400": { "description": "The payload is invalid or the display name is already used in the project." }, "403": { "description": "Access to the bucket was denied." }, "404": { "description": "The bucket was not found." }, "503": { "description": "The bucket or its 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/BucketUpdateJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketUpdateJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketUpdateJobParams" } } } }, "delete": { "tags": [ "Buckets" ], "summary": "Drop Bucket", "description": "Deletes a bucket from the project, or unlinks it when it is a linked bucket. In the default mode, only empty buckets can be deleted. Use the optional `force` parameter to delete all bucket content too. With `async=true` the bucket is dropped in a background job (recommended); the synchronous variant is deprecated.\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 [BucketDeleteResponse](#model-BucketDeleteResponse).\n\n Parameters of job will be [BucketDeleteJobParams](#components-schemas-BucketDeleteJobParams).\n\n[Deprecated] This endpoint can be used synchronously as well.", "operationId": "delete_/v2/storage/branch/{branchId}/buckets/{bucketId}::BucketDeleteAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "async", "in": "query", "description": "Drops the bucket in a background job. This is useful if dropping takes too much time and times out.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "force", "in": "query", "description": "Drops all tables and aliases. Tables must not have any dependencies (aliases, etc.).", "required": false, "schema": { "type": "boolean", "default": false }, "example": false }, { "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": { "204": { "description": "The bucket was deleted synchronously (`async=false`, deprecated)." }, "400": { "description": "The bucket is not empty (`buckets.deleteNotEmpty`), is linked in other projects (`storage.buckets.alreadyLinked`), a table has dependent aliases, synchronous delete is disabled (`storage.buckets.syncDeleteDisabled`), or the backend does not support the operation (`storage.driver.unsupportedOperation`)." }, "403": { "description": "Access to the bucket was denied." }, "404": { "description": "The bucket was not found (`storage.buckets.notFound`)." }, "409": { "description": "A workspace of the project held its direct-grant lock for the whole wait budget, so the grants on the bucket could not be revoked (`storage.workspace.lockFailedToAcquire`), or another exposure job of the bucket ran for the whole wait (`storage.bucketListing.locked`). Nothing was deleted; retry." }, "501": { "description": "Deleting a linked bucket is not supported in a development branch (`storage.buckets.linkedBucketDeleteNotSupportedInDevBranch`)." }, "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/BucketDeleteResponse" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketDeleteResponse" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketDeleteJobParams" } } } } }, "/v2/storage/buckets/{bucketId}": { "get": { "tags": [ "Buckets" ], "summary": "Bucket Detail", "description": "Obtains information about a bucket, including its metadata, tables, scheduled tasks, listing and buckets linked to it.", "operationId": "get_/v2/storage/buckets/{bucketId}::BucketDetailAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-ga" }, { "name": "include", "in": "query", "description": "Comma-separated list of resources to include for each table: `metadata` (table metadata), `columns` (table columns), `columnMetadata` (column metadata), `sourceMetadata` (for alias tables, source table metadata in `sourceTable.metadata`; works across projects for linked buckets), `sourceColumnMetadata` (for alias tables, source column metadata in `sourceTable.columnMetadata`).", "required": false, "schema": { "type": "string" }, "example": "columns,metadata" } ], "responses": { "200": { "description": "Bucket detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketDetailResponse" }, "example": { "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-ga", "id": "in.c-ga", "name": "c-ga", "displayName": "ga", "idBranch": 1234, "stage": "in", "description": "Google Analytics", "tables": [ { "id": "in.c-ga.sessions", "name": "sessions", "displayName": "sessions" } ], "created": "2017-02-13T12:01:05+0100", "lastChangeDate": "2024-11-28T13:03:13+0100", "updated": "2024-11-28T13:03:13+0100", "isReadOnly": false, "dataSizeBytes": 1536, "rowsCount": 32, "isMaintenance": false, "backend": "snowflake", "sharing": null, "hasExternalSchema": false, "databaseName": null, "path": "database_name.c-ga", "isSnowflakeSharedDatabase": false, "isLinkedBucket": false, "color": null, "bucketSharingAllowed": true, "sharedByActor": null, "owner": { "id": 123, "name": "Jan Developer", "email": "jan.dev@keboola.com" }, "backendPath": [ "KBC_PRJ_123", "in.c-ga" ], "attributes": [], "metadata": [ { "id": "206180828", "key": "KBC.createdBy.component.id", "value": "keboola.ex-db-snowflake", "provider": "user", "timestamp": "2019-08-12T14:36:08+0200" } ], "scheduledTasks": [ { "uuid": "0197e22b-379d-7c62-bc6d-88e50c3d0c75", "job": "bucketRefresh", "relatedEntity": "bucket", "relatedId": "in.c-ga", "cronExpression": "32 16 * * *", "createdAt": "2025-07-14T00:13:00+02:00" } ], "listing": null, "linkedBy": [ { "id": "in.c-linked-bucket", "created": "2017-02-13T12:01:05+0100", "project": { "id": "321", "name": "Some Project" } } ] } } } }, "404": { "description": "The bucket was not found (`storage.buckets.notFound`)." }, "403": { "description": "The token does not have read access to the bucket." } } }, "put": { "tags": [ "Buckets" ], "summary": "Update a bucket", "description": "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.\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 [BucketUpdateJobResult](#model-BucketUpdateJobResult).\n\n Parameters of job will be [BucketUpdateJobParams](#components-schemas-BucketUpdateJobParams).\n\n[Deprecated] This endpoint can be used synchronously as well. In that case, the final result is returned directly in the response [BucketUpdateResponse](#model-BucketUpdateResponse).", "operationId": "put_/v2/storage/buckets/{bucketId}::BucketUpdateAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Identifier of the bucket to update.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" } }, { "name": "async", "in": "query", "description": "When true, the update is performed asynchronously as a job.", "required": false, "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateBucketRequest" } ] } } } }, "responses": { "200": { "description": "The updated bucket (synchronous, deprecated).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketUpdateResponse" } } } }, "400": { "description": "The payload is invalid or the display name is already used in the project." }, "403": { "description": "Access to the bucket was denied." }, "404": { "description": "The bucket was not found." }, "503": { "description": "The bucket or its 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/BucketUpdateJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketUpdateJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketUpdateJobParams" } } } }, "delete": { "tags": [ "Buckets" ], "summary": "Drop Bucket", "description": "Deletes a bucket from the project, or unlinks it when it is a linked bucket. In the default mode, only empty buckets can be deleted. Use the optional `force` parameter to delete all bucket content too. With `async=true` the bucket is dropped in a background job (recommended); the synchronous variant is deprecated.\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 [BucketDeleteResponse](#model-BucketDeleteResponse).\n\n Parameters of job will be [BucketDeleteJobParams](#components-schemas-BucketDeleteJobParams).\n\n[Deprecated] This endpoint can be used synchronously as well.", "operationId": "delete_/v2/storage/buckets/{bucketId}::BucketDeleteAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "async", "in": "query", "description": "Drops the bucket in a background job. This is useful if dropping takes too much time and times out.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "force", "in": "query", "description": "Drops all tables and aliases. Tables must not have any dependencies (aliases, etc.).", "required": false, "schema": { "type": "boolean", "default": false }, "example": false }, { "name": "X-KBC-Backend", "in": "header", "schema": { "schema": "BackendConfigurationRequest", "properties": { "context": { "type": "string", "nullable": true, "minLength": 1 } }, "type": "object" } } ], "responses": { "204": { "description": "The bucket was deleted synchronously (`async=false`, deprecated)." }, "400": { "description": "The bucket is not empty (`buckets.deleteNotEmpty`), is linked in other projects (`storage.buckets.alreadyLinked`), a table has dependent aliases, synchronous delete is disabled (`storage.buckets.syncDeleteDisabled`), or the backend does not support the operation (`storage.driver.unsupportedOperation`)." }, "403": { "description": "Access to the bucket was denied." }, "404": { "description": "The bucket was not found (`storage.buckets.notFound`)." }, "409": { "description": "A workspace of the project held its direct-grant lock for the whole wait budget, so the grants on the bucket could not be revoked (`storage.workspace.lockFailedToAcquire`), or another exposure job of the bucket ran for the whole wait (`storage.bucketListing.locked`). Nothing was deleted; retry." }, "501": { "description": "Deleting a linked bucket is not supported in a development branch (`storage.buckets.linkedBucketDeleteNotSupportedInDevBranch`)." }, "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/BucketDeleteResponse" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketDeleteResponse" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketDeleteJobParams" } } } } }, "/v2/storage/branch/{branchId}/buckets/{bucketId}/metadata/{metadataId}": { "delete": { "tags": [ "Metadata" ], "summary": "Delete bucket metadata", "description": "Deletes the specified metadata item from the bucket.", "operationId": "delete_/v2/storage/branch/{branchId}/buckets/{bucketId}/metadata/{metadataId}::BucketDeleteMetadataAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Id of the bucket.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "metadataId", "in": "path", "description": "Id of the metadata.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 19509 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Metadata item deleted." }, "403": { "description": "Returned when the token has no write access to the bucket." }, "404": { "description": "Returned when the bucket (`storage.buckets.notFound`) or the metadata item (`storage.metadata.notFound`) is not found." } } } }, "/v2/storage/buckets/{bucketId}/metadata/{metadataId}": { "delete": { "tags": [ "Metadata" ], "summary": "Delete bucket metadata", "description": "Deletes the specified metadata item from the bucket.", "operationId": "delete_/v2/storage/buckets/{bucketId}/metadata/{metadataId}::BucketDeleteMetadataAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Id of the bucket.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "metadataId", "in": "path", "description": "Id of the metadata.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 19509 } ], "responses": { "204": { "description": "Metadata item deleted." }, "403": { "description": "Returned when the token has no write access to the bucket." }, "404": { "description": "Returned when the bucket (`storage.buckets.notFound`) or the metadata item (`storage.metadata.notFound`) is not found." } } } }, "/v2/storage/branch/{branchId}/buckets/{bucketId}/events": { "get": { "tags": [ "Buckets" ], "summary": "List events for a bucket", "description": "Returns a list of events for the specified bucket.", "operationId": "get_/v2/storage/branch/{branchId}/buckets/{bucketId}/events::BucketEventsListAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Identifier of the bucket to list events for.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" } }, { "name": "limit", "in": "query", "description": "Maximum number of events to return", "required": false, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of events to skip", "required": false, "schema": { "type": "integer" } }, { "name": "maxId", "in": "query", "description": "Only include events with ID less than or equal to this value", "required": false, "schema": { "type": "string" } }, { "name": "sinceId", "in": "query", "description": "Only include events with ID greater than this value", "required": false, "schema": { "type": "string" } }, { "name": "component", "in": "query", "description": "Filter events by component", "required": false, "schema": { "type": "string" } }, { "name": "configurationId", "in": "query", "description": "Filter events by configuration ID", "required": false, "schema": { "type": "string" } }, { "name": "runId", "in": "query", "description": "Filter events by run ID", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Full-text search query to filter event data", "required": false, "schema": { "type": "string" } }, { "name": "query", "in": "query", "description": "Deprecated alias of the q parameter.", "required": false, "deprecated": true, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Sort order of events. Use \"asc\" for oldest first or \"desc\" for newest first.", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bucket events list response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketEventsListResponse" } } } }, "400": { "description": "Returned when the provided events filter parameters are invalid." }, "403": { "description": "Access denied to the bucket." }, "404": { "description": "Returned when the bucket is not found." }, "503": { "description": "Bucket or its backend connection is under maintenance." } } } }, "/v2/storage/buckets/{bucketId}/events": { "get": { "tags": [ "Buckets" ], "summary": "List events for a bucket", "description": "Returns a list of events for the specified bucket.", "operationId": "get_/v2/storage/buckets/{bucketId}/events::BucketEventsListAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Identifier of the bucket to list events for.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" } }, { "name": "limit", "in": "query", "description": "Maximum number of events to return", "required": false, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of events to skip", "required": false, "schema": { "type": "integer" } }, { "name": "maxId", "in": "query", "description": "Only include events with ID less than or equal to this value", "required": false, "schema": { "type": "string" } }, { "name": "sinceId", "in": "query", "description": "Only include events with ID greater than this value", "required": false, "schema": { "type": "string" } }, { "name": "component", "in": "query", "description": "Filter events by component", "required": false, "schema": { "type": "string" } }, { "name": "configurationId", "in": "query", "description": "Filter events by configuration ID", "required": false, "schema": { "type": "string" } }, { "name": "runId", "in": "query", "description": "Filter events by run ID", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Full-text search query to filter event data", "required": false, "schema": { "type": "string" } }, { "name": "query", "in": "query", "description": "Deprecated alias of the q parameter.", "required": false, "deprecated": true, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Sort order of events. Use \"asc\" for oldest first or \"desc\" for newest first.", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Bucket events list response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketEventsListResponse" } } } }, "400": { "description": "Returned when the provided events filter parameters are invalid." }, "403": { "description": "Access denied to the bucket." }, "404": { "description": "Returned when the bucket is not found." }, "503": { "description": "Bucket or its backend connection is under maintenance." } } } }, "/v2/storage/branch/{branchId}/buckets/{bucketId}/links/{linkedProjectId}": { "delete": { "tags": [ "Buckets" ], "summary": "Force unlink a bucket from a project", "description": "When a bucket is shared and someone links it, it effectively prevents the owner of the data from revoking the share. When the user of the linked bucket is not responding it's a blocker. Force unlink allows you to unlink a bucket from any project it's linked to, solving the situation. The call is made from the source (sharing) project.\n\n**Note:** You may break some workflows in the project that linked the data by force unlinking the bucket.\n\nThe unlink always runs as a background job (the synchronous variant is not available).\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 [BucketForceUnlinkJobResult](#model-BucketForceUnlinkJobResult).\n\n Parameters of job will be [BucketForceUnlinkJobParams](#components-schemas-BucketForceUnlinkJobParams).", "operationId": "delete_/v2/storage/branch/{branchId}/buckets/{bucketId}/links/{linkedProjectId}::BucketForceUnlinkAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "ID of the shared source bucket.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "linkedProjectId", "in": "path", "description": "ID of the project where the bucket is linked.", "required": true, "schema": { "type": "integer", "pattern": "[^/]+" }, "example": 321 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "The bucket is not linked into the given project (`storage.buckets.linkedBucketNotFound`), or the project id is not a digits-only value (`storage.buckets.validation`)." }, "403": { "description": "Access to the bucket was denied (`accessDenied`)." }, "404": { "description": "The bucket was not found (`storage.buckets.notFound`)." }, "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/BucketForceUnlinkJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketForceUnlinkJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketForceUnlinkJobParams" } } } } }, "/v2/storage/buckets/{bucketId}/links/{linkedProjectId}": { "delete": { "tags": [ "Buckets" ], "summary": "Force unlink a bucket from a project", "description": "When a bucket is shared and someone links it, it effectively prevents the owner of the data from revoking the share. When the user of the linked bucket is not responding it's a blocker. Force unlink allows you to unlink a bucket from any project it's linked to, solving the situation. The call is made from the source (sharing) project.\n\n**Note:** You may break some workflows in the project that linked the data by force unlinking the bucket.\n\nThe unlink always runs as a background job (the synchronous variant is not available).\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 [BucketForceUnlinkJobResult](#model-BucketForceUnlinkJobResult).\n\n Parameters of job will be [BucketForceUnlinkJobParams](#components-schemas-BucketForceUnlinkJobParams).", "operationId": "delete_/v2/storage/buckets/{bucketId}/links/{linkedProjectId}::BucketForceUnlinkAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "ID of the shared source bucket.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "linkedProjectId", "in": "path", "description": "ID of the project where the bucket is linked.", "required": true, "schema": { "type": "integer", "pattern": "[^/]+" }, "example": 321 } ], "responses": { "400": { "description": "The bucket is not linked into the given project (`storage.buckets.linkedBucketNotFound`), or the project id is not a digits-only value (`storage.buckets.validation`)." }, "403": { "description": "Access to the bucket was denied (`accessDenied`)." }, "404": { "description": "The bucket was not found (`storage.buckets.notFound`)." }, "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/BucketForceUnlinkJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketForceUnlinkJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketForceUnlinkJobParams" } } } } }, "/v2/storage/branch/{branchId}/buckets/{bucketId}/tables": { "get": { "tags": [ "Tables" ], "summary": "Tables in bucket", "description": "Lists tables in a given bucket. By default each table is returned with its attributes and metadata;\nuse the `include` query parameter to add columns, column metadata or (for aliases) source table metadata.", "operationId": "get_/v2/storage/branch/{branchId}/buckets/{bucketId}/tables::BucketGetTablesAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket string id (e.g. `in.c-main`).", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "include", "in": "query", "description": "Comma-separated list of resources to include for each table: `columns`, `metadata`, `columnMetadata`, `sourceMetadata` (alias tables: source table metadata in `sourceTable.metadata`, works across projects for linked buckets), `sourceColumnMetadata` (alias tables: source column metadata in `sourceTable.columnMetadata`). Also accepted: `attributes`, `buckets`, `bucketsWithoutSourceTables`. Default: `attributes,metadata`; an empty value returns no extra data.", "required": false, "schema": { "type": "string" }, "example": "columns,metadata,columnMetadata" }, { "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": { "$ref": "#/components/schemas/TableListItemResponse" } }, "example": [ { "uri": "https://connection.keboola.com/v2/storage/tables/in.c-keboola-ex-db-snowflake-528221294.datatypes", "id": "in.c-keboola-ex-db-snowflake-528221294.datatypes", "name": "datatypes", "displayName": "datatypes", "transactional": false, "primaryKey": [], "indexType": null, "indexKey": [], "distributionType": null, "distributionKey": [], "syntheticPrimaryKeyEnabled": false, "created": "2019-08-12T14:36:00+0200", "lastImportDate": "2019-08-12T21:16:41+0200", "lastChangeDate": "2019-08-12T21:16:41+0200", "rowsCount": 2, "dataSizeBytes": 1024, "isAlias": false, "isAliasable": true, "isTyped": false, "isDescriptionSystemManaged": false, "timestampType": "MANAGED", "tableType": "table", "path": "kbc.c-keboola-ex-db-snowflake-528221294.datatypes", "metadata": [ { "id": "206180828", "key": "KBC.createdBy.component.id", "value": "keboola.ex-db-snowflake", "provider": "system", "timestamp": "2019-08-12T14:36:08+0200" } ], "columnMetadata": { "ID": [ { "id": "206180838", "key": "KBC.datatype.type", "value": "NUMBER", "provider": "keboola.ex-db-snowflake", "timestamp": "2019-08-12T14:36:17+0200" } ] } } ] } } }, "404": { "description": "Bucket not found (`storage.buckets.notFound`)." }, "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." } } }, "post": { "tags": [ "Tables" ], "summary": "Create new table from CSV file", "description": "**DEPRECATED**, use [Create table asynchronously](#operation/post_/v2/storage/buckets/{id}/tables-async) instead.\n\nCreates a new table in a bucket. The CSV file must follow the [RFC 4180 Specification](https://tools.ietf.org/html/rfc4180).\nMore information about the requirements can be found in the [Manual](https://help.keboola.com/storage/tables/csv-files/).\nColumn names are extracted from the CSV file header; spaces and any other special characters in column names are\nreplaced with an underscore. This API call should be used only for tables which can be safely transferred in a single HTTP request; for large\ntables use the asynchronous call.\n\nThe table data must be supplied through exactly one of `data` (file upload) or `dataString` (inline CSV).", "operationId": "post_/v2/storage/branch/{branchId}/buckets/{bucketId}/tables::CreateTableSyncAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket Id.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "New table name.", "type": "string", "example": "my_table_name", "allOf": [ { "$ref": "#/components/schemas/StorageName" } ] }, "data": { "description": "CSV file containing data for import. The data have to be encoded in UTF-8. The file can be raw or gzipped; gzipped files must have the extension `.gz`. Required unless `dataString` is provided.", "type": "string", "format": "binary" }, "dataString": { "description": "Inline CSV data. Used when no `data` file is uploaded.", "type": "string" }, "primaryKey": { "description": "Primary key of the table. If set, updates can be done on the table (see CSV incremental import). Multiple columns must be separated by a comma.", "type": "string", "example": "id" }, "delimiter": { "description": "Field delimiter used in the CSV file. Default `,`. Use '\\t' or type the char for the tabulator.", "type": "string", "example": "," }, "enclosure": { "description": "Field enclosure used in the CSV file. Default `\"`. Specify either `enclosure` or `escapedBy`, not both.", "type": "string", "example": "\"" }, "escapedBy": { "description": "Escape character used in the CSV file. Default empty - no escape character is used. Specify either `enclosure` or `escapedBy`, not both.", "type": "string" }, "columns": { "description": "Comma separated list of column names, used when the file has no header.", "type": "string" }, "withoutHeaders": { "description": "When true, the first row is treated as data, not as a header.", "type": "boolean" } }, "type": "object" } } } }, "responses": { "201": { "description": "The created table detail, including its columns and the parent bucket detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTableSyncResponse" }, "example": { "uri": "https://connection.keboola.com/v2/storage/tables/in.c-main.languages", "id": "in.c-main.languages", "name": "languages", "displayName": "languages", "transactional": false, "primaryKey": [], "indexType": null, "indexKey": [], "distributionType": null, "distributionKey": [], "syntheticPrimaryKeyEnabled": false, "created": "2012-07-23T09:51:45+0200", "lastImportDate": null, "lastChangeDate": null, "rowsCount": 0, "dataSizeBytes": 0, "isAlias": false, "isAliasable": true, "isTyped": false, "tableType": "table", "path": "languages", "columns": [ "id", "name_id", "nm_id" ], "bucket": { "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-main", "id": "in.c-main", "name": "c-main", "displayName": "main", "stage": "in", "description": "Main user storage", "tables": "https://connection.keboola.com/v2/storage/buckets/in.c-main" } } } } }, "400": { "description": "Validation error in the upload, CSV, table definition or import (e.g. `storage.tables.validation.*`, `storage.validation.*`)." }, "403": { "description": "Write access to the bucket was denied." }, "404": { "description": "The bucket was not found (`storage.buckets.notFound`), or synchronous import is disabled on this stack." }, "503": { "description": "The bucket or its backend connection is under maintenance (`storage.buckets.maintenance`, `storage.backend.maintenance`)." } } } }, "/v2/storage/buckets/{bucketId}/tables": { "get": { "tags": [ "Tables" ], "summary": "Tables in bucket", "description": "Lists tables in a given bucket. By default each table is returned with its attributes and metadata;\nuse the `include` query parameter to add columns, column metadata or (for aliases) source table metadata.", "operationId": "get_/v2/storage/buckets/{bucketId}/tables::BucketGetTablesAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket string id (e.g. `in.c-main`).", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "include", "in": "query", "description": "Comma-separated list of resources to include for each table: `columns`, `metadata`, `columnMetadata`, `sourceMetadata` (alias tables: source table metadata in `sourceTable.metadata`, works across projects for linked buckets), `sourceColumnMetadata` (alias tables: source column metadata in `sourceTable.columnMetadata`). Also accepted: `attributes`, `buckets`, `bucketsWithoutSourceTables`. Default: `attributes,metadata`; an empty value returns no extra data.", "required": false, "schema": { "type": "string" }, "example": "columns,metadata,columnMetadata" } ], "responses": { "200": { "description": "List of tables in the bucket.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TableListItemResponse" } }, "example": [ { "uri": "https://connection.keboola.com/v2/storage/tables/in.c-keboola-ex-db-snowflake-528221294.datatypes", "id": "in.c-keboola-ex-db-snowflake-528221294.datatypes", "name": "datatypes", "displayName": "datatypes", "transactional": false, "primaryKey": [], "indexType": null, "indexKey": [], "distributionType": null, "distributionKey": [], "syntheticPrimaryKeyEnabled": false, "created": "2019-08-12T14:36:00+0200", "lastImportDate": "2019-08-12T21:16:41+0200", "lastChangeDate": "2019-08-12T21:16:41+0200", "rowsCount": 2, "dataSizeBytes": 1024, "isAlias": false, "isAliasable": true, "isTyped": false, "isDescriptionSystemManaged": false, "timestampType": "MANAGED", "tableType": "table", "path": "kbc.c-keboola-ex-db-snowflake-528221294.datatypes", "metadata": [ { "id": "206180828", "key": "KBC.createdBy.component.id", "value": "keboola.ex-db-snowflake", "provider": "system", "timestamp": "2019-08-12T14:36:08+0200" } ], "columnMetadata": { "ID": [ { "id": "206180838", "key": "KBC.datatype.type", "value": "NUMBER", "provider": "keboola.ex-db-snowflake", "timestamp": "2019-08-12T14:36:17+0200" } ] } } ] } } }, "404": { "description": "Bucket not found (`storage.buckets.notFound`)." }, "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." } } }, "post": { "tags": [ "Tables" ], "summary": "Create new table from CSV file", "description": "**DEPRECATED**, use [Create table asynchronously](#operation/post_/v2/storage/buckets/{id}/tables-async) instead.\n\nCreates a new table in a bucket. The CSV file must follow the [RFC 4180 Specification](https://tools.ietf.org/html/rfc4180).\nMore information about the requirements can be found in the [Manual](https://help.keboola.com/storage/tables/csv-files/).\nColumn names are extracted from the CSV file header; spaces and any other special characters in column names are\nreplaced with an underscore. This API call should be used only for tables which can be safely transferred in a single HTTP request; for large\ntables use the asynchronous call.\n\nThe table data must be supplied through exactly one of `data` (file upload) or `dataString` (inline CSV).", "operationId": "post_/v2/storage/buckets/{bucketId}/tables::CreateTableSyncAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket Id.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "New table name.", "type": "string", "example": "my_table_name", "allOf": [ { "$ref": "#/components/schemas/StorageName" } ] }, "data": { "description": "CSV file containing data for import. The data have to be encoded in UTF-8. The file can be raw or gzipped; gzipped files must have the extension `.gz`. Required unless `dataString` is provided.", "type": "string", "format": "binary" }, "dataString": { "description": "Inline CSV data. Used when no `data` file is uploaded.", "type": "string" }, "primaryKey": { "description": "Primary key of the table. If set, updates can be done on the table (see CSV incremental import). Multiple columns must be separated by a comma.", "type": "string", "example": "id" }, "delimiter": { "description": "Field delimiter used in the CSV file. Default `,`. Use '\\t' or type the char for the tabulator.", "type": "string", "example": "," }, "enclosure": { "description": "Field enclosure used in the CSV file. Default `\"`. Specify either `enclosure` or `escapedBy`, not both.", "type": "string", "example": "\"" }, "escapedBy": { "description": "Escape character used in the CSV file. Default empty - no escape character is used. Specify either `enclosure` or `escapedBy`, not both.", "type": "string" }, "columns": { "description": "Comma separated list of column names, used when the file has no header.", "type": "string" }, "withoutHeaders": { "description": "When true, the first row is treated as data, not as a header.", "type": "boolean" } }, "type": "object" } } } }, "responses": { "201": { "description": "The created table detail, including its columns and the parent bucket detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTableSyncResponse" }, "example": { "uri": "https://connection.keboola.com/v2/storage/tables/in.c-main.languages", "id": "in.c-main.languages", "name": "languages", "displayName": "languages", "transactional": false, "primaryKey": [], "indexType": null, "indexKey": [], "distributionType": null, "distributionKey": [], "syntheticPrimaryKeyEnabled": false, "created": "2012-07-23T09:51:45+0200", "lastImportDate": null, "lastChangeDate": null, "rowsCount": 0, "dataSizeBytes": 0, "isAlias": false, "isAliasable": true, "isTyped": false, "tableType": "table", "path": "languages", "columns": [ "id", "name_id", "nm_id" ], "bucket": { "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-main", "id": "in.c-main", "name": "c-main", "displayName": "main", "stage": "in", "description": "Main user storage", "tables": "https://connection.keboola.com/v2/storage/buckets/in.c-main" } } } } }, "400": { "description": "Validation error in the upload, CSV, table definition or import (e.g. `storage.tables.validation.*`, `storage.validation.*`)." }, "403": { "description": "Write access to the bucket was denied." }, "404": { "description": "The bucket was not found (`storage.buckets.notFound`), or synchronous import is disabled on this stack." }, "503": { "description": "The bucket or its backend connection is under maintenance (`storage.buckets.maintenance`, `storage.backend.maintenance`)." } } } }, "/v2/storage/branch/{branchId}/buckets/{bucketId}/owner": { "get": { "tags": [ "Buckets" ], "summary": "Bucket Owner detail", "description": "Return information about the current bucket owner.", "operationId": "get_/v2/storage/branch/{branchId}/buckets/{bucketId}/owner::BucketOwnerDetailAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bucket owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketOwnerDetailResponse" }, "example": { "id": 123, "name": "Dev", "email": "dev@keboola.com" } } } }, "403": { "description": "The token does not have read access to the bucket." }, "404": { "description": "The bucket was not found (`storage.buckets.notFound`) or the bucket has no owner (`storage.bucket.ownerNotFound`)." } } }, "post": { "tags": [ "Buckets" ], "summary": "Bucket Owner update", "description": "Update the bucket owner. Identify the new owner by project admin `id` or `email`; exactly one of them is required.", "operationId": "post_/v2/storage/branch/{branchId}/buckets/{bucketId}/owner::BucketOwnerUpdateAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BucketOwnerUpdateRequest" } ] } } } }, "responses": { "204": { "description": "Bucket owner updated." }, "400": { "description": "Neither or both of `id` and `email` were provided, or the email is invalid." }, "404": { "description": "The bucket was not found (`storage.buckets.notFound`) or the specified admin is not a member of the project (`storage.bucket.ownerNotFound`)." } } } }, "/v2/storage/buckets/{bucketId}/owner": { "get": { "tags": [ "Buckets" ], "summary": "Bucket Owner detail", "description": "Return information about the current bucket owner.", "operationId": "get_/v2/storage/buckets/{bucketId}/owner::BucketOwnerDetailAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" } ], "responses": { "200": { "description": "Bucket owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketOwnerDetailResponse" }, "example": { "id": 123, "name": "Dev", "email": "dev@keboola.com" } } } }, "403": { "description": "The token does not have read access to the bucket." }, "404": { "description": "The bucket was not found (`storage.buckets.notFound`) or the bucket has no owner (`storage.bucket.ownerNotFound`)." } } }, "post": { "tags": [ "Buckets" ], "summary": "Bucket Owner update", "description": "Update the bucket owner. Identify the new owner by project admin `id` or `email`; exactly one of them is required.", "operationId": "post_/v2/storage/buckets/{bucketId}/owner::BucketOwnerUpdateAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BucketOwnerUpdateRequest" } ] } } } }, "responses": { "204": { "description": "Bucket owner updated." }, "400": { "description": "Neither or both of `id` and `email` were provided, or the email is invalid." }, "404": { "description": "The bucket was not found (`storage.buckets.notFound`) or the specified admin is not a member of the project (`storage.bucket.ownerNotFound`)." } } } }, "/v2/storage/branch/{branchId}/buckets/{bucketId}/table-aliases": { "post": { "tags": [ "Buckets" ], "summary": "Create a table alias in a bucket", "description": "Creates an alias table in the given bucket over a table from another bucket. The alias can\nexpose a subset of the source columns and can be restricted by a filter. On backends that\nkeep a persisted VIEW for aliases the work is delegated to an asynchronous job, otherwise the\nalias is created directly and returned with 201.\n\nAn alias cannot be created from a table that lives in an external bucket or in a development\nbranch. Additionally, the destination bucket itself cannot be an external bucket or a\ndevelopment branch bucket.\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 [AliasCreateJobResult](#model-AliasCreateJobResult).\n\n Parameters of job will be [AliasCreateJobParams](#components-schemas-AliasCreateJobParams).\n\n This endpoint can be used synchronously as well. In that case, the final result is returned directly in the response [CreateTableAliasResponse](#model-CreateTableAliasResponse).", "operationId": "post_/v2/storage/branch/{branchId}/buckets/{bucketId}/table-aliases::CreateTableAliasAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Identifier of the bucket the alias is created in.", "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/CreateTableAliasRequest" } ] } } } }, "responses": { "201": { "description": "The created alias detail, including its columns and the destination bucket detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTableAliasResponse" } } } }, "400": { "description": "The alias cannot be created - invalid request body, an external bucket on either side, a bucket in a development branch, a filter the source table does not support, or a source that reads a linked or external bucket while the destination bucket is exposed on Snowflake (`storage.tables.aliasSourceOutsideProjectInExposedBucket`)." }, "403": { "description": "Write access to the destination bucket or read access to the source bucket was denied." }, "404": { "description": "The destination bucket, the source bucket or the source table was not found." }, "503": { "description": "The destination bucket or its 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/AliasCreateJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/AliasCreateJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/AliasCreateJobParams" } } } } }, "/v2/storage/buckets/{bucketId}/table-aliases": { "post": { "tags": [ "Buckets" ], "summary": "Create a table alias in a bucket", "description": "Creates an alias table in the given bucket over a table from another bucket. The alias can\nexpose a subset of the source columns and can be restricted by a filter. On backends that\nkeep a persisted VIEW for aliases the work is delegated to an asynchronous job, otherwise the\nalias is created directly and returned with 201.\n\nAn alias cannot be created from a table that lives in an external bucket or in a development\nbranch. Additionally, the destination bucket itself cannot be an external bucket or a\ndevelopment branch bucket.\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 [AliasCreateJobResult](#model-AliasCreateJobResult).\n\n Parameters of job will be [AliasCreateJobParams](#components-schemas-AliasCreateJobParams).\n\n This endpoint can be used synchronously as well. In that case, the final result is returned directly in the response [CreateTableAliasResponse](#model-CreateTableAliasResponse).", "operationId": "post_/v2/storage/buckets/{bucketId}/table-aliases::CreateTableAliasAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Identifier of the bucket the alias is created in.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateTableAliasRequest" } ] } } } }, "responses": { "201": { "description": "The created alias detail, including its columns and the destination bucket detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTableAliasResponse" } } } }, "400": { "description": "The alias cannot be created - invalid request body, an external bucket on either side, a bucket in a development branch, a filter the source table does not support, or a source that reads a linked or external bucket while the destination bucket is exposed on Snowflake (`storage.tables.aliasSourceOutsideProjectInExposedBucket`)." }, "403": { "description": "Write access to the destination bucket or read access to the source bucket was denied." }, "404": { "description": "The destination bucket, the source bucket or the source table was not found." }, "503": { "description": "The destination bucket or its 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/AliasCreateJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/AliasCreateJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/AliasCreateJobParams" } } } } }, "/v2/storage/branch/{branchId}/buckets/{id}/tables-async": { "post": { "tags": [ "Tables" ], "summary": "Create new table asynchronously", "description": "Creates a new table in a bucket from one of the supported sources. The method of creating a table asynchronously should be used for larger imports (everything with 100 lines and more).\nThe create request is created and added to a queue, the job resource url for status polling is returned.\n\nThe source is selected by the request body:\n- **CSV file** \u2013 `dataFileId` of a file stored in [File Uploads](#tag/Files).\n- **Snapshot** \u2013 `snapshotId` of a table snapshot; the table is created from the snapshot.\n- **Workspace** \u2013 `dataWorkspaceId` together with `dataObject` (older `dataTableName` is deprecated). Load from a table or file in the [workspace](#tag/Workspaces).\n- **Time travel** \u2013 `sourceTableId` and `timestamp` (`YYYY-MM-DD hh:mm:ss Z`; time zone is required). Supported by Snowflake and BigQuery; BigQuery doesn't support primary keys, so the new table won't get primary keys.\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 [TableCreateJobParams](#components-schemas-TableCreateJobParams).", "operationId": "post_/v2/storage/branch/{branchId}/buckets/{id}/tables-async::CreateTableAsyncAction", "parameters": [ { "name": "id", "in": "path", "description": "The bucket Id.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main" }, { "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": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateTableAsyncFromFileRequest" }, { "$ref": "#/components/schemas/CreateTableAsyncFromSnapshotRequest" }, { "$ref": "#/components/schemas/CreateTableAsyncFromTimeTravelRequest" }, { "$ref": "#/components/schemas/CreateTableAsyncFromWorkspaceRequest" } ] } } } }, "responses": { "400": { "description": "Validation error, the table already exists, the backend does not support the operation (`storage.driver.unsupportedOperation`), time travel is not available, or the source workspace is deactivated (`workspace.workspaceDeactivated`)." }, "403": { "description": "Access denied to the bucket, the source file or the snapshot." }, "404": { "description": "Bucket (`storage.buckets.notFound`), source table, source file or snapshot 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/TableCreateResponse" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/TableCreateResponse" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/TableCreateJobParams" } } } } }, "/v2/storage/buckets/{id}/tables-async": { "post": { "tags": [ "Tables" ], "summary": "Create new table asynchronously", "description": "Creates a new table in a bucket from one of the supported sources. The method of creating a table asynchronously should be used for larger imports (everything with 100 lines and more).\nThe create request is created and added to a queue, the job resource url for status polling is returned.\n\nThe source is selected by the request body:\n- **CSV file** \u2013 `dataFileId` of a file stored in [File Uploads](#tag/Files).\n- **Snapshot** \u2013 `snapshotId` of a table snapshot; the table is created from the snapshot.\n- **Workspace** \u2013 `dataWorkspaceId` together with `dataObject` (older `dataTableName` is deprecated). Load from a table or file in the [workspace](#tag/Workspaces).\n- **Time travel** \u2013 `sourceTableId` and `timestamp` (`YYYY-MM-DD hh:mm:ss Z`; time zone is required). Supported by Snowflake and BigQuery; BigQuery doesn't support primary keys, so the new table won't get primary keys.\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 [TableCreateJobParams](#components-schemas-TableCreateJobParams).", "operationId": "post_/v2/storage/buckets/{id}/tables-async::CreateTableAsyncAction", "parameters": [ { "name": "id", "in": "path", "description": "The bucket Id.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main" }, { "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": { "400": { "description": "Validation error, the table already exists, the backend does not support the operation (`storage.driver.unsupportedOperation`), time travel is not available, or the source workspace is deactivated (`workspace.workspaceDeactivated`)." }, "403": { "description": "Access denied to the bucket, the source file or the snapshot." }, "404": { "description": "Bucket (`storage.buckets.notFound`), source table, source file or snapshot 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/TableCreateResponse" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/TableCreateResponse" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/TableCreateJobParams" } } } } }, "/v2/storage/branch/{branchId}/buckets/{bucketId}/tables-definition": { "post": { "tags": [ "Tables" ], "summary": "Create new table definition", "description": "Creates a table with typed columns. *Snowflake|BigQuery only.*\n\nRequest is handled asynchronously which means that the create request is created and added to a queue and the job resource URL for status polling is returned.\n\nIf there is no column datatype specified (`column.definition.type` or `column.basetype`) in a request a table will be created as a non-typed table.\n\nThe request payload is backend specific: `timePartitioning`, `rangePartitioning` and `clustering` are BigQuery only ([documentation](https://cloud.google.com/bigquery/docs/reference/rest/v2/tables)). Buckets on other backends are rejected.\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 [TableDefinitionCreateJobParams](#components-schemas-TableDefinitionCreateJobParams).", "operationId": "post_/v2/storage/branch/{branchId}/buckets/{bucketId}/tables-definition::CreateTableDefinitionAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "The bucket Id.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main" }, { "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": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SnowflakeCreateTableDefinitionRequest" }, { "$ref": "#/components/schemas/BigqueryCreateTableDefinitionRequest" } ] } } } }, "responses": { "400": { "description": "Validation error (including supplying `columns` together with `source`), or table definition is not supported for the bucket backend (`storage.driver.unsupportedOperation`)." }, "403": { "description": "Access denied to the bucket." }, "404": { "description": "Bucket not found (`storage.buckets.notFound`), or the supplied source table was not found in the project." }, "422": { "description": "`source` rejected: the bucket backend does not support creating a table from a source, the source is a non-persisted alias, or a referenced column (primary key, partitioning or clustering field) is not present in the source table." }, "503": { "description": "The bucket or its backend connection is under maintenance (`storage.buckets.maintenance`, `storage.backend.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/TableCreateResponse" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/TableCreateResponse" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/TableDefinitionCreateJobParams" } } } } }, "/v2/storage/buckets/{bucketId}/tables-definition": { "post": { "tags": [ "Tables" ], "summary": "Create new table definition", "description": "Creates a table with typed columns. *Snowflake|BigQuery only.*\n\nRequest is handled asynchronously which means that the create request is created and added to a queue and the job resource URL for status polling is returned.\n\nIf there is no column datatype specified (`column.definition.type` or `column.basetype`) in a request a table will be created as a non-typed table.\n\nThe request payload is backend specific: `timePartitioning`, `rangePartitioning` and `clustering` are BigQuery only ([documentation](https://cloud.google.com/bigquery/docs/reference/rest/v2/tables)). Buckets on other backends are rejected.\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 [TableDefinitionCreateJobParams](#components-schemas-TableDefinitionCreateJobParams).", "operationId": "post_/v2/storage/buckets/{bucketId}/tables-definition::CreateTableDefinitionAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "The bucket Id.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main" }, { "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/SnowflakeCreateTableDefinitionRequest" }, { "$ref": "#/components/schemas/BigqueryCreateTableDefinitionRequest" } ] } } } }, "responses": { "400": { "description": "Validation error (including supplying `columns` together with `source`), or table definition is not supported for the bucket backend (`storage.driver.unsupportedOperation`)." }, "403": { "description": "Access denied to the bucket." }, "404": { "description": "Bucket not found (`storage.buckets.notFound`), or the supplied source table was not found in the project." }, "422": { "description": "`source` rejected: the bucket backend does not support creating a table from a source, the source is a non-persisted alias, or a referenced column (primary key, partitioning or clustering field) is not present in the source table." }, "503": { "description": "The bucket or its backend connection is under maintenance (`storage.buckets.maintenance`, `storage.backend.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/TableCreateResponse" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/TableCreateResponse" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/TableDefinitionCreateJobParams" } } } } }, "/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 \u2014 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 read 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 \u2014 the endpoint returns 202 with the job detail. The `snowflake` section is validated, but exposing a Snowflake bucket is not available yet: such a request is rejected with `storage.bucketListing.backendNotSupported`.\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" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateBucketListingRequest" } ] } } } }, "responses": { "400": { "description": "The request body is invalid (`validation.failed`; `storage.bucketListing.validationError` for a request with a `snowflake` section), a Snowflake grantee is not allowed (`storage.bucketListing.snowflakeGranteeNotAllowed`), the bucket is ineligible for a listing, the backend is not supported, the bucket's Snowflake backend is not customer-owned (`storage.bucketListing.snowflakeBackendNotCustomerOwned`), 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": "Removes the bucket listing. The listing is removed from the Analytics Hub exchange and the listing record is deleted. The underlying exchange is retained for future listings in the same project. The operation is idempotent: if the listing has already been removed in the target backend, the job still completes successfully.\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": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-sales" }, { "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 (`storage.bucketListing.featureNotEnabled`). Same gate is enforced on POST and PATCH for the same route." }, "404": { "description": "The bucket or its listing was not found (`storage.bucketListing.notFound`)." }, "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`, `bigquery.subscribers`, `snowflake.grantees` or `snowflake.accounts` \u2014 an empty JSON object is rejected with 400. The `bigquery.listingId` and `snowflake.mode` are immutable and cannot be changed. A sent `snowflake.grantees` list is granted in full, not only its new members, and every member that may still hold access and is no longer listed is revoked; the job result reports both lists as `snowflake.added` and `snowflake.removed`.\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" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateBucketListingRequest" } ] } } } }, "responses": { "400": { "description": "Returned when the request body is invalid or `snowflake.mode` differs from the stored mode (`storage.bucketListing.validationError`), a Snowflake grantee is not allowed (`storage.bucketListing.snowflakeGranteeNotAllowed`), the backend section does not match the bucket's backend (`storage.bucketListing.backendNotSupported`), the bucket cannot be exposed: linked, external schema or unsupported backend (`storage.bucketListing.notAllowed`), or the bucket's Snowflake backend is not customer-owned (`storage.bucketListing.snowflakeBackendNotCustomerOwned`)." }, "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 \u2014 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 read 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 \u2014 the endpoint returns 202 with the job detail. The `snowflake` section is validated, but exposing a Snowflake bucket is not available yet: such a request is rejected with `storage.bucketListing.backendNotSupported`.\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": "[^/]+" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateBucketListingRequest" } ] } } } }, "responses": { "400": { "description": "The request body is invalid (`validation.failed`; `storage.bucketListing.validationError` for a request with a `snowflake` section), a Snowflake grantee is not allowed (`storage.bucketListing.snowflakeGranteeNotAllowed`), the bucket is ineligible for a listing, the backend is not supported, the bucket's Snowflake backend is not customer-owned (`storage.bucketListing.snowflakeBackendNotCustomerOwned`), 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": "Removes the bucket listing. The listing is removed from the Analytics Hub exchange and the listing record is deleted. The underlying exchange is retained for future listings in the same project. The operation is idempotent: if the listing has already been removed in the target backend, the job still completes successfully.\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/buckets/{bucketId}/listing::BucketListingDeleteAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-sales" } ], "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 (`storage.bucketListing.featureNotEnabled`). Same gate is enforced on POST and PATCH for the same route." }, "404": { "description": "The bucket or its listing was not found (`storage.bucketListing.notFound`)." }, "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`, `bigquery.subscribers`, `snowflake.grantees` or `snowflake.accounts` \u2014 an empty JSON object is rejected with 400. The `bigquery.listingId` and `snowflake.mode` are immutable and cannot be changed. A sent `snowflake.grantees` list is granted in full, not only its new members, and every member that may still hold access and is no longer listed is revoked; the job result reports both lists as `snowflake.added` and `snowflake.removed`.\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/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": "[^/]+" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateBucketListingRequest" } ] } } } }, "responses": { "400": { "description": "Returned when the request body is invalid or `snowflake.mode` differs from the stored mode (`storage.bucketListing.validationError`), a Snowflake grantee is not allowed (`storage.bucketListing.snowflakeGranteeNotAllowed`), the backend section does not match the bucket's backend (`storage.bucketListing.backendNotSupported`), the bucket cannot be exposed: linked, external schema or unsupported backend (`storage.bucketListing.notAllowed`), or the bucket's Snowflake backend is not customer-owned (`storage.bucketListing.snowflakeBackendNotCustomerOwned`)." }, "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/branch/{branchId}/buckets/{bucketId}/listing/subscriptions": { "get": { "tags": [ "Buckets" ], "summary": "List consumers subscribing to a bucket exposure", "description": "Lists the consumers that currently subscribe to the bucket's exposure, so the effect of\ndeleting it can be seen beforehand. Each entry names the consumer's GCP project and the\ndataset that would be left behind as an unusable linked dataset.\n\nUnlike the other listing endpoints, this one reads live from the backend rather than\nfrom the database, because subscriptions exist only in Google Analytics Hub. Note that\n`bigquery.subscribers` on the exposure is a different thing: it is the list of\nprincipals that were granted access, not the consumers that used it.\n\nFor a Snowflake exposure in grant mode, `subscriptions` is empty and `snowflake.members`\nlists the roles that hold the exposure's schema grants in Snowflake now, each compared\nwith `snowflake.grantees`: a listed role that lacks a grant, a removed role that still\nholds one, and a role granted outside the exposure are all shown. Grants on single\ntables and views are not read. Share-mode exposures are not supported yet.", "operationId": "get_/v2/storage/branch/{branchId}/buckets/{bucketId}/listing/subscriptions::BucketListingSubscriptionsAction", "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": "Consumers subscribing to the bucket exposure. Empty while a BigQuery exposure is still being provisioned. For a Snowflake exposure, its live members in `snowflake`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketListingSubscriptionsResponse" } } } }, "400": { "description": "Returned when the exposure has no consumers this endpoint can list (`storage.bucketListing.backendNotSupported`): a share-mode Snowflake exposure, whose accounts cannot be listed yet, or an exposure on a backend other than BigQuery and Snowflake." }, "403": { "description": "Returned when the token does not have manage privilege on the bucket, when it is not allowed to expose buckets in this project or its project role may not create the exposure (`accessDenied`), or when the project lacks the `bucket-exposure` feature (`storage.bucketListing.featureNotEnabled`). Reading a consumer contact takes the same rights as creating the exposure, including the protected-branch roles in SOX projects." }, "404": { "description": "Returned when the bucket is not found, has no exposure, or its Snowflake schema no longer exists." }, "503": { "description": "The backend could not be asked for the current subscriptions or members (`storage.bucketListing.subscriptionsUnavailable`). The exposure itself is unaffected; retry the request." } } } }, "/v2/storage/buckets/{bucketId}/listing/subscriptions": { "get": { "tags": [ "Buckets" ], "summary": "List consumers subscribing to a bucket exposure", "description": "Lists the consumers that currently subscribe to the bucket's exposure, so the effect of\ndeleting it can be seen beforehand. Each entry names the consumer's GCP project and the\ndataset that would be left behind as an unusable linked dataset.\n\nUnlike the other listing endpoints, this one reads live from the backend rather than\nfrom the database, because subscriptions exist only in Google Analytics Hub. Note that\n`bigquery.subscribers` on the exposure is a different thing: it is the list of\nprincipals that were granted access, not the consumers that used it.\n\nFor a Snowflake exposure in grant mode, `subscriptions` is empty and `snowflake.members`\nlists the roles that hold the exposure's schema grants in Snowflake now, each compared\nwith `snowflake.grantees`: a listed role that lacks a grant, a removed role that still\nholds one, and a role granted outside the exposure are all shown. Grants on single\ntables and views are not read. Share-mode exposures are not supported yet.", "operationId": "get_/v2/storage/buckets/{bucketId}/listing/subscriptions::BucketListingSubscriptionsAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Identifier of the bucket.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" } } ], "responses": { "200": { "description": "Consumers subscribing to the bucket exposure. Empty while a BigQuery exposure is still being provisioned. For a Snowflake exposure, its live members in `snowflake`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketListingSubscriptionsResponse" } } } }, "400": { "description": "Returned when the exposure has no consumers this endpoint can list (`storage.bucketListing.backendNotSupported`): a share-mode Snowflake exposure, whose accounts cannot be listed yet, or an exposure on a backend other than BigQuery and Snowflake." }, "403": { "description": "Returned when the token does not have manage privilege on the bucket, when it is not allowed to expose buckets in this project or its project role may not create the exposure (`accessDenied`), or when the project lacks the `bucket-exposure` feature (`storage.bucketListing.featureNotEnabled`). Reading a consumer contact takes the same rights as creating the exposure, including the protected-branch roles in SOX projects." }, "404": { "description": "Returned when the bucket is not found, has no exposure, or its Snowflake schema no longer exists." }, "503": { "description": "The backend could not be asked for the current subscriptions or members (`storage.bucketListing.subscriptionsUnavailable`). The exposure itself is unaffected; retry the request." } } } }, "/v2/storage/branch/{branchId}/listings": { "get": { "tags": [ "Buckets" ], "summary": "List bucket listings", "description": "Lists all bucket exposures (BigQuery Analytics Hub listings) in the project or development branch. Returns an empty array when no listings exist. The endpoint is BigQuery-only; Snowflake Partner Connect projects receive a 501 response. Each row mirrors the per-bucket `GET /v2/storage/buckets/{bucketId}/listing` response and additionally carries the source `bucketId` so the listing can be cross-referenced without a second call. Data is read from the database - no backend API call is performed.", "operationId": "get_/v2/storage/branch/{branchId}/listings::BucketListingsListAction", "parameters": [ { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of bucket listings the token has manage privilege on.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectBucketListingResponse" } }, "example": [ { "bucketId": "in.c-sales", "name": "Sales 2026", "description": "Monthly sales data aggregated by region", "backend": "bigquery", "bigquery": { "listingId": "sales_2026", "listingResourceName": "projects/proj-123/locations/US/dataExchanges/stk_bucket_exchanger_42_a1b2/listings/sales_2026", "subscribers": [ "user:a@example.com", "group:data@example.com" ] }, "createdAt": "2026-05-13T10:00:00+00:00" } ] } } }, "501": { "description": "Bucket listings are not supported on Snowflake Partner Connect projects (`storage.buckets.notSupportedForSPCProject`)." } } } }, "/v2/storage/listings": { "get": { "tags": [ "Buckets" ], "summary": "List bucket listings", "description": "Lists all bucket exposures (BigQuery Analytics Hub listings) in the project or development branch. Returns an empty array when no listings exist. The endpoint is BigQuery-only; Snowflake Partner Connect projects receive a 501 response. Each row mirrors the per-bucket `GET /v2/storage/buckets/{bucketId}/listing` response and additionally carries the source `bucketId` so the listing can be cross-referenced without a second call. Data is read from the database - no backend API call is performed.", "operationId": "get_/v2/storage/listings::BucketListingsListAction", "responses": { "200": { "description": "List of bucket listings the token has manage privilege on.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectBucketListingResponse" } }, "example": [ { "bucketId": "in.c-sales", "name": "Sales 2026", "description": "Monthly sales data aggregated by region", "backend": "bigquery", "bigquery": { "listingId": "sales_2026", "listingResourceName": "projects/proj-123/locations/US/dataExchanges/stk_bucket_exchanger_42_a1b2/listings/sales_2026", "subscribers": [ "user:a@example.com", "group:data@example.com" ] }, "createdAt": "2026-05-13T10:00:00+00:00" } ] } } }, "501": { "description": "Bucket listings are not supported on Snowflake Partner Connect projects (`storage.buckets.notSupportedForSPCProject`)." } } } }, "/v2/storage/branch/{branchId}/buckets/{bucketId}/refresh": { "put": { "tags": [ "Buckets" ], "summary": "Bucket Refresh", "description": "**EXPERIMENTAL**\n\nRefresh external bucket. For **Snowflake** and **BigQuery** backends only. If the database object (DB, schema...) isn't available anymore (was deleted or revoked), the bucket in Storage will be deleted.\n\nBy default only tables whose backend `LAST_ALTERED` is newer than the bucket's stored `lastChangeDate` are refreshed. Use `force=1` to ignore the stored date and refresh all tables and views (useful to recover from a stale Snowflake `LAST_ALTERED` on a data share), or pass `lastChangeDate` to override the comparison date. `force` takes precedence over `lastChangeDate`.\n\nA regular (not external, not linked) **Snowflake** bucket in the default branch can be refreshed too. The refresh registers the tables of the bucket schema that Storage does not know yet - for example a table restored with `UNDROP TABLE` or created outside Keboola - with their columns, types, primary key and comments as descriptions, and transfers their ownership to the project role. Tables Storage already knows are never changed or removed, import staging tables (`__temp_` prefix) and objects other than tables are skipped, and an empty table younger than about 15 minutes is left for a later refresh because it may belong to a table create still in progress. `force` and `lastChangeDate` do not apply.\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 [RefreshJobResponse](#model-RefreshJobResponse).\n\n Parameters of job will be [RefreshJobParams](#components-schemas-RefreshJobParams).", "operationId": "put_/v2/storage/branch/{branchId}/buckets/{bucketId}/refresh::RefreshAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-external-bucket" }, { "name": "force", "in": "query", "description": "When true, ignore the stored `lastChangeDate` and refresh all tables and views. Takes precedence over `lastChangeDate`.", "required": false, "schema": { "type": "boolean", "default": false }, "example": false }, { "name": "lastChangeDate", "in": "query", "description": "Override of the `lastChangeDate` used to detect altered tables. Can be a unix timestamp or any date accepted by [strtotime](http://www.php.net/manual/en/function.strtotime.php). Examples: `-2 days`, `1360138863`, `2013-02-12T15:19:21+00:00`. Ignored when `force` is true.", "required": false, "schema": { "type": "string", "nullable": true, "default": null }, "example": "2013-02-12T15:19:21+00:00" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "404": { "description": "The bucket was not found (`storage.buckets.notFound`)." }, "400": { "description": "Bucket refresh is not supported for the bucket (`storage.buckets.notSupported`), the bucket is in a development branch (`storage.buckets.devBranchBucketRefreshNotSupported`), or the `lastChangeDate` value is invalid (`storage.buckets.invalidLastChangeDate`)." }, "403": { "description": "Access to the bucket was denied." }, "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/RefreshJobResponse" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshJobResponse" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshJobParams" } } } } }, "/v2/storage/buckets/{bucketId}/refresh": { "put": { "tags": [ "Buckets" ], "summary": "Bucket Refresh", "description": "**EXPERIMENTAL**\n\nRefresh external bucket. For **Snowflake** and **BigQuery** backends only. If the database object (DB, schema...) isn't available anymore (was deleted or revoked), the bucket in Storage will be deleted.\n\nBy default only tables whose backend `LAST_ALTERED` is newer than the bucket's stored `lastChangeDate` are refreshed. Use `force=1` to ignore the stored date and refresh all tables and views (useful to recover from a stale Snowflake `LAST_ALTERED` on a data share), or pass `lastChangeDate` to override the comparison date. `force` takes precedence over `lastChangeDate`.\n\nA regular (not external, not linked) **Snowflake** bucket in the default branch can be refreshed too. The refresh registers the tables of the bucket schema that Storage does not know yet - for example a table restored with `UNDROP TABLE` or created outside Keboola - with their columns, types, primary key and comments as descriptions, and transfers their ownership to the project role. Tables Storage already knows are never changed or removed, import staging tables (`__temp_` prefix) and objects other than tables are skipped, and an empty table younger than about 15 minutes is left for a later refresh because it may belong to a table create still in progress. `force` and `lastChangeDate` do not apply.\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 [RefreshJobResponse](#model-RefreshJobResponse).\n\n Parameters of job will be [RefreshJobParams](#components-schemas-RefreshJobParams).", "operationId": "put_/v2/storage/buckets/{bucketId}/refresh::RefreshAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-external-bucket" }, { "name": "force", "in": "query", "description": "When true, ignore the stored `lastChangeDate` and refresh all tables and views. Takes precedence over `lastChangeDate`.", "required": false, "schema": { "type": "boolean", "default": false }, "example": false }, { "name": "lastChangeDate", "in": "query", "description": "Override of the `lastChangeDate` used to detect altered tables. Can be a unix timestamp or any date accepted by [strtotime](http://www.php.net/manual/en/function.strtotime.php). Examples: `-2 days`, `1360138863`, `2013-02-12T15:19:21+00:00`. Ignored when `force` is true.", "required": false, "schema": { "type": "string", "nullable": true, "default": null }, "example": "2013-02-12T15:19:21+00:00" } ], "responses": { "404": { "description": "The bucket was not found (`storage.buckets.notFound`)." }, "400": { "description": "Bucket refresh is not supported for the bucket (`storage.buckets.notSupported`), the bucket is in a development branch (`storage.buckets.devBranchBucketRefreshNotSupported`), or the `lastChangeDate` value is invalid (`storage.buckets.invalidLastChangeDate`)." }, "403": { "description": "Access to the bucket was denied." }, "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/RefreshJobResponse" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshJobResponse" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshJobParams" } } } } }, "/v2/storage/branch/{branchId}/buckets/{bucketId}/refresh-tables-info": { "post": { "tags": [ "Buckets" ], "summary": "Bucket Tables Information Refresh", "description": "Refresh tables information in bucket. Available for **Snowflake** and **BigQuery** backends, not for external buckets. The refresh runs in a background job; to see the job detail use the Job Detail endpoint.\n\nOn **Snowflake** it refreshes the row count and data size of the bucket's tables. Aliases with source table in the defined bucket are also refreshed. If an alias in the discussed bucket has its source table in another bucket, it won't be refreshed.\n\nOn **BigQuery** it re-reads the policy tags of the bucket's dataset and records them, so a tag set or removed directly in BigQuery shows in the table detail's `policyTagState`. Column definitions, row count and data size are not changed, and aliases are not refreshed. It runs one BigQuery `INFORMATION_SCHEMA` query per refresh, which BigQuery bills.", "operationId": "post_/v2/storage/branch/{branchId}/buckets/{bucketId}/refresh-tables-info::RefreshTablesInformationAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Refresh job enqueued; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "refreshTablesInformation", "operationParams": { "idBucket": 123 }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "The bucket is an external bucket or is not on the Snowflake or BigQuery backend (`storage.buckets.notSupported`), or the job could not be created." }, "403": { "description": "The token does not have write access to the bucket." }, "404": { "description": "The bucket was not found (`storage.buckets.notFound`)." }, "503": { "description": "The bucket or its backend is under maintenance." } } } }, "/v2/storage/branch/{branchId}/buckets/register": { "post": { "tags": [ "Buckets" ], "summary": "Register bucket", "description": "**EXPERIMENTAL**\n\nUse this API call to create a new bucket from an existing resource (schema or DB - depends on backend). Available for **Snowflake** and **BigQuery** backends only. Requires the `external-buckets` and `input-mapping-read-only-storage` project features and is available in the default branch only. The bucket is registered in a background job; to see the job detail use the Job Detail endpoint.", "operationId": "post_/v2/storage/branch/{branchId}/buckets/register::RegisterExistingBucketAction", "parameters": [ { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RegisterExistingBucketRequest" } ] } } } }, "responses": { "202": { "description": "Bucket registration job enqueued; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "bucketRegister", "operationParams": { "name": "organizationData", "displayName": "organization-members", "stage": "in", "backend": "snowflake", "description": "my bucket", "path": [ "DATABASE", "SCHEMA" ], "isSnowflakeSharedDatabase": false, "branchId": 4230, "queue": "main" }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "Invalid request (`storage.buckets.validation`), the project lacks the `input-mapping-read-only-storage` or `external-buckets` feature (`manage.project.missingFeatureFlag`), or the request was made in a development branch." }, "403": { "description": "The token cannot manage buckets." } } } }, "/v2/storage/buckets/register": { "post": { "tags": [ "Buckets" ], "summary": "Register bucket", "description": "**EXPERIMENTAL**\n\nUse this API call to create a new bucket from an existing resource (schema or DB - depends on backend). Available for **Snowflake** and **BigQuery** backends only. Requires the `external-buckets` and `input-mapping-read-only-storage` project features and is available in the default branch only. The bucket is registered in a background job; to see the job detail use the Job Detail endpoint.", "operationId": "post_/v2/storage/buckets/register::RegisterExistingBucketAction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RegisterExistingBucketRequest" } ] } } } }, "responses": { "202": { "description": "Bucket registration job enqueued; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "bucketRegister", "operationParams": { "name": "organizationData", "displayName": "organization-members", "stage": "in", "backend": "snowflake", "description": "my bucket", "path": [ "DATABASE", "SCHEMA" ], "isSnowflakeSharedDatabase": false, "branchId": 4230, "queue": "main" }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "Invalid request (`storage.buckets.validation`), the project lacks the `input-mapping-read-only-storage` or `external-buckets` feature (`manage.project.missingFeatureFlag`), or the request was made in a development branch." }, "403": { "description": "The token cannot manage buckets." } } } }, "/v2/storage/branch/{branchId}/buckets/{bucketId}/scheduled-tasks/refresh": { "post": { "tags": [ "Buckets" ], "summary": "Schedule bucket refresh", "description": "**EXPERIMENTAL**\n\nSchedule external bucket refresh to a given time or repeating period defined by a cron expression. Available for external buckets in the default branch only.", "operationId": "post_/v2/storage/branch/{branchId}/buckets/{bucketId}/scheduled-tasks/refresh::ScheduleRefreshAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-bucket-name" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ScheduleRefreshRequest" } ] } } } }, "responses": { "201": { "description": "Scheduled task data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledTaskResponse" }, "example": { "uuid": "0197e22b-379d-7c62-bc6d-88e50c3d0c75", "job": "bucketRefresh", "relatedEntity": "bucket", "relatedId": "in.c-bucket-name", "cronExpression": "42 13 * * *", "createdAt": "2025-07-01T00:08:00+02:00" } } } }, "400": { "description": "The bucket is not an external bucket or is in a development branch (`storage.buckets.notSupported`), or the cron expression is invalid." }, "403": { "description": "The token does not have write access to the bucket (`accessDenied`)." }, "404": { "description": "The bucket was not found (`storage.buckets.notFound`)." } } } }, "/v2/storage/buckets/{bucketId}/scheduled-tasks/refresh": { "post": { "tags": [ "Buckets" ], "summary": "Schedule bucket refresh", "description": "**EXPERIMENTAL**\n\nSchedule external bucket refresh to a given time or repeating period defined by a cron expression. Available for external buckets in the default branch only.", "operationId": "post_/v2/storage/buckets/{bucketId}/scheduled-tasks/refresh::ScheduleRefreshAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-bucket-name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ScheduleRefreshRequest" } ] } } } }, "responses": { "201": { "description": "Scheduled task data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledTaskResponse" }, "example": { "uuid": "0197e22b-379d-7c62-bc6d-88e50c3d0c75", "job": "bucketRefresh", "relatedEntity": "bucket", "relatedId": "in.c-bucket-name", "cronExpression": "42 13 * * *", "createdAt": "2025-07-01T00:08:00+02:00" } } } }, "400": { "description": "The bucket is not an external bucket or is in a development branch (`storage.buckets.notSupported`), or the cron expression is invalid." }, "403": { "description": "The token does not have write access to the bucket (`accessDenied`)." }, "404": { "description": "The bucket was not found (`storage.buckets.notFound`)." } } } }, "/v2/storage/branch/{branchId}/buckets/{bucketId}/share": { "put": { "tags": [ "Buckets" ], "summary": "Change Bucket Sharing", "description": "Change the [sharing type](https://help.keboola.com/storage/buckets/sharing/#sharing-type) of a bucket. This operation is available only for organization administrators. The change is applied in a background job; to see the job detail use the Job Detail endpoint.", "operationId": "put_/v2/storage/branch/{branchId}/buckets/{bucketId}/share::BucketShareUpdateAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateBucketSharingRequest" } ] } } } }, "responses": { "202": { "description": "Sharing update job enqueued; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "bucketShareUpdate", "operationParams": { "sharing": "organization-project", "queue": "main" }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "Invalid or missing `sharing` value (`bucketSharing.validationError`)." }, "403": { "description": "The token cannot manage the bucket or is not an organization administrator (`accessDenied`)." }, "501": { "description": "Operation is not supported for Snowflake Partner Connect projects (`storage.snowflakePartnerConnect.notSupported`)." } } }, "delete": { "tags": [ "Buckets" ], "summary": "Stop Bucket Sharing", "description": "Disables sharing of a bucket.\n\nWhile other projects link the bucket, Storage refuses the request with `409 Conflict` and changes nothing: every link stays and the consumer projects observe no interruption. The refusal lists the blocking projects in its `linkedProjects` param.\n\nRemoving those links is a separate act, never a side effect of unsharing - use Drop Bucket in the linking project, or Force Unlink from this one. Reading the bucket stops working in a consumer project the moment its link is gone.\n\nThis operation is available only for organization administrators. Sharing is removed in a background job; to see the job detail use the Job Detail endpoint.", "operationId": "delete_/v2/storage/branch/{branchId}/buckets/{bucketId}/share::BucketShareDeleteAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Share removal job enqueued; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketShareDeleteResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "bucketRemoveShare", "operationParams": { "queue": "main" }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "The bucket is not shared (`storage.buckets.notShared`)." }, "403": { "description": "The token cannot manage the bucket or is not an organization administrator (`accessDenied`)." }, "404": { "description": "The bucket was not found (`storage.buckets.notFound`)." }, "409": { "description": "Other projects still link the bucket (`storage.buckets.alreadyLinked`). Nothing changed: every link is intact and the consumer projects observe no interruption. `linkedProjects` names the projects that block the request; unlink them first, which stops their reads and cannot be undone from this project.", "content": { "application/json": { "schema": {}, "example": { "error": "The bucket is already linked in other projects.", "code": "storage.buckets.alreadyLinked", "uuid": "019f47e0-d5d6-76c4-8da6-e2e60bebdd05", "params": { "linkedProjects": [ { "id": 123, "name": "Marketing analytics" }, { "id": 456, "name": "Finance reporting" } ] } } } } }, "503": { "description": "The bucket (`storage.buckets.maintenance`) or its backend (`storage.backend.maintenance`) is under maintenance." } } } }, "/v2/storage/buckets/{bucketId}/share": { "put": { "tags": [ "Buckets" ], "summary": "Change Bucket Sharing", "description": "Change the [sharing type](https://help.keboola.com/storage/buckets/sharing/#sharing-type) of a bucket. This operation is available only for organization administrators. The change is applied in a background job; to see the job detail use the Job Detail endpoint.", "operationId": "put_/v2/storage/buckets/{bucketId}/share::BucketShareUpdateAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateBucketSharingRequest" } ] } } } }, "responses": { "202": { "description": "Sharing update job enqueued; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "bucketShareUpdate", "operationParams": { "sharing": "organization-project", "queue": "main" }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "Invalid or missing `sharing` value (`bucketSharing.validationError`)." }, "403": { "description": "The token cannot manage the bucket or is not an organization administrator (`accessDenied`)." }, "501": { "description": "Operation is not supported for Snowflake Partner Connect projects (`storage.snowflakePartnerConnect.notSupported`)." } } }, "delete": { "tags": [ "Buckets" ], "summary": "Stop Bucket Sharing", "description": "Disables sharing of a bucket.\n\nWhile other projects link the bucket, Storage refuses the request with `409 Conflict` and changes nothing: every link stays and the consumer projects observe no interruption. The refusal lists the blocking projects in its `linkedProjects` param.\n\nRemoving those links is a separate act, never a side effect of unsharing - use Drop Bucket in the linking project, or Force Unlink from this one. Reading the bucket stops working in a consumer project the moment its link is gone.\n\nThis operation is available only for organization administrators. Sharing is removed in a background job; to see the job detail use the Job Detail endpoint.", "operationId": "delete_/v2/storage/buckets/{bucketId}/share::BucketShareDeleteAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" } ], "responses": { "202": { "description": "Share removal job enqueued; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketShareDeleteResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "bucketRemoveShare", "operationParams": { "queue": "main" }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "The bucket is not shared (`storage.buckets.notShared`)." }, "403": { "description": "The token cannot manage the bucket or is not an organization administrator (`accessDenied`)." }, "404": { "description": "The bucket was not found (`storage.buckets.notFound`)." }, "409": { "description": "Other projects still link the bucket (`storage.buckets.alreadyLinked`). Nothing changed: every link is intact and the consumer projects observe no interruption. `linkedProjects` names the projects that block the request; unlink them first, which stops their reads and cannot be undone from this project.", "content": { "application/json": { "schema": {}, "example": { "error": "The bucket is already linked in other projects.", "code": "storage.buckets.alreadyLinked", "uuid": "019f47e0-d5d6-76c4-8da6-e2e60bebdd05", "params": { "linkedProjects": [ { "id": 123, "name": "Marketing analytics" }, { "id": 456, "name": "Finance reporting" } ] } } } } }, "503": { "description": "The bucket (`storage.buckets.maintenance`) or its backend (`storage.backend.maintenance`) is under maintenance." } } } }, "/v2/storage/branch/{branchId}/buckets/{bucketId}/share-organization": { "post": { "tags": [ "Buckets" ], "summary": "Share Bucket To Organization", "description": "[Enables sharing](https://help.keboola.com/storage/buckets/sharing/) or **updates sharing** for this bucket within the organization. Any organization member will be able to link to this bucket from any project within the organization. This operation is available only for organization administrators. Sharing is set up in a background job; to see the job detail use the Job Detail endpoint.", "operationId": "post_/v2/storage/branch/{branchId}/buckets/{bucketId}/share-organization::BucketShareOrganizationAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Share job enqueued; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketShareOrganizationResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "bucketShareToOrganization", "operationParams": { "queue": "main" }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "Sharing a bucket in a development branch is not supported (`storage.buckets.devBranchBucketSharingNotSupported`)." }, "403": { "description": "The token cannot manage the bucket or is not an organization administrator (`accessDenied`)." }, "501": { "description": "Operation is not supported for Snowflake Partner Connect projects (`storage.snowflakePartnerConnect.notSupported`)." } } } }, "/v2/storage/buckets/{bucketId}/share-organization": { "post": { "tags": [ "Buckets" ], "summary": "Share Bucket To Organization", "description": "[Enables sharing](https://help.keboola.com/storage/buckets/sharing/) or **updates sharing** for this bucket within the organization. Any organization member will be able to link to this bucket from any project within the organization. This operation is available only for organization administrators. Sharing is set up in a background job; to see the job detail use the Job Detail endpoint.", "operationId": "post_/v2/storage/buckets/{bucketId}/share-organization::BucketShareOrganizationAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" } ], "responses": { "202": { "description": "Share job enqueued; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketShareOrganizationResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "bucketShareToOrganization", "operationParams": { "queue": "main" }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "Sharing a bucket in a development branch is not supported (`storage.buckets.devBranchBucketSharingNotSupported`)." }, "403": { "description": "The token cannot manage the bucket or is not an organization administrator (`accessDenied`)." }, "501": { "description": "Operation is not supported for Snowflake Partner Connect projects (`storage.snowflakePartnerConnect.notSupported`)." } } } }, "/v2/storage/branch/{branchId}/buckets/{bucketId}/share-organization-project": { "post": { "tags": [ "Buckets" ], "summary": "Share Bucket To Organization Project", "description": "[Enables sharing](https://help.keboola.com/storage/buckets/sharing/) or **updates sharing** for this bucket within the organization. Any member of a project within the organization will be able to link to this bucket from their project. This operation is available only for organization administrators. Sharing is set up in a background job; to see the job detail use the Job Detail endpoint.", "operationId": "post_/v2/storage/branch/{branchId}/buckets/{bucketId}/share-organization-project::BucketShareOrganizationProjectAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Share job enqueued; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketShareOrganizationProjectResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "bucketShareToOrganizationProject", "operationParams": { "queue": "main" }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "Sharing a bucket in a development branch is not supported (`storage.buckets.devBranchBucketSharingNotSupported`)." }, "403": { "description": "The token cannot manage the bucket or is not an organization administrator (`accessDenied`)." }, "404": { "description": "The bucket was not found (`storage.buckets.notFound`)." }, "501": { "description": "Operation is not supported for Snowflake Partner Connect projects (`storage.snowflakePartnerConnect.notSupported`)." } } } }, "/v2/storage/buckets/{bucketId}/share-organization-project": { "post": { "tags": [ "Buckets" ], "summary": "Share Bucket To Organization Project", "description": "[Enables sharing](https://help.keboola.com/storage/buckets/sharing/) or **updates sharing** for this bucket within the organization. Any member of a project within the organization will be able to link to this bucket from their project. This operation is available only for organization administrators. Sharing is set up in a background job; to see the job detail use the Job Detail endpoint.", "operationId": "post_/v2/storage/buckets/{bucketId}/share-organization-project::BucketShareOrganizationProjectAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" } ], "responses": { "202": { "description": "Share job enqueued; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketShareOrganizationProjectResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "bucketShareToOrganizationProject", "operationParams": { "queue": "main" }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "Sharing a bucket in a development branch is not supported (`storage.buckets.devBranchBucketSharingNotSupported`)." }, "403": { "description": "The token cannot manage the bucket or is not an organization administrator (`accessDenied`)." }, "404": { "description": "The bucket was not found (`storage.buckets.notFound`)." }, "501": { "description": "Operation is not supported for Snowflake Partner Connect projects (`storage.snowflakePartnerConnect.notSupported`)." } } } }, "/v2/storage/branch/{branchId}/buckets/{bucketId}/share-to-projects": { "post": { "tags": [ "Buckets" ], "summary": "Share Bucket To Projects", "description": "[Enables sharing](https://help.keboola.com/storage/buckets/sharing/) or **updates sharing** for this bucket to a specific set of projects in the organization. All users who are members of one of the targeted projects will be able to link to this bucket from that specific project. This operation is available only for organization administrators. Sharing is set up in a background job; to see the job detail use the Job Detail endpoint.", "operationId": "post_/v2/storage/branch/{branchId}/buckets/{bucketId}/share-to-projects::BucketShareToProjectsAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateBucketSharingToProjectsRequest" } ] } } } }, "responses": { "202": { "description": "Share job enqueued; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "bucketShareToProjects", "operationParams": { "targetProjectIds": [ 1 ], "queue": "main" }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "Invalid request (`bucketSharing.validationError`), or sharing an external bucket is not allowed / requires a listing (`storage.buckets.externalBucketShareNotAllowed`, `storage.buckets.externalBucketShareListingMissing`)." }, "403": { "description": "The token cannot manage the bucket or is not an organization administrator (`accessDenied`)." }, "501": { "description": "Operation is not supported for Snowflake Partner Connect projects (`storage.snowflakePartnerConnect.notSupported`)." } } } }, "/v2/storage/buckets/{bucketId}/share-to-projects": { "post": { "tags": [ "Buckets" ], "summary": "Share Bucket To Projects", "description": "[Enables sharing](https://help.keboola.com/storage/buckets/sharing/) or **updates sharing** for this bucket to a specific set of projects in the organization. All users who are members of one of the targeted projects will be able to link to this bucket from that specific project. This operation is available only for organization administrators. Sharing is set up in a background job; to see the job detail use the Job Detail endpoint.", "operationId": "post_/v2/storage/buckets/{bucketId}/share-to-projects::BucketShareToProjectsAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateBucketSharingToProjectsRequest" } ] } } } }, "responses": { "202": { "description": "Share job enqueued; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "bucketShareToProjects", "operationParams": { "targetProjectIds": [ 1 ], "queue": "main" }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "Invalid request (`bucketSharing.validationError`), or sharing an external bucket is not allowed / requires a listing (`storage.buckets.externalBucketShareNotAllowed`, `storage.buckets.externalBucketShareListingMissing`)." }, "403": { "description": "The token cannot manage the bucket or is not an organization administrator (`accessDenied`)." }, "501": { "description": "Operation is not supported for Snowflake Partner Connect projects (`storage.snowflakePartnerConnect.notSupported`)." } } } }, "/v2/storage/branch/{branchId}/buckets/{bucketId}/share-to-users": { "post": { "tags": [ "Buckets" ], "summary": "Share Bucket To Users", "description": "[Enables sharing](https://help.keboola.com/storage/buckets/sharing/) or **updates sharing** for this bucket to a specific set of users in the organization. All users who are included in the `targetUsers` array will be able to link to this bucket. This operation is available only for organization administrators. Sharing is set up in a background job; to see the job detail use the Job Detail endpoint.", "operationId": "post_/v2/storage/branch/{branchId}/buckets/{bucketId}/share-to-users::BucketShareToUsersAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateBucketSharingToUsersRequest" } ] } } } }, "responses": { "202": { "description": "Share job enqueued; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "bucketShareToAdmins", "operationParams": { "targetUsers": [ 1 ], "queue": "main" }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "Invalid request (`bucketSharing.validationError`), or sharing an external bucket is not allowed / requires a listing (`storage.buckets.externalBucketShareNotAllowed`, `storage.buckets.externalBucketShareListingMissing`)." }, "403": { "description": "The token cannot manage the bucket or is not an organization administrator (`accessDenied`)." }, "501": { "description": "Operation is not supported for Snowflake Partner Connect projects (`storage.snowflakePartnerConnect.notSupported`)." } } } }, "/v2/storage/buckets/{bucketId}/share-to-users": { "post": { "tags": [ "Buckets" ], "summary": "Share Bucket To Users", "description": "[Enables sharing](https://help.keboola.com/storage/buckets/sharing/) or **updates sharing** for this bucket to a specific set of users in the organization. All users who are included in the `targetUsers` array will be able to link to this bucket. This operation is available only for organization administrators. Sharing is set up in a background job; to see the job detail use the Job Detail endpoint.", "operationId": "post_/v2/storage/buckets/{bucketId}/share-to-users::BucketShareToUsersAction", "parameters": [ { "name": "bucketId", "in": "path", "description": "Bucket ID.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateBucketSharingToUsersRequest" } ] } } } }, "responses": { "202": { "description": "Share job enqueued; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "bucketShareToAdmins", "operationParams": { "targetUsers": [ 1 ], "queue": "main" }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "Invalid request (`bucketSharing.validationError`), or sharing an external bucket is not allowed / requires a listing (`storage.buckets.externalBucketShareNotAllowed`, `storage.buckets.externalBucketShareListingMissing`)." }, "403": { "description": "The token cannot manage the bucket or is not an organization administrator (`accessDenied`)." }, "501": { "description": "Operation is not supported for Snowflake Partner Connect projects (`storage.snowflakePartnerConnect.notSupported`)." } } } }, "/v2/storage/branch/{branchId}/changes/tables": { "get": { "tags": [ "Development Branches" ], "summary": "List table changes in a development branch", "description": "Lists the tables of a [Development Branch](#tag/Development-Branches) whose schema differs from production: tables that are new in the branch, and tables whose columns, column types, primary key or column order changed. The branch is compared with production (the default branch) as it is **now**, not as it was when a table was pulled into the branch, so a column added in production after the pull is reported as removed in the branch.\n\nTables are matched by ID and columns by name, byte for byte, so a column whose name differs only in case is reported as removed and added. A column type change is a change of `type`, `length` or `nullable`. The column order counts as changed when a column present on both sides moved; columns appended at the end of the branch table do not count. Tables whose schema is equal on both sides are omitted, and so are tables that cannot be compared: tables of linked, external or read-only buckets, aliases, and tables whose production bucket the token cannot read. Entries are ordered by table ID.\n\n`changeType` is `new` or `modified`. `deleted` is reserved for a later version and never returned by this one.\n\nOnly available in development branches of projects with branched storage.", "operationId": "get_/v2/storage/branch/{branchId}/changes/tables::TableChangesListAction", "parameters": [ { "name": "branchId", "in": "path", "description": "ID of the development branch. `default` resolves to the default branch, which is rejected with 400 (`storage.tables.changesNotAvailableOnDefaultBranch`).", "required": true, "schema": { "type": "string" }, "example": "1234" } ], "responses": { "200": { "description": "Tables that are new or modified in the branch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableChangesListResponse" }, "example": { "tables": [ { "id": "in.c-sales.customers", "name": "customers", "displayName": "customers", "bucket": { "id": "in.c-sales", "name": "c-sales", "displayName": "sales" }, "changeType": "new", "isTyped": false, "summary": { "addedColumns": 3, "removedColumns": 0, "typeChangedColumns": 0, "primaryKeyChanged": false, "columnOrderChanged": false }, "columns": [ { "name": "id", "definition": null }, { "name": "email", "definition": null }, { "name": "created_at", "definition": null } ], "primaryKey": [ "id" ] }, { "id": "in.c-sales.products", "name": "products", "displayName": "products", "bucket": { "id": "in.c-sales", "name": "c-sales", "displayName": "sales" }, "changeType": "modified", "isTyped": true, "summary": { "addedColumns": 1, "removedColumns": 1, "typeChangedColumns": 1, "primaryKeyChanged": true, "columnOrderChanged": true }, "changes": { "addedColumns": [ { "name": "tax_rate", "definition": { "type": "NUMBER", "length": "10,2", "nullable": true } } ], "removedColumns": [ { "name": "old_price", "definition": { "type": "NUMBER", "length": "10,2", "nullable": true } } ], "typeChangedColumns": [ { "name": "amount", "production": { "type": "NUMBER", "length": "38,0", "nullable": false }, "branch": { "type": "NUMBER", "length": "10,2", "nullable": false } } ], "primaryKey": { "production": [ "id" ], "branch": [ "id", "sku" ] }, "columnOrder": { "production": [ "id", "name", "sku", "old_price", "amount", "category" ], "branch": [ "id", "sku", "name", "amount", "category", "tax_rate" ], "columns": [ { "name": "id", "productionPosition": 1, "branchPosition": 1 }, { "name": "sku", "productionPosition": 3, "branchPosition": 2 }, { "name": "name", "productionPosition": 2, "branchPosition": 3 }, { "name": "amount", "productionPosition": 5, "branchPosition": 4 }, { "name": "category", "productionPosition": 6, "branchPosition": 5 }, { "name": "tax_rate", "productionPosition": null, "branchPosition": 6 }, { "name": "old_price", "productionPosition": 4, "branchPosition": null } ] } } } ] } } } }, "400": { "description": "Called on the default branch (`storage.tables.changesNotAvailableOnDefaultBranch`), or the project has no branched storage (`storage.tables.changesRequireBranchedStorage`)." }, "404": { "description": "The development branch does not exist in the project." } } } }, "/v2/storage/branch/{branchId}/columns/{id}/metadata": { "get": { "tags": [ "Metadata" ], "summary": "List column metadata", "description": "Shows all metadata associated with the specified column.", "operationId": "get_/v2/storage/branch/{branchId}/columns/{id}/metadata::ColumnMetadataDetailAction", "parameters": [ { "name": "id", "in": "path", "description": "Id of the column in format `bucket.table.column`.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.customers.id" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Column metadata list.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } }, "example": [ { "id": "123", "key": "attribute_key", "value": "attribute_value", "provider": "keboola.some-komponent", "timestamp": "2016-09-19T13:02:11+0200" }, { "id": "124", "key": "another_attribute_key", "value": "attribute_value", "provider": "keboola.some-komponent", "timestamp": "2016-09-19T13:02:11+0200" } ] } } }, "403": { "description": "Returned when the token has no read access to the bucket." }, "404": { "description": "Returned when the column (`storage.tables.columnNotFound`), table (`storage.tables.notFound`) or bucket (`storage.buckets.notFound`) is not found." } } }, "post": { "tags": [ "Metadata" ], "summary": "Create or update column metadata", "description": "Sets multiple metadata with one call. If the given key and provider combination already exist\nfor the column, the data will be updated with the new value and timestamp. All metadata associated\nwith the column are returned in the response.", "operationId": "post_/v2/storage/branch/{branchId}/columns/{id}/metadata::ColumnMetadataCreateOrUpdateAction", "parameters": [ { "name": "id", "in": "path", "description": "Id of the column in format `bucket.table.column`.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.customers.id" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Metadata payload including provider identifier and metadata items.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMetadataWithProviderRequest" } } } }, "responses": { "201": { "description": "All metadata associated with the column.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } }, "example": [ { "id": "19509", "key": "some-key", "value": "Some value", "provider": "test-component", "timestamp": "2017-02-13T23:36:10+0100" } ] } } }, "400": { "description": "Returned when the metadata payload is invalid (`KBC.invalid`)." }, "403": { "description": "Returned when the token has no write access to the bucket or the provider is protected (`storage.metadata.invalidProvider`)." }, "404": { "description": "Returned when the column (`storage.tables.columnNotFound`), table (`storage.tables.notFound`) or bucket (`storage.buckets.notFound`) is not found." } } } }, "/v2/storage/columns/{id}/metadata": { "get": { "tags": [ "Metadata" ], "summary": "List column metadata", "description": "Shows all metadata associated with the specified column.", "operationId": "get_/v2/storage/columns/{id}/metadata::ColumnMetadataDetailAction", "parameters": [ { "name": "id", "in": "path", "description": "Id of the column in format `bucket.table.column`.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.customers.id" } ], "responses": { "200": { "description": "Column metadata list.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } }, "example": [ { "id": "123", "key": "attribute_key", "value": "attribute_value", "provider": "keboola.some-komponent", "timestamp": "2016-09-19T13:02:11+0200" }, { "id": "124", "key": "another_attribute_key", "value": "attribute_value", "provider": "keboola.some-komponent", "timestamp": "2016-09-19T13:02:11+0200" } ] } } }, "403": { "description": "Returned when the token has no read access to the bucket." }, "404": { "description": "Returned when the column (`storage.tables.columnNotFound`), table (`storage.tables.notFound`) or bucket (`storage.buckets.notFound`) is not found." } } }, "post": { "tags": [ "Metadata" ], "summary": "Create or update column metadata", "description": "Sets multiple metadata with one call. If the given key and provider combination already exist\nfor the column, the data will be updated with the new value and timestamp. All metadata associated\nwith the column are returned in the response.", "operationId": "post_/v2/storage/columns/{id}/metadata::ColumnMetadataCreateOrUpdateAction", "parameters": [ { "name": "id", "in": "path", "description": "Id of the column in format `bucket.table.column`.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.customers.id" } ], "requestBody": { "description": "Metadata payload including provider identifier and metadata items.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMetadataWithProviderRequest" } } } }, "responses": { "201": { "description": "All metadata associated with the column.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } }, "example": [ { "id": "19509", "key": "some-key", "value": "Some value", "provider": "test-component", "timestamp": "2017-02-13T23:36:10+0100" } ] } } }, "400": { "description": "Returned when the metadata payload is invalid (`KBC.invalid`)." }, "403": { "description": "Returned when the token has no write access to the bucket or the provider is protected (`storage.metadata.invalidProvider`)." }, "404": { "description": "Returned when the column (`storage.tables.columnNotFound`), table (`storage.tables.notFound`) or bucket (`storage.buckets.notFound`) is not found." } } } }, "/v2/storage/branch/{branchId}/columns/{id}/metadata/{metadataId}": { "delete": { "tags": [ "Metadata" ], "summary": "Delete column metadata", "description": "Deletes the specified metadata item from the column.", "operationId": "delete_/v2/storage/branch/{branchId}/columns/{id}/metadata/{metadataId}::ColumnMetadataDeleteAction", "parameters": [ { "name": "id", "in": "path", "description": "Id of the column in format `bucket.table.column`.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.customers.id" }, { "name": "metadataId", "in": "path", "description": "Id of the metadata.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 19509 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Metadata item deleted." }, "400": { "description": "Returned when the metadata item cannot be deleted (`KBC.invalid`)." }, "403": { "description": "Returned when the token has no write access to the bucket or the provider is protected (`storage.metadata.invalidProvider`)." }, "404": { "description": "Returned when the column (`storage.tables.columnNotFound`), table, bucket or the metadata item (`storage.metadata.notFound`) is not found." } } } }, "/v2/storage/columns/{id}/metadata/{metadataId}": { "delete": { "tags": [ "Metadata" ], "summary": "Delete column metadata", "description": "Deletes the specified metadata item from the column.", "operationId": "delete_/v2/storage/columns/{id}/metadata/{metadataId}::ColumnMetadataDeleteAction", "parameters": [ { "name": "id", "in": "path", "description": "Id of the column in format `bucket.table.column`.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.customers.id" }, { "name": "metadataId", "in": "path", "description": "Id of the metadata.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 19509 } ], "responses": { "204": { "description": "Metadata item deleted." }, "400": { "description": "Returned when the metadata item cannot be deleted (`KBC.invalid`)." }, "403": { "description": "Returned when the token has no write access to the bucket or the provider is protected (`storage.metadata.invalidProvider`)." }, "404": { "description": "Returned when the column (`storage.tables.columnNotFound`), table, bucket or the metadata item (`storage.metadata.notFound`) is not found." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}": { "get": { "tags": [ "Components and Configurations" ], "summary": "Get component", "description": "Use this API call to obtain the definition of component for [Development Branch](#tag/Development-Branches) available in KBC.", "operationId": "get_/v2/storage/branch/{branchId}/components/{componentId}::BranchComponentDetailAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "branchId", "in": "path", "description": "Id of the development branch.", "required": true, "schema": { "type": "string" }, "example": "default" } ], "responses": { "200": { "description": "Component detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentArrayRead" }, "example": { "id": "keboola.app-tree", "type": "application", "name": "Tree depth", "description": "Application which computes a tree depth.", "longDescription": "This application computes levels in a table representing a tree.", "version": 1, "complexity": null, "categories": [], "hasUI": false, "hasRun": false, "ico32": "https://d3iz2gfan5zufq.cloudfront.net/images/cloud-services/keboola.app-tree-32-1.png", "ico64": "https://d3iz2gfan5zufq.cloudfront.net/images/cloud-services/keboola.app-tree-64-1.png", "ico128": "https://d3iz2gfan5zufq.cloudfront.net/images/cloud-services/keboola.app-tree-128-1.png", "data": { "definition": { "type": "aws-ecr", "uri": "147946154733.dkr.ecr.us-east-1.amazonaws.com/keboola/app-tree", "tag": "latest", "repository": { "region": "us-east-1" } }, "cpu_shares": 1024, "memory": "8024m", "configuration_format": "json", "process_timeout": 10800 }, "flags": [ "genericDockerUI", "genericDockerUI-tableInput", "genericDockerUI-tableOutput", "excludeFromNewList" ], "configurationSchema": [], "configurationRowSchema": [], "emptyConfiguration": [], "emptyConfigurationRow": [], "createConfigurationRowSchema": [], "uiOptions": [], "configurationDescription": "The tree data must be stored in a child-parent relationship.", "features": [], "expiredOn": null, "uri": "https://syrup.keboola.com/docker/keboola.app-tree", "dataTypesConfiguration": [], "processorConfiguration": [] } } } }, "403": { "description": "Token is not allowed to read the component (`storage.tokens.componentAccessDenied`)." }, "404": { "description": "Component not found (`storage.component.notFound`)." } } } }, "/v2/storage/branch/{branchId}/components": { "get": { "tags": [ "Components and Configurations" ], "summary": "Get components", "description": "Use this API call to obtain the definitions of all components in [Development Branch](#tag/Development-Branches)\ntogether with their configurations in the project. For more information about the KBC Component architecture, see the\n[Developers documentation](https://developers.keboola.com/overview/).\n\nOnly components that have at least one configuration in the project (deleted ones when `isDeleted=true`) are returned.\nThe `include` query parameter controls whether `configuration`, `rows` and `state` are embedded in each configuration.\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "get_/v2/storage/branch/{branchId}/components::ComponentsListAction", "parameters": [ { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "componentType", "in": "query", "description": "Filter components by type.", "required": false, "schema": { "description": "Filter components by type.", "type": "string", "nullable": true } }, { "name": "include", "in": "query", "description": "Comma-separated list of data to include. Allowed values: state, configuration, rows.", "required": false, "schema": { "description": "Comma-separated list of data to include. Allowed values: state, configuration, rows.", "type": "string", "nullable": true } }, { "name": "isDeleted", "in": "query", "description": "Whether to list deleted components instead of active ones. Accepts booleanish values.", "required": false, "schema": { "description": "Whether to list deleted components instead of active ones. Accepts booleanish values.", "type": "string", "nullable": true } } ], "responses": { "200": { "description": "List of components with their configurations.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ComponentWithConfigurationsResponse" } }, "example": [ { "id": "keboola.app-tree", "type": "application", "name": "Tree depth", "description": "Application which computes a tree depth.", "longDescription": "This application computes levels in a table representing a tree.", "version": 1, "complexity": null, "categories": [], "hasUI": false, "hasRun": false, "ico32": "https://d3iz2gfan5zufq.cloudfront.net/images/cloud-services/keboola.app-tree-32-1.png", "ico64": "https://d3iz2gfan5zufq.cloudfront.net/images/cloud-services/keboola.app-tree-64-1.png", "ico128": "https://d3iz2gfan5zufq.cloudfront.net/images/cloud-services/keboola.app-tree-128-1.png", "data": { "definition": { "type": "aws-ecr", "uri": "147946154733.dkr.ecr.us-east-1.amazonaws.com/keboola/app-tree", "tag": "latest", "repository": { "region": "us-east-1" } }, "cpu_shares": 1024, "memory": "8024m", "configuration_format": "json", "process_timeout": 10800 }, "flags": [ "genericDockerUI", "genericDockerUI-tableInput", "genericDockerUI-tableOutput", "excludeFromNewList" ], "configurationSchema": [], "configurationRowSchema": [], "emptyConfiguration": [], "emptyConfigurationRow": [], "createConfigurationRowSchema": [], "uiOptions": [], "configurationDescription": "The tree data must be stored in a child-parent relationship.", "features": [], "expiredOn": null, "uri": "https://syrup.keboola.com/docker/keboola.app-tree", "configurations": [ { "id": "236552566", "name": "teest2", "description": "", "created": "2017-02-14T12:12:30+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "version": 2, "changeDescription": "Configuration deleted", "isDisabled": false, "isDeleted": true, "currentVersion": { "created": "2017-02-14T12:12:45+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Configuration deleted", "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S" } } ], "dataTypesConfiguration": [], "processorConfiguration": [] } ] } } }, "403": { "description": "Token is not allowed to list components." } } } }, "/v2/storage/components": { "get": { "tags": [ "Components and Configurations" ], "summary": "Get components", "description": "Use this API call to obtain the definitions of all components in [Development Branch](#tag/Development-Branches)\ntogether with their configurations in the project. For more information about the KBC Component architecture, see the\n[Developers documentation](https://developers.keboola.com/overview/).\n\nOnly components that have at least one configuration in the project (deleted ones when `isDeleted=true`) are returned.\nThe `include` query parameter controls whether `configuration`, `rows` and `state` are embedded in each configuration.\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "get_/v2/storage/components::ComponentsListAction", "parameters": [ { "name": "componentType", "in": "query", "description": "Filter components by type.", "required": false, "schema": { "description": "Filter components by type.", "type": "string", "nullable": true } }, { "name": "include", "in": "query", "description": "Comma-separated list of data to include. Allowed values: state, configuration, rows.", "required": false, "schema": { "description": "Comma-separated list of data to include. Allowed values: state, configuration, rows.", "type": "string", "nullable": true } }, { "name": "isDeleted", "in": "query", "description": "Whether to list deleted components instead of active ones. Accepts booleanish values.", "required": false, "schema": { "description": "Whether to list deleted components instead of active ones. Accepts booleanish values.", "type": "string", "nullable": true } } ], "responses": { "200": { "description": "List of components with their configurations.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ComponentWithConfigurationsResponse" } }, "example": [ { "id": "keboola.app-tree", "type": "application", "name": "Tree depth", "description": "Application which computes a tree depth.", "longDescription": "This application computes levels in a table representing a tree.", "version": 1, "complexity": null, "categories": [], "hasUI": false, "hasRun": false, "ico32": "https://d3iz2gfan5zufq.cloudfront.net/images/cloud-services/keboola.app-tree-32-1.png", "ico64": "https://d3iz2gfan5zufq.cloudfront.net/images/cloud-services/keboola.app-tree-64-1.png", "ico128": "https://d3iz2gfan5zufq.cloudfront.net/images/cloud-services/keboola.app-tree-128-1.png", "data": { "definition": { "type": "aws-ecr", "uri": "147946154733.dkr.ecr.us-east-1.amazonaws.com/keboola/app-tree", "tag": "latest", "repository": { "region": "us-east-1" } }, "cpu_shares": 1024, "memory": "8024m", "configuration_format": "json", "process_timeout": 10800 }, "flags": [ "genericDockerUI", "genericDockerUI-tableInput", "genericDockerUI-tableOutput", "excludeFromNewList" ], "configurationSchema": [], "configurationRowSchema": [], "emptyConfiguration": [], "emptyConfigurationRow": [], "createConfigurationRowSchema": [], "uiOptions": [], "configurationDescription": "The tree data must be stored in a child-parent relationship.", "features": [], "expiredOn": null, "uri": "https://syrup.keboola.com/docker/keboola.app-tree", "configurations": [ { "id": "236552566", "name": "teest2", "description": "", "created": "2017-02-14T12:12:30+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "version": 2, "changeDescription": "Configuration deleted", "isDisabled": false, "isDeleted": true, "currentVersion": { "created": "2017-02-14T12:12:45+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Configuration deleted", "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S" } } ], "dataTypesConfiguration": [], "processorConfiguration": [] } ] } } }, "403": { "description": "Token is not allowed to list components." } } } }, "/v2/storage/branch/{branchId}/components/configs/batch-purge": { "post": { "tags": [ "Components and Configurations" ], "summary": "Purge Deleted Configurations", "description": "Permanently removes a list of configurations from the trash in one request, including all their versions,\nrows and metadata. This cannot be undone. Returns a `componentConfigurationsBatchPurge` job.\n\nEvery item carries the `version` the configuration was read at \u2014 the per-item equivalent of the `If-Match`\nheader of [the single-configuration purge](#tag/Components-and-Configurations). An item whose configuration\nhas moved on is reported in `failed` with `storage.components.configurations.versionMismatch` and the rest\nof the batch still runs. The same holds for every other per-item rule: a configuration that is not in the\ntrash, one that no longer exists, or one the token may not manage fails alone.\n\nThe job's `results` say per item what happened: `purged` lists the configurations that are gone, `failed`\nlists the ones left in the trash with the reason. The job itself ends as `error` when at least one item\nfailed, so a caller that only polls the status still learns the batch was partial.\n\nOnly available in the **default branch**; development branch configurations cannot be permanently removed,\nand in a development branch every item fails with `storage.components.cannotDeleteConfiguration`. Requires\nthe `canPurgeTrash` token permission.\n\nThe variant without `branch/{branchId}` in the URL behaves the same as the branch endpoint with `branch/default`.\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 [BatchPurgeJobResult](#model-BatchPurgeJobResult).\n\n Parameters of job will be [BatchPurgeJobParams](#components-schemas-BatchPurgeJobParams).", "operationId": "post_/v2/storage/branch/{branchId}/components/configs/batch-purge::ConfigurationBatchPurgeAction", "parameters": [ { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchPurgeRequest" }, "example": { "configurations": [ { "componentId": "keboola.ex-db-mysql", "configurationId": "main-1", "version": 5 }, { "componentId": "keboola.ex-db-mysql", "configurationId": "main-2", "version": 2 } ] } } } }, "responses": { "400": { "description": "Request body is invalid \u2014 a `configurations` list that is empty or longer than 1000 items, or an item missing `componentId`, `configurationId` or `version`." }, "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/BatchPurgeJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchPurgeJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchPurgeJobParams" } } } } }, "/v2/storage/components/configs/batch-purge": { "post": { "tags": [ "Components and Configurations" ], "summary": "Purge Deleted Configurations", "description": "Permanently removes a list of configurations from the trash in one request, including all their versions,\nrows and metadata. This cannot be undone. Returns a `componentConfigurationsBatchPurge` job.\n\nEvery item carries the `version` the configuration was read at \u2014 the per-item equivalent of the `If-Match`\nheader of [the single-configuration purge](#tag/Components-and-Configurations). An item whose configuration\nhas moved on is reported in `failed` with `storage.components.configurations.versionMismatch` and the rest\nof the batch still runs. The same holds for every other per-item rule: a configuration that is not in the\ntrash, one that no longer exists, or one the token may not manage fails alone.\n\nThe job's `results` say per item what happened: `purged` lists the configurations that are gone, `failed`\nlists the ones left in the trash with the reason. The job itself ends as `error` when at least one item\nfailed, so a caller that only polls the status still learns the batch was partial.\n\nOnly available in the **default branch**; development branch configurations cannot be permanently removed,\nand in a development branch every item fails with `storage.components.cannotDeleteConfiguration`. Requires\nthe `canPurgeTrash` token permission.\n\nThe variant without `branch/{branchId}` in the URL behaves the same as the branch endpoint with `branch/default`.\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 [BatchPurgeJobResult](#model-BatchPurgeJobResult).\n\n Parameters of job will be [BatchPurgeJobParams](#components-schemas-BatchPurgeJobParams).", "operationId": "post_/v2/storage/components/configs/batch-purge::ConfigurationBatchPurgeAction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchPurgeRequest" }, "example": { "configurations": [ { "componentId": "keboola.ex-db-mysql", "configurationId": "main-1", "version": 5 }, { "componentId": "keboola.ex-db-mysql", "configurationId": "main-2", "version": 2 } ] } } } }, "responses": { "400": { "description": "Request body is invalid \u2014 a `configurations` list that is empty or longer than 1000 items, or an item missing `componentId`, `configurationId` or `version`." }, "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/BatchPurgeJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchPurgeJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchPurgeJobParams" } } } } }, "/v2/storage/branch/{branchId}/components/configs/batch-restore": { "post": { "tags": [ "Components and Configurations" ], "summary": "Restore Deleted Configurations", "description": "Moves a list of configurations out of the trash in one request. Returns a\n`componentConfigurationsBatchRestore` job.\n\nItems carry no `version`: restoring is reversible and makes a new version rather than destroying one, so\nthere is nothing to guard against a concurrent write. Every per-item rule is applied per item \u2014 a\nconfiguration that no longer exists, one belonging to an unknown component, or one the token may not\nmanage fails alone and the rest of the batch still runs.\n\nThe job's `results` say per item what happened: `restored` lists the configurations that are back, each\nwith the new `version` the restore created, and `failed` lists the ones still in the trash with the\nreason. The job itself ends as `error` when at least one item failed, so a caller that only polls the\nstatus still learns the batch was partial.\n\nThe variant without `branch/{branchId}` in the URL behaves the same as the branch endpoint with `branch/default`.\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 [BatchRestoreJobResult](#model-BatchRestoreJobResult).\n\n Parameters of job will be [BatchRestoreJobParams](#components-schemas-BatchRestoreJobParams).", "operationId": "post_/v2/storage/branch/{branchId}/components/configs/batch-restore::ConfigurationBatchRestoreAction", "parameters": [ { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRestoreRequest" }, "example": { "configurations": [ { "componentId": "keboola.ex-db-mysql", "configurationId": "main-1" }, { "componentId": "keboola.ex-db-mysql", "configurationId": "main-2" } ] } } } }, "responses": { "400": { "description": "Request body is invalid \u2014 a `configurations` list that is empty or longer than 1000 items, or an item missing `componentId` or `configurationId`." }, "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/BatchRestoreJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRestoreJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRestoreJobParams" } } } } }, "/v2/storage/components/configs/batch-restore": { "post": { "tags": [ "Components and Configurations" ], "summary": "Restore Deleted Configurations", "description": "Moves a list of configurations out of the trash in one request. Returns a\n`componentConfigurationsBatchRestore` job.\n\nItems carry no `version`: restoring is reversible and makes a new version rather than destroying one, so\nthere is nothing to guard against a concurrent write. Every per-item rule is applied per item \u2014 a\nconfiguration that no longer exists, one belonging to an unknown component, or one the token may not\nmanage fails alone and the rest of the batch still runs.\n\nThe job's `results` say per item what happened: `restored` lists the configurations that are back, each\nwith the new `version` the restore created, and `failed` lists the ones still in the trash with the\nreason. The job itself ends as `error` when at least one item failed, so a caller that only polls the\nstatus still learns the batch was partial.\n\nThe variant without `branch/{branchId}` in the URL behaves the same as the branch endpoint with `branch/default`.\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 [BatchRestoreJobResult](#model-BatchRestoreJobResult).\n\n Parameters of job will be [BatchRestoreJobParams](#components-schemas-BatchRestoreJobParams).", "operationId": "post_/v2/storage/components/configs/batch-restore::ConfigurationBatchRestoreAction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRestoreRequest" }, "example": { "configurations": [ { "componentId": "keboola.ex-db-mysql", "configurationId": "main-1" }, { "componentId": "keboola.ex-db-mysql", "configurationId": "main-2" } ] } } } }, "responses": { "400": { "description": "Request body is invalid \u2014 a `configurations` list that is empty or longer than 1000 items, or an item missing `componentId` or `configurationId`." }, "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/BatchRestoreJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRestoreJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRestoreJobParams" } } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs": { "get": { "tags": [ "Components and Configurations" ], "summary": "List configurations", "description": "Lists all configurations for a component including all config rows in [Development Branch](#tag/Development-Branches).\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "get_/v2/storage/branch/{branchId}/components/{componentId}/configs::ConfigurationListAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "isDeleted", "in": "query", "description": "When true, only deleted configurations will be returned. When false, only current configurations will be returned.", "required": false, "schema": { "type": "boolean", "default": false }, "example": false }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of configurations.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationResponse" } }, "example": [ { "id": "main-1", "name": "Main 1", "description": "", "created": "2016-05-11T14:33:50+0200", "creatorToken": { "id": 67, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "67", "name": "dev@keboola.com", "adminId": 1234 }, "version": 2, "changeDescription": "Row row1 added", "isDisabled": false, "isDeleted": false, "configuration": { "key1": "val1" }, "rowsSortOrder": [], "rows": [ { "id": "row1", "name": "Row 1", "description": "", "isDisabled": false, "version": 1, "created": "2016-05-11T14:33:50+0200", "creatorToken": { "id": 67, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "67", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": null, "versionIdentifier": "01H2W8N0ZJJB6V126C8ZSND28N", "state": [], "configuration": { "key2": "val2" } } ], "state": [], "currentVersion": { "created": "2016-05-11T14:33:50+0200", "creatorToken": { "id": 67, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "67", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Row row1 added", "versionIdentifier": "01H2W8N0ZJJB6V126C8ZSND28N" } } ] } } }, "403": { "description": "Token is not allowed to read the component (`storage.tokens.componentAccessDenied`)." }, "404": { "description": "Component not found (`storage.component.notFound`)." } } }, "post": { "tags": [ "Components and Configurations" ], "summary": "Create Configuration", "description": "Creates a new component configuration for [Development Branch](#tag/Development-Branches).\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "post_/v2/storage/branch/{branchId}/components/{componentId}/configs::ConfigurationCreateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateConfigurationRequest" } ] } } } }, "responses": { "201": { "description": "Configuration created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationPartialResponse" }, "example": { "id": "236606822", "name": "My new configuration", "description": "", "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "version": 1, "changeDescription": "Initial configuration", "isDisabled": false, "isDeleted": false, "configuration": { "key": "value", "key2": "value2" }, "rowsSortOrder": [], "rows": [], "state": [], "currentVersion": { "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Initial configuration", "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S" } } } } }, "400": { "description": "Invalid request body (`storage.components.validation`, `validation.invalidConfigurationFormat`, `validation.invalidStateFormat`)." }, "403": { "description": "Token is not allowed to manage the component, or orchestrator creation is disabled for the project (`orchestrator.creationDisabled`)." }, "404": { "description": "Component not found (`storage.component.notFound`)." } } } }, "/v2/storage/components/{componentId}/configs": { "get": { "tags": [ "Components and Configurations" ], "summary": "List configurations", "description": "Lists all configurations for a component including all config rows in [Development Branch](#tag/Development-Branches).\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "get_/v2/storage/components/{componentId}/configs::ConfigurationListAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "isDeleted", "in": "query", "description": "When true, only deleted configurations will be returned. When false, only current configurations will be returned.", "required": false, "schema": { "type": "boolean", "default": false }, "example": false } ], "responses": { "200": { "description": "List of configurations.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationResponse" } }, "example": [ { "id": "main-1", "name": "Main 1", "description": "", "created": "2016-05-11T14:33:50+0200", "creatorToken": { "id": 67, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "67", "name": "dev@keboola.com", "adminId": 1234 }, "version": 2, "changeDescription": "Row row1 added", "isDisabled": false, "isDeleted": false, "configuration": { "key1": "val1" }, "rowsSortOrder": [], "rows": [ { "id": "row1", "name": "Row 1", "description": "", "isDisabled": false, "version": 1, "created": "2016-05-11T14:33:50+0200", "creatorToken": { "id": 67, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "67", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": null, "versionIdentifier": "01H2W8N0ZJJB6V126C8ZSND28N", "state": [], "configuration": { "key2": "val2" } } ], "state": [], "currentVersion": { "created": "2016-05-11T14:33:50+0200", "creatorToken": { "id": 67, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "67", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Row row1 added", "versionIdentifier": "01H2W8N0ZJJB6V126C8ZSND28N" } } ] } } }, "403": { "description": "Token is not allowed to read the component (`storage.tokens.componentAccessDenied`)." }, "404": { "description": "Component not found (`storage.component.notFound`)." } } }, "post": { "tags": [ "Components and Configurations" ], "summary": "Create Configuration", "description": "Creates a new component configuration for [Development Branch](#tag/Development-Branches).\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "post_/v2/storage/components/{componentId}/configs::ConfigurationCreateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateConfigurationRequest" } ] } } } }, "responses": { "201": { "description": "Configuration created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationPartialResponse" }, "example": { "id": "236606822", "name": "My new configuration", "description": "", "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "version": 1, "changeDescription": "Initial configuration", "isDisabled": false, "isDeleted": false, "configuration": { "key": "value", "key2": "value2" }, "rowsSortOrder": [], "rows": [], "state": [], "currentVersion": { "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Initial configuration", "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S" } } } } }, "400": { "description": "Invalid request body (`storage.components.validation`, `validation.invalidConfigurationFormat`, `validation.invalidStateFormat`)." }, "403": { "description": "Token is not allowed to manage the component, or orchestrator creation is disabled for the project (`orchestrator.creationDisabled`)." }, "404": { "description": "Component not found (`storage.component.notFound`)." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}": { "get": { "tags": [ "Components and Configurations" ], "summary": "Configuration Detail", "description": "Gets the component configuration detail for [Development Branch](#tag/Development-Branches).\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "get_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}::ConfigurationDetailAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Configuration detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationResponse" }, "example": { "id": "236606822", "name": "My new configuration", "description": "", "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "version": 1, "changeDescription": "Initial configuration", "isDisabled": false, "isDeleted": false, "configuration": { "key": "value", "key2": "value2" }, "rowsSortOrder": [], "rows": [], "state": [], "currentVersion": { "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Initial configuration", "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S" } } } } }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." } } }, "put": { "tags": [ "Components and Configurations" ], "summary": "Update Configuration", "description": "Updates an existing configuration for [Development Branch](#tag/Development-Branches). When the configuration is updated in a development branch, it does not affect `currentVersion` of the configuration.\n\nThe optional `If-Match` header turns the update into an optimistic-concurrency operation: the change\nis applied only if the configuration is still at the given version, otherwise nothing is written and\nthe request fails with `412 Precondition Failed`. Send the `version` field of a configuration detail\nresponse as a strong entity tag, e.g. `If-Match: \"5\"`.\n\n`If-Match: *` only requires that the configuration still exists. Weak validators (`W/\"5\"`) and tag\nlists are rejected with `400`, because `If-Match` mandates strong comparison and a configuration has\na single version.\n\nReads deliberately do **not** emit an `ETag`. The version covers the whole configuration including\nits rows and row order, but not `state` or `folder`, so job state writes and folder moves never\ninvalidate a caller's precondition, and `If-Match` does not protect `folder`. This also means the\nversion is not a valid strong validator for the full representation and must not be used for caching.\n\nWithout the header the update is unconditional and overwrites concurrent changes.\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "put_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}::ConfigurationUpdateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "workspaceId", "in": "query", "description": "When provided, enqueues a workspace output-mapping sync job after the config update. The workspace must be linked to this component and configuration.", "required": false, "schema": { "type": "integer", "nullable": true, "default": null } }, { "name": "If-Match", "in": "header", "description": "Optimistic concurrency precondition, RFC 9110 form. Send the `version` field of the configuration detail response as a strong entity tag, e.g. `\"5\"`; the update is applied only if the configuration is still at that version, otherwise it fails with 412. `*` only requires that the configuration still exists. Weak validators and tag lists are rejected with 400.", "required": false, "schema": { "type": "string" }, "example": "\"1\"" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateConfigurationRequest" } ] } } } }, "responses": { "200": { "description": "Configuration updated.", "headers": { "X-StorageApi-Job-Id": { "description": "ID of the enqueued workspace output-mapping sync job. Present only when `workspaceId` query parameter is supplied.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationResponse" }, "example": { "id": "236606822", "name": "My new configuration", "description": "", "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "version": 2, "changeDescription": "Added new key", "isDisabled": false, "isDeleted": false, "configuration": { "key": "value", "key2": "value2", "key3": "value3" }, "rowsSortOrder": [], "rows": [], "state": [], "currentVersion": { "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Added new key", "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S" } } } } }, "400": { "description": "Invalid request body, workspace does not belong to this component and configuration (`workspace.workspaceConfigurationMismatch`), or the `If-Match` value is unusable." }, "403": { "description": "Token is not allowed to manage the component (`storage.tokens.componentAccessDenied`)." }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." }, "409": { "description": "Another request is mid-write on the configuration; retryable (`storage.components.configurations.versionConflict`)." }, "412": { "description": "`If-Match` does not match the current version (`storage.components.configurations.versionMismatch`)." } } }, "delete": { "tags": [ "Components and Configurations" ], "summary": "Delete Configuration", "description": "Deletes a configuration in specified branch. When a configuration is deleted, it is only marked as deleted and remains still available in the system.\nYou can [list deleted](#tag/Components-and-Configurations) configurations.\nOther operations with deleted configurations are restricted.\n\nCalling this API call on a deleted configuration in a **development branch** will result in an error. Development branch configuration cannot be permanently removed.\nCalling this API call on a deleted configuration in a **default branch** will purge the configuration. Prefer the explicit\n[purge endpoint](#tag/Components-and-Configurations) for that \u2014 it states the destructive intent\nunambiguously and never falls back to a soft delete.\n\nThe optional `If-Match` header carries the same optimistic-concurrency precondition as configuration update: the delete is\napplied only if the configuration is still at the given version, otherwise nothing is written and the request fails with\n`412 Precondition Failed`. This closes the double-delete race \u2014 a delete sent from a stale view (which still saw the live\nconfiguration) cannot purge a configuration that moved to the trash in the meantime. Send the `version` field of a\nconfiguration detail response as a strong entity tag, e.g. `If-Match: \"5\"`. `If-Match: *` only requires that the\nconfiguration still exists; weak validators and tag lists are rejected with `400`.\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "delete_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}::ConfigurationDeleteAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "If-Match", "in": "header", "description": "Optimistic concurrency precondition, RFC 9110 form. Send the `version` field of the configuration detail response as a strong entity tag, e.g. `\"5\"`; the delete is applied only if the configuration is still at that version, otherwise it fails with 412.", "required": false, "schema": { "type": "string" }, "example": "\"1\"" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Configuration moved to trash, or purged when it already was in the trash." }, "400": { "description": "Configuration is in the trash of a development branch (`storage.components.cannotDeleteConfiguration`), or the `If-Match` value is unusable." }, "403": { "description": "Token is not allowed to manage the component, or lacks the `canPurgeTrash` permission required to purge." }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." }, "409": { "description": "Another request is mid-write on the configuration; retryable (`storage.components.configurations.versionConflict`)." }, "412": { "description": "`If-Match` does not match the current version (`storage.components.configurations.versionMismatch`)." } } } }, "/v2/storage/components/{componentId}/configs/{configurationId}": { "get": { "tags": [ "Components and Configurations" ], "summary": "Configuration Detail", "description": "Gets the component configuration detail for [Development Branch](#tag/Development-Branches).\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "get_/v2/storage/components/{componentId}/configs/{configurationId}::ConfigurationDetailAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" } ], "responses": { "200": { "description": "Configuration detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationResponse" }, "example": { "id": "236606822", "name": "My new configuration", "description": "", "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "version": 1, "changeDescription": "Initial configuration", "isDisabled": false, "isDeleted": false, "configuration": { "key": "value", "key2": "value2" }, "rowsSortOrder": [], "rows": [], "state": [], "currentVersion": { "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Initial configuration", "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S" } } } } }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." } } }, "put": { "tags": [ "Components and Configurations" ], "summary": "Update Configuration", "description": "Updates an existing configuration for [Development Branch](#tag/Development-Branches). When the configuration is updated in a development branch, it does not affect `currentVersion` of the configuration.\n\nThe optional `If-Match` header turns the update into an optimistic-concurrency operation: the change\nis applied only if the configuration is still at the given version, otherwise nothing is written and\nthe request fails with `412 Precondition Failed`. Send the `version` field of a configuration detail\nresponse as a strong entity tag, e.g. `If-Match: \"5\"`.\n\n`If-Match: *` only requires that the configuration still exists. Weak validators (`W/\"5\"`) and tag\nlists are rejected with `400`, because `If-Match` mandates strong comparison and a configuration has\na single version.\n\nReads deliberately do **not** emit an `ETag`. The version covers the whole configuration including\nits rows and row order, but not `state` or `folder`, so job state writes and folder moves never\ninvalidate a caller's precondition, and `If-Match` does not protect `folder`. This also means the\nversion is not a valid strong validator for the full representation and must not be used for caching.\n\nWithout the header the update is unconditional and overwrites concurrent changes.\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "put_/v2/storage/components/{componentId}/configs/{configurationId}::ConfigurationUpdateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "workspaceId", "in": "query", "description": "When provided, enqueues a workspace output-mapping sync job after the config update. The workspace must be linked to this component and configuration.", "required": false, "schema": { "type": "integer", "nullable": true, "default": null } }, { "name": "If-Match", "in": "header", "description": "Optimistic concurrency precondition, RFC 9110 form. Send the `version` field of the configuration detail response as a strong entity tag, e.g. `\"5\"`; the update is applied only if the configuration is still at that version, otherwise it fails with 412. `*` only requires that the configuration still exists. Weak validators and tag lists are rejected with 400.", "required": false, "schema": { "type": "string" }, "example": "\"1\"" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateConfigurationRequest" } ] } } } }, "responses": { "200": { "description": "Configuration updated.", "headers": { "X-StorageApi-Job-Id": { "description": "ID of the enqueued workspace output-mapping sync job. Present only when `workspaceId` query parameter is supplied.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationResponse" }, "example": { "id": "236606822", "name": "My new configuration", "description": "", "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "version": 2, "changeDescription": "Added new key", "isDisabled": false, "isDeleted": false, "configuration": { "key": "value", "key2": "value2", "key3": "value3" }, "rowsSortOrder": [], "rows": [], "state": [], "currentVersion": { "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Added new key", "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S" } } } } }, "400": { "description": "Invalid request body, workspace does not belong to this component and configuration (`workspace.workspaceConfigurationMismatch`), or the `If-Match` value is unusable." }, "403": { "description": "Token is not allowed to manage the component (`storage.tokens.componentAccessDenied`)." }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." }, "409": { "description": "Another request is mid-write on the configuration; retryable (`storage.components.configurations.versionConflict`)." }, "412": { "description": "`If-Match` does not match the current version (`storage.components.configurations.versionMismatch`)." } } }, "delete": { "tags": [ "Components and Configurations" ], "summary": "Delete Configuration", "description": "Deletes a configuration in specified branch. When a configuration is deleted, it is only marked as deleted and remains still available in the system.\nYou can [list deleted](#tag/Components-and-Configurations) configurations.\nOther operations with deleted configurations are restricted.\n\nCalling this API call on a deleted configuration in a **development branch** will result in an error. Development branch configuration cannot be permanently removed.\nCalling this API call on a deleted configuration in a **default branch** will purge the configuration. Prefer the explicit\n[purge endpoint](#tag/Components-and-Configurations) for that \u2014 it states the destructive intent\nunambiguously and never falls back to a soft delete.\n\nThe optional `If-Match` header carries the same optimistic-concurrency precondition as configuration update: the delete is\napplied only if the configuration is still at the given version, otherwise nothing is written and the request fails with\n`412 Precondition Failed`. This closes the double-delete race \u2014 a delete sent from a stale view (which still saw the live\nconfiguration) cannot purge a configuration that moved to the trash in the meantime. Send the `version` field of a\nconfiguration detail response as a strong entity tag, e.g. `If-Match: \"5\"`. `If-Match: *` only requires that the\nconfiguration still exists; weak validators and tag lists are rejected with `400`.\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "delete_/v2/storage/components/{componentId}/configs/{configurationId}::ConfigurationDeleteAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "If-Match", "in": "header", "description": "Optimistic concurrency precondition, RFC 9110 form. Send the `version` field of the configuration detail response as a strong entity tag, e.g. `\"5\"`; the delete is applied only if the configuration is still at that version, otherwise it fails with 412.", "required": false, "schema": { "type": "string" }, "example": "\"1\"" } ], "responses": { "204": { "description": "Configuration moved to trash, or purged when it already was in the trash." }, "400": { "description": "Configuration is in the trash of a development branch (`storage.components.cannotDeleteConfiguration`), or the `If-Match` value is unusable." }, "403": { "description": "Token is not allowed to manage the component, or lacks the `canPurgeTrash` permission required to purge." }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." }, "409": { "description": "Another request is mid-write on the configuration; retryable (`storage.components.configurations.versionConflict`)." }, "412": { "description": "`If-Match` does not match the current version (`storage.components.configurations.versionMismatch`)." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/diff": { "get": { "tags": [ "Components and Configurations" ], "summary": "Configuration Three-Way Diff", "description": "Returns the three sides needed to resolve a merge conflict for a configuration in a [Development Branch](#tag/Development-Branches): `base` (the configuration version at branch creation, or after the last rebase), `ours` (the dev branch head) and `theirs` (the default branch head). Each side carries per-side metadata (`version`, `isDeleted`) and the user-editable content in `diff` \u2014 the payload a client feeds directly into a three-way diff editor and, once resolved, sends back to the rebase endpoint. `diff.rows` are the configuration rows valid at that side's version, in their sort order \u2014 the same editable-content contract as the configuration body, with no per-row metadata; a row deleted on one side is detected by its absence relative to `base` (which acts as the reference set of \"what existed\"). A side is `null` when the configuration never existed on that side; `isDeleted: true` marks a deletion tombstone (it existed but was soft-deleted). When there is no conflict, `base` equals `theirs`; `ours` may still differ if the dev branch has its own changes, so the endpoint also works as a \"compare with default\" tool.\n\nOnly available in development branches.", "operationId": "get_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/diff::ConfigurationDiffAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Three-way diff of the configuration body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationDiffResponse" }, "example": { "theirs": { "version": 3, "isDeleted": false, "diff": { "name": "My configuration", "description": "", "changeDescription": "Default branch change", "isDisabled": false, "configuration": { "key": "default-value" }, "rows": [ { "id": "row-1", "name": "First row", "description": "", "isDisabled": false, "configuration": { "key": "default-value" } } ] } }, "base": { "version": 1, "isDeleted": false, "diff": { "name": "My configuration", "description": "", "changeDescription": "Initial configuration", "isDisabled": false, "configuration": { "key": "value" }, "rows": [ { "id": "row-1", "name": "First row", "description": "", "isDisabled": false, "configuration": { "key": "value" } } ] } }, "ours": { "version": 5, "isDeleted": false, "diff": { "name": "My configuration", "description": "", "changeDescription": "Dev branch change", "isDisabled": false, "configuration": { "key": "dev-value" }, "rows": [ { "id": "row-1", "name": "First row", "description": "", "isDisabled": false, "configuration": { "key": "dev-value" } }, { "id": "row-2", "name": "Added in dev branch", "description": "", "isDisabled": false, "configuration": { "key": "new" } } ] } } } } } }, "400": { "description": "Called on the default branch \u2014 diff is only available in dev branches (`storage.configuration.diffNotAvailableOnDefaultBranch`)." }, "403": { "description": "Token is not allowed to read the component (`storage.tokens.componentAccessDenied`)." }, "404": { "description": "Component not found (`storage.component.notFound`), or configuration absent in both branches (`storage.configuration.notFound`)." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/purge": { "post": { "tags": [ "Components and Configurations" ], "summary": "Purge Deleted Configuration", "description": "Permanently removes a configuration from the trash, including all its versions, rows and metadata. This cannot be undone.\n\nThe configuration must already be deleted (in the trash) \u2014 purging a live configuration fails with `400` and\n`storage.components.configurations.notInTrash`. Unlike [deleting](#tag/Components-and-Configurations)\nan already-deleted configuration (which also purges, for backward compatibility), this endpoint never falls back to a\nsoft delete, so a stale caller can never destroy a live configuration.\n\nOnly available in the **default branch**; development branch configurations cannot be permanently removed. Requires the\n`canPurgeTrash` token permission.\n\nThe `If-Match` header is **required**: purge is irreversible, so the caller must state which version of the configuration\nit decided to destroy. Send the `version` field of the configuration (deleted configurations are listed with\n`?isDeleted=1`) as a strong entity tag, e.g. `If-Match: \"5\"`. The purge is applied only if the configuration is still at\nthat version, otherwise nothing is removed and the request fails with `412 Precondition Failed`. A request without the\nheader (or with `*`, which does not pin a version) fails with `428 Precondition Required`.\n\nThe variant without `branch/{branchId}` in the URL behaves the same as the branch endpoint with `branch/default`.", "operationId": "post_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/purge::ConfigurationPurgeAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "If-Match", "in": "header", "description": "Required optimistic-concurrency precondition, RFC 9110 form. Send the `version` field of the configuration as a strong entity tag, e.g. `\"5\"`; the purge is applied only if the configuration is still at that version, otherwise it fails with 412. A request without the header (or with `*`, which does not pin a version) fails with 428.", "required": true, "schema": { "type": "string" }, "example": "\"2\"" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Configuration purged." }, "400": { "description": "Configuration is not in the trash (`storage.components.configurations.notInTrash`), the branch is a development branch (`storage.components.cannotDeleteConfiguration`), or the `If-Match` value is unusable." }, "403": { "description": "Token lacks the `canPurgeTrash` permission or is not allowed to manage the component." }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." }, "409": { "description": "Another request is mid-write on the configuration; retryable (`storage.components.configurations.versionConflict`)." }, "412": { "description": "`If-Match` does not match the current version (`storage.components.configurations.versionMismatch`)." }, "428": { "description": "`If-Match` header is missing or does not pin a specific version (`storage.components.configurations.missingExpectedVersion`)." } } } }, "/v2/storage/components/{componentId}/configs/{configurationId}/purge": { "post": { "tags": [ "Components and Configurations" ], "summary": "Purge Deleted Configuration", "description": "Permanently removes a configuration from the trash, including all its versions, rows and metadata. This cannot be undone.\n\nThe configuration must already be deleted (in the trash) \u2014 purging a live configuration fails with `400` and\n`storage.components.configurations.notInTrash`. Unlike [deleting](#tag/Components-and-Configurations)\nan already-deleted configuration (which also purges, for backward compatibility), this endpoint never falls back to a\nsoft delete, so a stale caller can never destroy a live configuration.\n\nOnly available in the **default branch**; development branch configurations cannot be permanently removed. Requires the\n`canPurgeTrash` token permission.\n\nThe `If-Match` header is **required**: purge is irreversible, so the caller must state which version of the configuration\nit decided to destroy. Send the `version` field of the configuration (deleted configurations are listed with\n`?isDeleted=1`) as a strong entity tag, e.g. `If-Match: \"5\"`. The purge is applied only if the configuration is still at\nthat version, otherwise nothing is removed and the request fails with `412 Precondition Failed`. A request without the\nheader (or with `*`, which does not pin a version) fails with `428 Precondition Required`.\n\nThe variant without `branch/{branchId}` in the URL behaves the same as the branch endpoint with `branch/default`.", "operationId": "post_/v2/storage/components/{componentId}/configs/{configurationId}/purge::ConfigurationPurgeAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "If-Match", "in": "header", "description": "Required optimistic-concurrency precondition, RFC 9110 form. Send the `version` field of the configuration as a strong entity tag, e.g. `\"5\"`; the purge is applied only if the configuration is still at that version, otherwise it fails with 412. A request without the header (or with `*`, which does not pin a version) fails with 428.", "required": true, "schema": { "type": "string" }, "example": "\"2\"" } ], "responses": { "204": { "description": "Configuration purged." }, "400": { "description": "Configuration is not in the trash (`storage.components.configurations.notInTrash`), the branch is a development branch (`storage.components.cannotDeleteConfiguration`), or the `If-Match` value is unusable." }, "403": { "description": "Token lacks the `canPurgeTrash` permission or is not allowed to manage the component." }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." }, "409": { "description": "Another request is mid-write on the configuration; retryable (`storage.components.configurations.versionConflict`)." }, "412": { "description": "`If-Match` does not match the current version (`storage.components.configurations.versionMismatch`)." }, "428": { "description": "`If-Match` header is missing or does not pin a specific version (`storage.components.configurations.missingExpectedVersion`)." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/rebase": { "post": { "tags": [ "Components and Configurations" ], "summary": "Rebase Configuration onto Default Branch", "description": "Re-anchors a [Development Branch](#tag/Development-Branches) configuration onto the given `version` of the default branch, preserving the dev branch work. The result is exactly two versions: version 1 = a faithful snapshot of the chosen default branch version (the new base, including its rows) and version 2 = the resolved head sent in the request's `diff` \u2014 the content of the three-way diff after the user resolved it, in the same shape a [Configuration Diff](#tag/Development-Branches) response side carries it in.\n\n`diff.rows` is the **complete resolved row set** (the diff's `diff.rows` posted back) and is required for a keep rebase \u2014 omitting it is an error, `[]` deletes all rows. Rows are reconciled against the re-anchored base: an `id` present in the base with changed content updates that row, identical content is kept without a new row version, an `id` not present in the base (or a row without an `id`) creates a new row, and a base row whose `id` is missing from the request is deleted. The array order becomes the row sort order.\n\nTo resolve the conflict by **deleting the configuration**, send an empty `diff` \u2014 `{}` or an empty/whitespace-only string \u2014 the new head version is a tombstone and the rows are deleted with it.\n\nOnly available in development branches. Requires the `branches-merge-requests` project feature.", "operationId": "post_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/rebase::ConfigurationRebaseAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RebaseRequest" } ] } } } }, "responses": { "200": { "description": "Rebased configuration (the new head).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationResponse" }, "example": { "id": "236606822", "name": "My new configuration", "description": "", "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "version": 2, "changeDescription": "Conflict resolved via rebase", "isDisabled": false, "isDeleted": false, "configuration": { "key": "resolved-value" }, "rowsSortOrder": [], "rows": [], "state": [], "currentVersion": { "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Conflict resolved via rebase", "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S" } } } } }, "400": { "description": "Not available on the default branch (`storage.configuration.rebaseNotAvailableOnDefaultBranch`), target version is not newer than the current base (`storage.configuration.rebaseTargetVersionNotNewer`), or invalid request body." }, "403": { "description": "Token is not allowed to manage the component (`storage.tokens.componentAccessDenied`)." }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`) or default branch version (`storage.configuration.versionNotFound`) not found." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/reset-to-default": { "post": { "tags": [ "Components and Configurations" ], "summary": "Reset Development Branch Configuration to Default", "description": "Updates an existing configuration for [Development Branch](#tag/Development-Branches) to a version that is currently in projects default branch.\n\nOnly available in development branches.", "operationId": "post_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/reset-to-default::ConfigurationResetToDefaultAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Configuration reset to the default branch version." }, "403": { "description": "Token is not allowed to manage the component (`storage.tokens.componentAccessDenied`)." }, "404": { "description": "Component not found (`storage.component.notFound`)." }, "501": { "description": "Called on the default branch (`notImplemented`)." } } } }, "/v2/storage/components/{componentId}/configs/{configurationId}/reset-to-default": { "post": { "tags": [ "Components and Configurations" ], "summary": "Reset Development Branch Configuration to Default", "description": "Updates an existing configuration for [Development Branch](#tag/Development-Branches) to a version that is currently in projects default branch.\n\nOnly available in development branches.", "operationId": "post_/v2/storage/components/{componentId}/configs/{configurationId}/reset-to-default::ConfigurationResetToDefaultAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" } ], "responses": { "204": { "description": "Configuration reset to the default branch version." }, "403": { "description": "Token is not allowed to manage the component (`storage.tokens.componentAccessDenied`)." }, "404": { "description": "Component not found (`storage.component.notFound`)." }, "501": { "description": "Called on the default branch (`notImplemented`)." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/restore": { "post": { "tags": [ "Components and Configurations" ], "summary": "Restore Deleted Configuration", "description": "Removes the `isDeleted` flag of a deleted configuration for [Development Branch](#tag/Development-Branches). This makes a new version of the configuration\nand the configuration becomes available for other API calls.\n\nThe response does not include `configuration`, `state`, `rowsSortOrder` and `rows`.\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "post_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/restore::ConfigurationRestoreAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Restored configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationPartialResponse" }, "example": { "id": "236606822", "name": "My new configuration", "description": "", "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "version": 4, "changeDescription": "Configuration restored", "isDisabled": false, "isDeleted": false, "currentVersion": { "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Configuration restored", "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S" } } } } }, "403": { "description": "Token is not allowed to manage the component, or orchestrator creation is disabled for the project (`orchestrator.creationDisabled`)." }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." } } } }, "/v2/storage/components/{componentId}/configs/{configurationId}/restore": { "post": { "tags": [ "Components and Configurations" ], "summary": "Restore Deleted Configuration", "description": "Removes the `isDeleted` flag of a deleted configuration for [Development Branch](#tag/Development-Branches). This makes a new version of the configuration\nand the configuration becomes available for other API calls.\n\nThe response does not include `configuration`, `state`, `rowsSortOrder` and `rows`.\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "post_/v2/storage/components/{componentId}/configs/{configurationId}/restore::ConfigurationRestoreAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" } ], "responses": { "200": { "description": "Restored configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationPartialResponse" }, "example": { "id": "236606822", "name": "My new configuration", "description": "", "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "version": 4, "changeDescription": "Configuration restored", "isDisabled": false, "isDeleted": false, "currentVersion": { "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Configuration restored", "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S" } } } } }, "403": { "description": "Token is not allowed to manage the component, or orchestrator creation is disabled for the project (`orchestrator.creationDisabled`)." }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/state": { "put": { "tags": [ "Components and Configurations" ], "summary": "Update Configuration State", "description": "Updates state of an existing configuration for [Development Branch](#tag/Development-Branches).\nWriting `state` does not create a new configuration version.\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "put_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/state::ConfigurationStateUpdateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateConfigurationStateRequest" } ] } } } }, "responses": { "200": { "description": "Configuration with the updated state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationResponse" }, "example": { "id": "236606822", "name": "My new configuration", "description": "", "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "version": 2, "changeDescription": "Added new key", "isDisabled": false, "isDeleted": false, "configuration": { "key": "value", "key2": "value2", "key3": "value3" }, "rowsSortOrder": [], "rows": [], "state": { "lastId": 123 }, "currentVersion": { "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Added new key", "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S" } } } } }, "400": { "description": "Invalid request body: `state` is missing, not valid JSON, or extra properties were sent." }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." } } } }, "/v2/storage/components/{componentId}/configs/{configurationId}/state": { "put": { "tags": [ "Components and Configurations" ], "summary": "Update Configuration State", "description": "Updates state of an existing configuration for [Development Branch](#tag/Development-Branches).\nWriting `state` does not create a new configuration version.\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "put_/v2/storage/components/{componentId}/configs/{configurationId}/state::ConfigurationStateUpdateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateConfigurationStateRequest" } ] } } } }, "responses": { "200": { "description": "Configuration with the updated state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationResponse" }, "example": { "id": "236606822", "name": "My new configuration", "description": "", "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "version": 2, "changeDescription": "Added new key", "isDisabled": false, "isDeleted": false, "configuration": { "key": "value", "key2": "value2", "key3": "value3" }, "rowsSortOrder": [], "rows": [], "state": { "lastId": 123 }, "currentVersion": { "created": "2017-02-14T14:38:26+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Added new key", "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S" } } } } }, "400": { "description": "Invalid request body: `state` is missing, not valid JSON, or extra properties were sent." }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/workspaces": { "get": { "tags": [ "Components and Configurations" ], "summary": "Workspace List", "description": "Returns all workspaces for the component configuration in [Development Branch](#tag/Development-Branches).\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "get_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/workspaces::ConfigurationWorkspacesListAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspaces linked to the configuration.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceDetailResponse" } }, "example": [ { "id": 78423, "type": "table", "name": "WORKSPACE_78423", "component": "keboola.ex-db-mysql", "configurationId": "main-1", "created": "2018-01-19T14:55:38+0100", "connection": { "backend": "snowflake", "region": "us-east-1", "host": "keboola.snowflakecomputing.com", "database": "KEBOOLA_123", "schema": "WORKSPACE_78423", "warehouse": "KEBOOLA_PROD", "user": "KEBOOLA_WORKSPACE_78423", "loginType": "default" }, "backendSize": null, "statementTimeoutSeconds": 7200, "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": null }, "readOnlyStorageAccess": false, "platformUsageType": null, "state": "active", "deactivateAt": null, "deleteAt": null } ] } } }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." } } }, "post": { "tags": [ "Workspaces" ], "summary": "Create workspace", "description": "Creates a new workspace and returns its credentials. Workspaces provide a playground for your data. You can load data\nfrom your storage, explore or modify it and then, optionally, load it back to storage tables. A workspace is represented\nby access credentials to a storage backend with permissions to write to the workspace specific database schema.\n\nSet `async=true` to create the workspace in a background job. Calling the endpoint with `async=false` is deprecated.\n\nTo create a workspace bound to a component configuration (including a reader workspace), use the\n`/components/{componentId}/configs/{configurationId}/workspaces` variant of this endpoint.\n\nAll workspaces endpoints can be used with `default` for the `branchId` parameter, which emulates the call without\na development branch: `GET /v2/storage/workspaces` is the same as `GET /v2/storage/branch/default/workspaces`.", "operationId": "post_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/workspaces::WorkspaceCreateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Component identifier. Only for the configuration workspace variant of the endpoint.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "keboola.snowflake-transformation" }, { "name": "configurationId", "in": "path", "description": "Configuration identifier. Only for the configuration workspace variant of the endpoint.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "1234567890" }, { "name": "async", "in": "query", "description": "Create workspace in a background job. Calling the parameter as `async=false` is deprecated.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true }, { "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": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateWorkspaceRequest" } ] } } } }, "responses": { "201": { "description": "Synchronous call response (`async=false`). The password (or key/connection string) is returned only here and cannot be retrieved later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCreatedResponse" }, "example": { "id": 234, "type": "table", "name": "boring_wozniak", "component": "wr-db", "configurationId": "aws-1", "configurationVersion": null, "created": "2016-05-17T11:11:20+0200", "connection": { "backend": "snowflake", "region": "us-east1", "host": "keboola.snowflakecomputing.com", "database": "keboola_123", "schema": "boring_wozniak", "warehouse": "SAPI_PROD", "user": "xzy", "loginType": "default", "ssoLoginAvailable": false, "password": "abc", "account": "keboola", "role": "boring_wozniak" }, "backendSize": "small", "statementTimeoutSeconds": 0, "creatorToken": { "id": 234, "description": "martin@keboola.com" }, "actor": { "type": "token", "id": "234", "name": "martin@keboola.com", "adminId": null }, "readOnlyStorageAccess": true, "platformUsageType": "user", "state": "active", "deactivateAt": null, "deleteAt": null } } } }, "202": { "description": "Asynchronous call response (`async=true`) that creates a new `workspaceCreate` job. To see the job detail use the Job Detail endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "workspaceCreate", "operationParams": { "backend": "snowflake", "branchId": 1 }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" } } } } }, "400": { "description": "Returned when the request is invalid, e.g. unsupported backend or backend size (`workspace.backendNotSupported`), dynamic backend size feature not enabled, invalid reader/direct-grant configuration, or a backend driver error." }, "403": { "description": "Returned when the token lacks write access to a direct grant output mapping bucket, or when the user has the read-only role in the project." }, "404": { "description": "Returned when the component or configuration is not found (configuration workspace variant only)." }, "501": { "description": "Returned when creating a configuration workspace in a Snowflake Partner Connect limited project." } } } }, "/v2/storage/components/{componentId}/configs/{configurationId}/workspaces": { "get": { "tags": [ "Components and Configurations" ], "summary": "Workspace List", "description": "Returns all workspaces for the component configuration in [Development Branch](#tag/Development-Branches).\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "get_/v2/storage/components/{componentId}/configs/{configurationId}/workspaces::ConfigurationWorkspacesListAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" } ], "responses": { "200": { "description": "Workspaces linked to the configuration.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceDetailResponse" } }, "example": [ { "id": 78423, "type": "table", "name": "WORKSPACE_78423", "component": "keboola.ex-db-mysql", "configurationId": "main-1", "created": "2018-01-19T14:55:38+0100", "connection": { "backend": "snowflake", "region": "us-east-1", "host": "keboola.snowflakecomputing.com", "database": "KEBOOLA_123", "schema": "WORKSPACE_78423", "warehouse": "KEBOOLA_PROD", "user": "KEBOOLA_WORKSPACE_78423", "loginType": "default" }, "backendSize": null, "statementTimeoutSeconds": 7200, "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": null }, "readOnlyStorageAccess": false, "platformUsageType": null, "state": "active", "deactivateAt": null, "deleteAt": null } ] } } }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." } } }, "post": { "tags": [ "Workspaces" ], "summary": "Create workspace", "description": "Creates a new workspace and returns its credentials. Workspaces provide a playground for your data. You can load data\nfrom your storage, explore or modify it and then, optionally, load it back to storage tables. A workspace is represented\nby access credentials to a storage backend with permissions to write to the workspace specific database schema.\n\nSet `async=true` to create the workspace in a background job. Calling the endpoint with `async=false` is deprecated.\n\nTo create a workspace bound to a component configuration (including a reader workspace), use the\n`/components/{componentId}/configs/{configurationId}/workspaces` variant of this endpoint.\n\nAll workspaces endpoints can be used with `default` for the `branchId` parameter, which emulates the call without\na development branch: `GET /v2/storage/workspaces` is the same as `GET /v2/storage/branch/default/workspaces`.", "operationId": "post_/v2/storage/components/{componentId}/configs/{configurationId}/workspaces::WorkspaceCreateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Component identifier. Only for the configuration workspace variant of the endpoint.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "keboola.snowflake-transformation" }, { "name": "configurationId", "in": "path", "description": "Configuration identifier. Only for the configuration workspace variant of the endpoint.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "1234567890" }, { "name": "async", "in": "query", "description": "Create workspace in a background job. Calling the parameter as `async=false` is deprecated.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true }, { "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/CreateWorkspaceRequest" } ] } } } }, "responses": { "201": { "description": "Synchronous call response (`async=false`). The password (or key/connection string) is returned only here and cannot be retrieved later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCreatedResponse" }, "example": { "id": 234, "type": "table", "name": "boring_wozniak", "component": "wr-db", "configurationId": "aws-1", "configurationVersion": null, "created": "2016-05-17T11:11:20+0200", "connection": { "backend": "snowflake", "region": "us-east1", "host": "keboola.snowflakecomputing.com", "database": "keboola_123", "schema": "boring_wozniak", "warehouse": "SAPI_PROD", "user": "xzy", "loginType": "default", "ssoLoginAvailable": false, "password": "abc", "account": "keboola", "role": "boring_wozniak" }, "backendSize": "small", "statementTimeoutSeconds": 0, "creatorToken": { "id": 234, "description": "martin@keboola.com" }, "actor": { "type": "token", "id": "234", "name": "martin@keboola.com", "adminId": null }, "readOnlyStorageAccess": true, "platformUsageType": "user", "state": "active", "deactivateAt": null, "deleteAt": null } } } }, "202": { "description": "Asynchronous call response (`async=true`) that creates a new `workspaceCreate` job. To see the job detail use the Job Detail endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "workspaceCreate", "operationParams": { "backend": "snowflake", "branchId": 1 }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" } } } } }, "400": { "description": "Returned when the request is invalid, e.g. unsupported backend or backend size (`workspace.backendNotSupported`), dynamic backend size feature not enabled, invalid reader/direct-grant configuration, or a backend driver error." }, "403": { "description": "Returned when the token lacks write access to a direct grant output mapping bucket, or when the user has the read-only role in the project." }, "404": { "description": "Returned when the component or configuration is not found (configuration workspace variant only)." }, "501": { "description": "Returned when creating a configuration workspace in a Snowflake Partner Connect limited project." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/metadata": { "get": { "tags": [ "Metadata" ], "summary": "List configuration metadata", "description": "Metadata can be listed for your component configuration.\n\nAll requests must include the branch (`/branch/{branchId}`) in the URL. This is also true for default (production) branch.", "operationId": "get_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/metadata::ConfigurationMetadataListAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Configuration metadata.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationMetadataResponse" } }, "example": [ { "id": "123", "key": "attribute_key", "value": "attribute_value", "timestamp": "2016-09-19T13:02:11+0200" }, { "id": "124", "key": "another_attribute_key", "value": "attribute_value", "timestamp": "2016-09-19T13:02:11+0200" } ] } } }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." } } }, "post": { "tags": [ "Metadata" ], "summary": "Create or Update configuration metadata", "description": "Sets multiple metadata with one call. If the given key and provider combination already exist\nfor the configuration, the data will be updated with the new value and timestamp. All metadata associated\nwith the configuration are returned in the response.\n\nAll requests must include the branch (`/branch/{branchId}`) in the URL. This is also true for default (production) branch. You can find out the id of your default branch by calling [List Branches](#tag/Development-Branches) and finding branch with attribute `isDefault` set to `true`.", "operationId": "post_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/metadata::ConfigurationMetadataCreateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "metadata" ], "properties": { "metadata": { "description": "Array of metadata objects.", "type": "array", "items": { "required": [ "key", "value" ], "properties": { "key": { "description": "Metadata key; allowed characters `a-zA-Z0-9_.-`.", "type": "string", "example": "some-key" }, "value": { "description": "Metadata value.", "type": "string", "example": "Some value" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "201": { "description": "All metadata of the configuration after the upsert.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationMetadataResponse" } }, "example": [ { "id": "19509", "key": "some-key", "value": "Some value", "timestamp": "2017-02-13T23:36:10+0100" } ] } } }, "400": { "description": "Invalid metadata payload (`validation.failed`), including a `KBC.configuration.folderName` value longer than 400 characters after trimming." }, "403": { "description": "Token is not allowed to create configuration metadata." }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." }, "409": { "description": "Another request is mid-write on the configuration folder; retryable (`storage.components.configurations.versionConflict`)." } } } }, "/v2/storage/components/{componentId}/configs/{configurationId}/metadata": { "get": { "tags": [ "Metadata" ], "summary": "List configuration metadata", "description": "Metadata can be listed for your component configuration.\n\nAll requests must include the branch (`/branch/{branchId}`) in the URL. This is also true for default (production) branch.", "operationId": "get_/v2/storage/components/{componentId}/configs/{configurationId}/metadata::ConfigurationMetadataListAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" } ], "responses": { "200": { "description": "Configuration metadata.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationMetadataResponse" } }, "example": [ { "id": "123", "key": "attribute_key", "value": "attribute_value", "timestamp": "2016-09-19T13:02:11+0200" }, { "id": "124", "key": "another_attribute_key", "value": "attribute_value", "timestamp": "2016-09-19T13:02:11+0200" } ] } } }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." } } }, "post": { "tags": [ "Metadata" ], "summary": "Create or Update configuration metadata", "description": "Sets multiple metadata with one call. If the given key and provider combination already exist\nfor the configuration, the data will be updated with the new value and timestamp. All metadata associated\nwith the configuration are returned in the response.\n\nAll requests must include the branch (`/branch/{branchId}`) in the URL. This is also true for default (production) branch. You can find out the id of your default branch by calling [List Branches](#tag/Development-Branches) and finding branch with attribute `isDefault` set to `true`.", "operationId": "post_/v2/storage/components/{componentId}/configs/{configurationId}/metadata::ConfigurationMetadataCreateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "metadata" ], "properties": { "metadata": { "description": "Array of metadata objects.", "type": "array", "items": { "required": [ "key", "value" ], "properties": { "key": { "description": "Metadata key; allowed characters `a-zA-Z0-9_.-`.", "type": "string", "example": "some-key" }, "value": { "description": "Metadata value.", "type": "string", "example": "Some value" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "201": { "description": "All metadata of the configuration after the upsert.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationMetadataResponse" } }, "example": [ { "id": "19509", "key": "some-key", "value": "Some value", "timestamp": "2017-02-13T23:36:10+0100" } ] } } }, "400": { "description": "Invalid metadata payload (`validation.failed`), including a `KBC.configuration.folderName` value longer than 400 characters after trimming." }, "403": { "description": "Token is not allowed to create configuration metadata." }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." }, "409": { "description": "Another request is mid-write on the configuration folder; retryable (`storage.components.configurations.versionConflict`)." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/metadata/{metadataId}": { "delete": { "tags": [ "Metadata" ], "summary": "Delete configuration metadata", "description": "Deletes the specified metadata item from the component configuration.\n\nOnly available on the default branch.", "operationId": "delete_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/metadata/{metadataId}::ConfigurationMetadataDeleteAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "metadataId", "in": "path", "description": "Id of the metadata entry.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 19509 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Metadata deleted." }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`) or metadata entry (`storage.componentConfigurations.metadataNotFound`) not found." }, "409": { "description": "Another request is mid-write on the configuration folder; retryable (`storage.components.configurations.versionConflict`)." }, "501": { "description": "Called on a development branch (`notImplemented`)." } } } }, "/v2/storage/components/{componentId}/configs/{configurationId}/metadata/{metadataId}": { "delete": { "tags": [ "Metadata" ], "summary": "Delete configuration metadata", "description": "Deletes the specified metadata item from the component configuration.\n\nOnly available on the default branch.", "operationId": "delete_/v2/storage/components/{componentId}/configs/{configurationId}/metadata/{metadataId}::ConfigurationMetadataDeleteAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "metadataId", "in": "path", "description": "Id of the metadata entry.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 19509 } ], "responses": { "204": { "description": "Metadata deleted." }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`) or metadata entry (`storage.componentConfigurations.metadataNotFound`) not found." }, "409": { "description": "Another request is mid-write on the configuration folder; retryable (`storage.components.configurations.versionConflict`)." }, "501": { "description": "Called on a development branch (`notImplemented`)." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/rows": { "get": { "tags": [ "Components and Configurations" ], "summary": "Configuration Row List", "description": "Gets configuration rows for Development Branch (see the *Development Branches* section).\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "get_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/rows::ConfigurationRowListAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of configuration rows.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationRowResponse" } }, "example": [ { "id": "236781529", "name": "", "description": "", "isDisabled": false, "version": 1, "created": "2017-02-15T00:04:42+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Row 236781529 added", "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P", "state": [], "configuration": [] }, { "id": "236781639", "name": "", "description": "", "isDisabled": false, "version": 1, "created": "2017-02-15T00:05:29+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Added new row", "versionIdentifier": "01H5PWX76CG19RAKJW4Q8WMFST", "state": [], "configuration": { "host": "localhost", "port": 4406 } } ] } } }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." } } }, "post": { "tags": [ "Components and Configurations" ], "summary": "Create Configuration Row", "description": "Creates a new row (item) of an existing configuration in Development Branch (see the *Development Branches* section).\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "post_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/rows::ConfigurationRowCreateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateConfigurationRowRequest" } ] } } } }, "responses": { "201": { "description": "Created configuration row.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationRowResponse" }, "example": { "id": "236781646", "name": "", "description": "", "isDisabled": false, "version": 1, "created": "2017-02-15T00:05:32+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Added new row", "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P", "state": [], "configuration": { "host": "localhost", "port": 4406 } } } } }, "400": { "description": "Validation error (`storage.componentsRows.validation`, `validation.invalidConfigurationFormat`, `validation.invalidStateFormat`) or a row with the given `rowId` already exists (`configurationRowAlreadyExists`)." }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." }, "409": { "description": "Concurrent modification of the configuration (`storage.components.configurations.versionConflict`); retry the request." } } } }, "/v2/storage/components/{componentId}/configs/{configurationId}/rows": { "get": { "tags": [ "Components and Configurations" ], "summary": "Configuration Row List", "description": "Gets configuration rows for Development Branch (see the *Development Branches* section).\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "get_/v2/storage/components/{componentId}/configs/{configurationId}/rows::ConfigurationRowListAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" } ], "responses": { "200": { "description": "List of configuration rows.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationRowResponse" } }, "example": [ { "id": "236781529", "name": "", "description": "", "isDisabled": false, "version": 1, "created": "2017-02-15T00:04:42+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Row 236781529 added", "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P", "state": [], "configuration": [] }, { "id": "236781639", "name": "", "description": "", "isDisabled": false, "version": 1, "created": "2017-02-15T00:05:29+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Added new row", "versionIdentifier": "01H5PWX76CG19RAKJW4Q8WMFST", "state": [], "configuration": { "host": "localhost", "port": 4406 } } ] } } }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." } } }, "post": { "tags": [ "Components and Configurations" ], "summary": "Create Configuration Row", "description": "Creates a new row (item) of an existing configuration in Development Branch (see the *Development Branches* section).\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "post_/v2/storage/components/{componentId}/configs/{configurationId}/rows::ConfigurationRowCreateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateConfigurationRowRequest" } ] } } } }, "responses": { "201": { "description": "Created configuration row.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationRowResponse" }, "example": { "id": "236781646", "name": "", "description": "", "isDisabled": false, "version": 1, "created": "2017-02-15T00:05:32+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Added new row", "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P", "state": [], "configuration": { "host": "localhost", "port": 4406 } } } } }, "400": { "description": "Validation error (`storage.componentsRows.validation`, `validation.invalidConfigurationFormat`, `validation.invalidStateFormat`) or a row with the given `rowId` already exists (`configurationRowAlreadyExists`)." }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." }, "409": { "description": "Concurrent modification of the configuration (`storage.components.configurations.versionConflict`); retry the request." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/rows/{rowId}": { "get": { "tags": [ "Components and Configurations" ], "summary": "Configuration Row detail", "description": "Gets a single configuration row for Development Branch (see the *Development Branches* section).\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "get_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/rows/{rowId}::ConfigurationRowDetailAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" }, { "name": "rowId", "in": "path", "description": "ID of the configuration row.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236781529" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Configuration row detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationRowResponse" }, "example": { "id": "236781529", "name": "", "description": "", "isDisabled": false, "version": 1, "created": "2017-02-15T00:04:42+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Row 236781529 added", "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P", "state": [], "configuration": [] } } } }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`) or row (`notFound`) not found." } } }, "put": { "tags": [ "Components and Configurations" ], "summary": "Update Configuration Row", "description": "Modifies the content of a single row in Development Branch (see the *Development Branches* section). Note that configuration rows are versioned independently on the configurations.\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "put_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/rows/{rowId}::ConfigurationRowUpdateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" }, { "name": "rowId", "in": "path", "description": "ID of the configuration row.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236781529" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateConfigurationRowRequest" } ] } } } }, "responses": { "200": { "description": "Updated configuration row.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationRowResponse" }, "example": { "id": "236781529", "name": "", "description": "", "isDisabled": false, "version": 2, "created": "2017-02-15T00:04:42+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "change description", "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P", "state": [], "configuration": { "host": "localhost", "port": null } } } } }, "400": { "description": "Validation error (`storage.componentsRows.validation`, `validation.invalidConfigurationFormat`) or `state` sent in the body (`validation.invalidConfigurationRowParameter`)." }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`) or row (`notFound`) not found." }, "409": { "description": "Concurrent modification of the configuration (`storage.components.configurations.versionConflict`); retry the request." } } }, "delete": { "tags": [ "Components and Configurations" ], "summary": "Delete Configuration Row", "description": "Deletes a configuration row for Development Branch (see the *Development Branches* section). A configuration row is deleted permanently and cannot be restored.\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "delete_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/rows/{rowId}::ConfigurationRowDeleteAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" }, { "name": "rowId", "in": "path", "description": "ID of the configuration row.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236781529" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DeleteConfigurationRowRequest" } ] } } } }, "responses": { "204": { "description": "Configuration row deleted." }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`) or row (`notFound`) not found." } } } }, "/v2/storage/components/{componentId}/configs/{configurationId}/rows/{rowId}": { "get": { "tags": [ "Components and Configurations" ], "summary": "Configuration Row detail", "description": "Gets a single configuration row for Development Branch (see the *Development Branches* section).\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "get_/v2/storage/components/{componentId}/configs/{configurationId}/rows/{rowId}::ConfigurationRowDetailAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" }, { "name": "rowId", "in": "path", "description": "ID of the configuration row.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236781529" } ], "responses": { "200": { "description": "Configuration row detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationRowResponse" }, "example": { "id": "236781529", "name": "", "description": "", "isDisabled": false, "version": 1, "created": "2017-02-15T00:04:42+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Row 236781529 added", "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P", "state": [], "configuration": [] } } } }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`) or row (`notFound`) not found." } } }, "put": { "tags": [ "Components and Configurations" ], "summary": "Update Configuration Row", "description": "Modifies the content of a single row in Development Branch (see the *Development Branches* section). Note that configuration rows are versioned independently on the configurations.\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "put_/v2/storage/components/{componentId}/configs/{configurationId}/rows/{rowId}::ConfigurationRowUpdateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" }, { "name": "rowId", "in": "path", "description": "ID of the configuration row.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236781529" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateConfigurationRowRequest" } ] } } } }, "responses": { "200": { "description": "Updated configuration row.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationRowResponse" }, "example": { "id": "236781529", "name": "", "description": "", "isDisabled": false, "version": 2, "created": "2017-02-15T00:04:42+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "change description", "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P", "state": [], "configuration": { "host": "localhost", "port": null } } } } }, "400": { "description": "Validation error (`storage.componentsRows.validation`, `validation.invalidConfigurationFormat`) or `state` sent in the body (`validation.invalidConfigurationRowParameter`)." }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`) or row (`notFound`) not found." }, "409": { "description": "Concurrent modification of the configuration (`storage.components.configurations.versionConflict`); retry the request." } } }, "delete": { "tags": [ "Components and Configurations" ], "summary": "Delete Configuration Row", "description": "Deletes a configuration row for Development Branch (see the *Development Branches* section). A configuration row is deleted permanently and cannot be restored.\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "delete_/v2/storage/components/{componentId}/configs/{configurationId}/rows/{rowId}::ConfigurationRowDeleteAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" }, { "name": "rowId", "in": "path", "description": "ID of the configuration row.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236781529" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DeleteConfigurationRowRequest" } ] } } } }, "responses": { "204": { "description": "Configuration row deleted." }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`) or row (`notFound`) not found." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/rows/{rowId}/state": { "put": { "tags": [ "Components and Configurations" ], "summary": "Update Configuration Row State", "description": "Updates state of an existing configuration row for Development Branch (see the *Development Branches* section).\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "put_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/rows/{rowId}/state::ConfigurationRowStateUpdateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" }, { "name": "rowId", "in": "path", "description": "ID of the configuration row.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236781529" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateConfigurationRowStateRequest" } ] } } } }, "responses": { "200": { "description": "Configuration row with the updated state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationRowResponse" }, "example": { "id": "236781529", "name": "", "description": "", "isDisabled": false, "version": 2, "created": "2017-02-15T00:04:42+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "change description", "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P", "state": { "lastId": 123 }, "configuration": { "host": "localhost", "port": null } } } } }, "400": { "description": "Missing or invalid `state` (`storage.componentsRows.validation`, `validation.invalidStateFormat`)." }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`) or row (`notFound`) not found." } } } }, "/v2/storage/components/{componentId}/configs/{configurationId}/rows/{rowId}/state": { "put": { "tags": [ "Components and Configurations" ], "summary": "Update Configuration Row State", "description": "Updates state of an existing configuration row for Development Branch (see the *Development Branches* section).\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "put_/v2/storage/components/{componentId}/configs/{configurationId}/rows/{rowId}/state::ConfigurationRowStateUpdateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" }, { "name": "rowId", "in": "path", "description": "ID of the configuration row.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236781529" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateConfigurationRowStateRequest" } ] } } } }, "responses": { "200": { "description": "Configuration row with the updated state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationRowResponse" }, "example": { "id": "236781529", "name": "", "description": "", "isDisabled": false, "version": 2, "created": "2017-02-15T00:04:42+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "change description", "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P", "state": { "lastId": 123 }, "configuration": { "host": "localhost", "port": null } } } } }, "400": { "description": "Missing or invalid `state` (`storage.componentsRows.validation`, `validation.invalidStateFormat`)." }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`) or row (`notFound`) not found." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/rows/{rowId}/versions/{versionId}/create": { "post": { "tags": [ "Components and Configurations" ], "summary": "Create Configuration Row copy", "description": "Creates a new configuration row from an existing row version in Development Branch (see the *Development Branches* section).\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "post_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/rows/{rowId}/versions/{versionId}/create::RowVersionCreateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" }, { "name": "rowId", "in": "path", "description": "ID of the configuration row.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236781529" }, { "name": "versionId", "in": "path", "description": "ID of the configuration row version to copy from.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 1 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateConfigurationRowVersionRequest" } ] } } } }, "responses": { "201": { "description": "Newly created configuration row.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationRowResponse" }, "example": { "id": "236791247", "name": "", "description": "", "isDisabled": false, "version": 1, "created": "2017-02-15T00:38:58+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Copy to another row", "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P", "state": [], "configuration": { "host": "localhost", "port": 4406 } } } } }, "400": { "description": "Validation error." }, "404": { "description": "Component (`storage.component.notFound`), source or target configuration (`storage.configuration.notFound`), row or version (`notFound`) not found." } } } }, "/v2/storage/components/{componentId}/configs/{configurationId}/rows/{rowId}/versions/{versionId}/create": { "post": { "tags": [ "Components and Configurations" ], "summary": "Create Configuration Row copy", "description": "Creates a new configuration row from an existing row version in Development Branch (see the *Development Branches* section).\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "post_/v2/storage/components/{componentId}/configs/{configurationId}/rows/{rowId}/versions/{versionId}/create::RowVersionCreateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" }, { "name": "rowId", "in": "path", "description": "ID of the configuration row.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236781529" }, { "name": "versionId", "in": "path", "description": "ID of the configuration row version to copy from.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateConfigurationRowVersionRequest" } ] } } } }, "responses": { "201": { "description": "Newly created configuration row.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationRowResponse" }, "example": { "id": "236791247", "name": "", "description": "", "isDisabled": false, "version": 1, "created": "2017-02-15T00:38:58+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Copy to another row", "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P", "state": [], "configuration": { "host": "localhost", "port": 4406 } } } } }, "400": { "description": "Validation error." }, "404": { "description": "Component (`storage.component.notFound`), source or target configuration (`storage.configuration.notFound`), row or version (`notFound`) not found." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/rows/{rowId}/versions/{versionId}": { "get": { "tags": [ "Components and Configurations" ], "summary": "Version detail", "description": "Gets details about the configuration row version.\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "get_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/rows/{rowId}/versions/{versionId}::RowVersionDetailAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" }, { "name": "rowId", "in": "path", "description": "ID of the configuration row.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236781529" }, { "name": "versionId", "in": "path", "description": "ID of the configuration row version.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 1 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Configuration row version detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationRowVersionResponse" }, "example": { "id": "236781529", "name": "", "description": "", "isDisabled": false, "version": 1, "created": "2015-08-10T22:00:55+0200", "creatorToken": { "id": 1392, "description": "martin@keboola.com" }, "actor": { "type": "token", "id": "1392", "name": "martin@keboola.com", "adminId": 1234 }, "changeDescription": "Some other cause of the change", "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P", "configuration": [] } } } }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`), row or version (`notFound`) not found." } } } }, "/v2/storage/components/{componentId}/configs/{configurationId}/rows/{rowId}/versions/{versionId}": { "get": { "tags": [ "Components and Configurations" ], "summary": "Version detail", "description": "Gets details about the configuration row version.\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "get_/v2/storage/components/{componentId}/configs/{configurationId}/rows/{rowId}/versions/{versionId}::RowVersionDetailAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" }, { "name": "rowId", "in": "path", "description": "ID of the configuration row.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236781529" }, { "name": "versionId", "in": "path", "description": "ID of the configuration row version.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 1 } ], "responses": { "200": { "description": "Configuration row version detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationRowVersionResponse" }, "example": { "id": "236781529", "name": "", "description": "", "isDisabled": false, "version": 1, "created": "2015-08-10T22:00:55+0200", "creatorToken": { "id": 1392, "description": "martin@keboola.com" }, "actor": { "type": "token", "id": "1392", "name": "martin@keboola.com", "adminId": 1234 }, "changeDescription": "Some other cause of the change", "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P", "configuration": [] } } } }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`), row or version (`notFound`) not found." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/rows/{rowId}/versions": { "get": { "tags": [ "Components and Configurations" ], "summary": "Versions list", "description": "List versions of a given configuration row of a given configuration for Development Branch (see the *Development Branches* section).\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "get_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/rows/{rowId}/versions::RowVersionListAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" }, { "name": "rowId", "in": "path", "description": "ID of the configuration row.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236781529" }, { "name": "include", "in": "query", "description": "Comma separated list of information to retrieve; it may contain: `configuration`.", "required": false, "schema": { "type": "string" }, "example": "configuration" }, { "name": "limit", "in": "query", "description": "Pagination limit.", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1 }, "example": 100 }, { "name": "offset", "in": "query", "description": "Pagination offset.", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "example": 0 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of configuration row versions.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationRowVersionListItemResponse" } }, "example": [ { "id": "236781529", "name": "", "description": "", "isDisabled": false, "version": 2, "created": "2015-08-12T12:33:04+0200", "creatorToken": { "id": 1392, "description": "martin@keboola.com" }, "actor": { "type": "token", "id": "1392", "name": "martin@keboola.com", "adminId": 1234 }, "changeDescription": "Cause of the change", "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P" }, { "id": "236781529", "name": "", "description": "", "isDisabled": false, "version": 1, "created": "2015-08-10T22:00:55+0200", "creatorToken": { "id": 1392, "description": "martin@keboola.com" }, "actor": { "type": "token", "id": "1392", "name": "martin@keboola.com", "adminId": 1234 }, "changeDescription": "Some other cause of the change", "versionIdentifier": "01H5PWX76CG19RAKJW4Q8WMFST" } ] } } }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`) or row (`notFound`) not found." } } } }, "/v2/storage/components/{componentId}/configs/{configurationId}/rows/{rowId}/versions": { "get": { "tags": [ "Components and Configurations" ], "summary": "Versions list", "description": "List versions of a given configuration row of a given configuration for Development Branch (see the *Development Branches* section).\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "get_/v2/storage/components/{componentId}/configs/{configurationId}/rows/{rowId}/versions::RowVersionListAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" }, { "name": "rowId", "in": "path", "description": "ID of the configuration row.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236781529" }, { "name": "include", "in": "query", "description": "Comma separated list of information to retrieve; it may contain: `configuration`.", "required": false, "schema": { "type": "string" }, "example": "configuration" }, { "name": "limit", "in": "query", "description": "Pagination limit.", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1 }, "example": 100 }, { "name": "offset", "in": "query", "description": "Pagination offset.", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "example": 0 } ], "responses": { "200": { "description": "List of configuration row versions.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationRowVersionListItemResponse" } }, "example": [ { "id": "236781529", "name": "", "description": "", "isDisabled": false, "version": 2, "created": "2015-08-12T12:33:04+0200", "creatorToken": { "id": 1392, "description": "martin@keboola.com" }, "actor": { "type": "token", "id": "1392", "name": "martin@keboola.com", "adminId": 1234 }, "changeDescription": "Cause of the change", "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P" }, { "id": "236781529", "name": "", "description": "", "isDisabled": false, "version": 1, "created": "2015-08-10T22:00:55+0200", "creatorToken": { "id": 1392, "description": "martin@keboola.com" }, "actor": { "type": "token", "id": "1392", "name": "martin@keboola.com", "adminId": 1234 }, "changeDescription": "Some other cause of the change", "versionIdentifier": "01H5PWX76CG19RAKJW4Q8WMFST" } ] } } }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`) or row (`notFound`) not found." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/rows/{rowId}/versions/{versionId}/rollback": { "post": { "tags": [ "Components and Configurations" ], "summary": "Rollback Version", "description": "Rollbacks row to a previous version. This operation actually creates a new row version with identical content to be rollbacked to.\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "post_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/rows/{rowId}/versions/{versionId}/rollback::RowVersionRollbackAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" }, { "name": "rowId", "in": "path", "description": "ID of the configuration row.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236781529" }, { "name": "versionId", "in": "path", "description": "ID of the configuration row version to rollback to.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 1 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RollbackConfigurationRowRequest" } ] } } } }, "responses": { "201": { "description": "Configuration row after the rollback (new version).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationRowResponse" }, "example": { "id": "236781646", "name": "", "description": "", "isDisabled": false, "version": 2, "created": "2017-02-15T00:05:32+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Rollback to previous version", "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P", "state": [], "configuration": { "host": "localhost", "port": 4406 } } } } }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`), row or version (`notFound`) not found." } } } }, "/v2/storage/components/{componentId}/configs/{configurationId}/rows/{rowId}/versions/{versionId}/rollback": { "post": { "tags": [ "Components and Configurations" ], "summary": "Rollback Version", "description": "Rollbacks row to a previous version. This operation actually creates a new row version with identical content to be rollbacked to.\n\nThe variant without `branch/{branchId}` in the URL is **deprecated**; use the branch endpoint with `branch/default`.", "operationId": "post_/v2/storage/components/{componentId}/configs/{configurationId}/rows/{rowId}/versions/{versionId}/rollback::RowVersionRollbackAction", "parameters": [ { "name": "componentId", "in": "path", "description": "ID of the component, e.g. `keboola.ex-db-mysql`.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "ID of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236606822" }, { "name": "rowId", "in": "path", "description": "ID of the configuration row.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "236781529" }, { "name": "versionId", "in": "path", "description": "ID of the configuration row version to rollback to.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RollbackConfigurationRowRequest" } ] } } } }, "responses": { "201": { "description": "Configuration row after the rollback (new version).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationRowResponse" }, "example": { "id": "236781646", "name": "", "description": "", "isDisabled": false, "version": 2, "created": "2017-02-15T00:05:32+0100", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Rollback to previous version", "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P", "state": [], "configuration": { "host": "localhost", "port": 4406 } } } } }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`), row or version (`notFound`) not found." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/versions/{versionId}/create": { "post": { "tags": [ "Components and Configurations" ], "summary": "Create Configuration Copy", "description": "Creates a new configuration from the specified configuration version in [Development Branch](#tag/Development-Branches).\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "post_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/versions/{versionId}/create::ConfigurationVersionCreateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration to copy.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "versionId", "in": "path", "description": "Version number to copy.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 2 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateConfigurationVersionRequest" } ] } } } }, "responses": { "201": { "description": "New configuration created from the version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationCopyResponse" }, "example": { "id": "236606823" } } } }, "400": { "description": "Invalid request body (`name` is required)." }, "403": { "description": "Orchestrator creation is disabled for the project (`orchestrator.creationDisabled`)." }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." } } } }, "/v2/storage/components/{componentId}/configs/{configurationId}/versions/{versionId}/create": { "post": { "tags": [ "Components and Configurations" ], "summary": "Create Configuration Copy", "description": "Creates a new configuration from the specified configuration version in [Development Branch](#tag/Development-Branches).\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "post_/v2/storage/components/{componentId}/configs/{configurationId}/versions/{versionId}/create::ConfigurationVersionCreateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration to copy.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "versionId", "in": "path", "description": "Version number to copy.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 2 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateConfigurationVersionRequest" } ] } } } }, "responses": { "201": { "description": "New configuration created from the version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationCopyResponse" }, "example": { "id": "236606823" } } } }, "400": { "description": "Invalid request body (`name` is required)." }, "403": { "description": "Orchestrator creation is disabled for the project (`orchestrator.creationDisabled`)." }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/versions/{versionId}": { "get": { "tags": [ "Components and Configurations" ], "summary": "Version Detail", "description": "Gets configuration version for [Development Branch](#tag/Development-Branches). The response includes `name`, `description`, `configuration`, `rowsSortOrder` and `rows` as of that version.\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "get_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/versions/{versionId}::ConfigurationVersionDetailAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "versionId", "in": "path", "description": "Version number.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 2 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Configuration version detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationVersionDetailResponse" }, "example": { "version": 1, "created": "2017-02-09T21:10:31+0100", "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "", "isDisabled": false, "isDeleted": false, "name": "test", "description": "", "configuration": [], "rowsSortOrder": [], "rows": [] } } } }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`) or version (`notFound`) not found." } } } }, "/v2/storage/components/{componentId}/configs/{configurationId}/versions/{versionId}": { "get": { "tags": [ "Components and Configurations" ], "summary": "Version Detail", "description": "Gets configuration version for [Development Branch](#tag/Development-Branches). The response includes `name`, `description`, `configuration`, `rowsSortOrder` and `rows` as of that version.\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "get_/v2/storage/components/{componentId}/configs/{configurationId}/versions/{versionId}::ConfigurationVersionDetailAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "versionId", "in": "path", "description": "Version number.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 2 } ], "responses": { "200": { "description": "Configuration version detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationVersionDetailResponse" }, "example": { "version": 1, "created": "2017-02-09T21:10:31+0100", "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "", "isDisabled": false, "isDeleted": false, "name": "test", "description": "", "configuration": [], "rowsSortOrder": [], "rows": [] } } } }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`) or version (`notFound`) not found." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/versions": { "get": { "tags": [ "Components and Configurations" ], "summary": "Versions list", "description": "Lists all versions of a component configuration for [Development Branch](#tag/Development-Branches).\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "get_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/versions::ConfigurationVersionListAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include", "in": "query", "description": "Comma-separated list of information to be retrieved; possible fields are `name`, `description` and `configuration`.", "required": false, "schema": { "description": "Comma-separated list of information to be retrieved; possible fields are `name`, `description` and `configuration`.", "type": "string", "example": "name,description,configuration", "nullable": true, "default": "name,description" }, "example": "name,description,configuration" }, { "name": "limit", "in": "query", "description": "Pagination limit.", "required": false, "schema": { "description": "Pagination limit.", "type": "integer", "example": 100, "nullable": true, "default": 100 }, "example": 100 }, { "name": "offset", "in": "query", "description": "Pagination offset.", "required": false, "schema": { "description": "Pagination offset.", "type": "integer", "example": 0, "nullable": true, "default": 0 }, "example": 0 } ], "responses": { "200": { "description": "List of configuration versions, newest first.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationVersionListItemResponse" } }, "example": [ { "version": 2, "created": "2017-02-09T21:11:02+0100", "versionIdentifier": "0001J8B6AMR2DJWHYPC5HE7BWA", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Add input table in.c-afnhk.tree-test", "isDisabled": false, "isDeleted": false, "name": "test", "description": "" }, { "version": 1, "created": "2017-02-09T21:10:31+0100", "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "", "isDisabled": false, "isDeleted": false, "name": "test", "description": "" } ] } } }, "400": { "description": "Invalid `limit` or `offset` query parameter." }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." } } } }, "/v2/storage/components/{componentId}/configs/{configurationId}/versions": { "get": { "tags": [ "Components and Configurations" ], "summary": "Versions list", "description": "Lists all versions of a component configuration for [Development Branch](#tag/Development-Branches).\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "get_/v2/storage/components/{componentId}/configs/{configurationId}/versions::ConfigurationVersionListAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "include", "in": "query", "description": "Comma-separated list of information to be retrieved; possible fields are `name`, `description` and `configuration`.", "required": false, "schema": { "description": "Comma-separated list of information to be retrieved; possible fields are `name`, `description` and `configuration`.", "type": "string", "example": "name,description,configuration", "nullable": true, "default": "name,description" }, "example": "name,description,configuration" }, { "name": "limit", "in": "query", "description": "Pagination limit.", "required": false, "schema": { "description": "Pagination limit.", "type": "integer", "example": 100, "nullable": true, "default": 100 }, "example": 100 }, { "name": "offset", "in": "query", "description": "Pagination offset.", "required": false, "schema": { "description": "Pagination offset.", "type": "integer", "example": 0, "nullable": true, "default": 0 }, "example": 0 } ], "responses": { "200": { "description": "List of configuration versions, newest first.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationVersionListItemResponse" } }, "example": [ { "version": 2, "created": "2017-02-09T21:11:02+0100", "versionIdentifier": "0001J8B6AMR2DJWHYPC5HE7BWA", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "Add input table in.c-afnhk.tree-test", "isDisabled": false, "isDeleted": false, "name": "test", "description": "" }, { "version": 1, "created": "2017-02-09T21:10:31+0100", "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S", "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": 1234 }, "changeDescription": "", "isDisabled": false, "isDeleted": false, "name": "test", "description": "" } ] } } }, "400": { "description": "Invalid `limit` or `offset` query parameter." }, "404": { "description": "Component (`storage.component.notFound`) or configuration (`storage.configuration.notFound`) not found." } } } }, "/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/versions/{versionId}/rollback": { "post": { "tags": [ "Components and Configurations" ], "summary": "Rollback Version", "description": "Rollbacking a configuration version actually creates a new configuration version identical to the\none you specified. `state` attributes of the config and rows is preserved, if any row is recreated, it will have the last existing state.\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "post_/v2/storage/branch/{branchId}/components/{componentId}/configs/{configurationId}/versions/{versionId}/rollback::ConfigurationVersionRollbackAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "versionId", "in": "path", "description": "Version number to rollback to.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 2 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RollbackConfigurationVersionRequest" } ] } } } }, "responses": { "201": { "description": "New configuration version created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationVersionRollbackResponse" }, "example": { "version": "3" } } } }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`) or version (`storage.configuration.versionNotFound`) not found." } } } }, "/v2/storage/components/{componentId}/configs/{configurationId}/versions/{versionId}/rollback": { "post": { "tags": [ "Components and Configurations" ], "summary": "Rollback Version", "description": "Rollbacking a configuration version actually creates a new configuration version identical to the\none you specified. `state` attributes of the config and rows is preserved, if any row is recreated, it will have the last existing state.\n\nThe variant without `branch/{branchId}` in the URL is deprecated, use the branch endpoint and set `branch/default`.", "operationId": "post_/v2/storage/components/{componentId}/configs/{configurationId}/versions/{versionId}/rollback::ConfigurationVersionRollbackAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" }, { "name": "configurationId", "in": "path", "description": "Id of the configuration.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "main-1" }, { "name": "versionId", "in": "path", "description": "Version number to rollback to.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 2 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RollbackConfigurationVersionRequest" } ] } } } }, "responses": { "201": { "description": "New configuration version created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationVersionRollbackResponse" }, "example": { "version": "3" } } } }, "404": { "description": "Component (`storage.component.notFound`), configuration (`storage.configuration.notFound`) or version (`storage.configuration.versionNotFound`) not found." } } } }, "/v2/storage/components/{componentId}": { "get": { "tags": [ "Components and Configurations" ], "summary": "Get component - without branch in URL (without authentication)", "description": "Use this API call to obtain the definition of a component available in KBC.\n\n**Without authentication**, you can call this endpoint without the `X-StorageApi-Token` and still get the component details.", "operationId": "get_/v2/storage/components/{componentId}::PublicComponentDetailAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Id of the component.", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "keboola.ex-db-mysql" } ], "responses": { "200": { "description": "Component detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentArrayRead" }, "example": { "id": "keboola.app-tree", "type": "application", "name": "Tree depth", "description": "Application which computes a tree depth.", "longDescription": "This application computes levels in a table representing a tree.", "version": 1, "complexity": null, "categories": [], "hasUI": false, "hasRun": false, "ico32": "https://d3iz2gfan5zufq.cloudfront.net/images/cloud-services/keboola.app-tree-32-1.png", "ico64": "https://d3iz2gfan5zufq.cloudfront.net/images/cloud-services/keboola.app-tree-64-1.png", "ico128": "https://d3iz2gfan5zufq.cloudfront.net/images/cloud-services/keboola.app-tree-128-1.png", "data": { "definition": { "type": "aws-ecr", "uri": "147946154733.dkr.ecr.us-east-1.amazonaws.com/keboola/app-tree", "tag": "latest", "repository": { "region": "us-east-1" } }, "cpu_shares": 1024, "memory": "8024m", "configuration_format": "json", "process_timeout": 10800 }, "flags": [ "genericDockerUI", "genericDockerUI-tableInput", "genericDockerUI-tableOutput", "excludeFromNewList" ], "configurationSchema": [], "configurationRowSchema": [], "emptyConfiguration": [], "emptyConfigurationRow": [], "createConfigurationRowSchema": [], "uiOptions": [], "configurationDescription": "The tree data must be stored in a child-parent relationship.", "features": [], "expiredOn": null, "uri": "https://syrup.keboola.com/docker/keboola.app-tree", "dataTypesConfiguration": [], "processorConfiguration": [] } } } }, "404": { "description": "Component not found (`storage.component.notFound`)." } } } }, "/v2/storage/dev-branches/{id}": { "get": { "tags": [ "Development Branches" ], "summary": "Branch detail", "description": "Returns detail of a single development branch.", "operationId": "get_/v2/storage/dev-branches/{id}::DevBranchDetailAction", "parameters": [ { "name": "id", "in": "path", "description": "ID of the branch.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 123 } ], "responses": { "200": { "description": "Branch detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevBranchResponse" }, "example": { "id": 123, "name": "My branch", "description": "", "created": "2020-09-17T12:17:32+0200", "isDefault": false, "creatorToken": { "id": 267, "name": "dev@keboola.com" }, "actor": { "type": "token", "id": "267", "name": "dev@keboola.com", "adminId": null } } } } }, "403": { "description": "Returned when the token is not allowed to view development branches." }, "404": { "description": "Returned when the branch does not exist in the project." } } }, "put": { "tags": [ "Development Branches" ], "summary": "Branch update", "description": "Updates name and/or description of a development branch. Update of a default branch name is not allowed.", "operationId": "put_/v2/storage/dev-branches/{id}::DevBranchUpdateAction", "parameters": [ { "name": "id", "in": "path", "description": "ID of the branch.", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 123 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateDevBranchRequest" } ] } } } }, "responses": { "200": { "description": "Updated branch detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevBranchResponse" }, "example": { "id": 123, "name": "My branch", "description": "Some description", "created": "2020-09-17T12:17:32+0200", "isDefault": false, "creatorToken": { "id": 267, "name": "dev@keboola.com" }, "actor": { "type": "token", "id": "267", "name": "dev@keboola.com", "adminId": null } } } } }, "400": { "description": "Returned when the request is invalid or the default branch name is being updated (`devBranch.defaultBranchNameCannotBeUpdated`)." }, "403": { "description": "Returned when the token is not allowed to manipulate development branches." }, "404": { "description": "Returned when the branch does not exist in the project." } } }, "delete": { "tags": [ "Development Branches" ], "summary": "Delete branch", "description": "Deletes a development branch with all buckets (tables) belonging to the development branch; other buckets (production buckets or buckets belonging to other development branches) are preserved.\n\nThe deletion runs asynchronously; the response is a storage job (`devBranchDelete`).", "operationId": "delete_/v2/storage/dev-branches/{id}::DevBranchDeleteAction", "parameters": [ { "name": "id", "in": "path", "description": "ID of the branch.", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 123 } ], "responses": { "202": { "description": "Branch deletion job accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 366, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/366", "tableId": null, "operationName": "devBranchDelete", "operationParams": { "queue": "main", "values": { "id": 14 } }, "createdTime": "2020-09-05T15:29:45+0200", "startTime": null, "endTime": null, "runId": "994", "results": null, "creatorToken": { "id": "1", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "403": { "description": "Returned when the token is not allowed to delete the development branch." }, "404": { "description": "Returned when the branch does not exist in the project." } } } }, "/v2/storage/dev-branches/": { "post": { "tags": [ "Development Branches" ], "summary": "Create branch", "description": "Creates a new development branch asynchronously. The response is a storage job (`devBranchCreate`); poll its `url` until the job finishes.", "operationId": "post_/v2/storage/dev-branches/::DevBranchCreateAction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateDevBranchRequest" } ] } } } }, "responses": { "202": { "description": "Branch creation job accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 347, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/347", "tableId": null, "operationName": "devBranchCreate", "operationParams": { "queue": "main", "values": { "name": "Refactor DB extractors", "description": "" } }, "createdTime": "2020-09-05T15:29:45+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "1", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "Returned when the request is invalid or a branch with the same name already exists (`devBranch.duplicateName`)." }, "403": { "description": "Returned when the token is not allowed to manipulate development branches." } } } }, "/v2/storage/dev-branches": { "get": { "tags": [ "Development Branches" ], "summary": "List branches", "description": "**EXPERIMENTAL**\n\nDevelopment branches allow you to prepare changes to configuration and tables in isolation. When ready, you can replace the production with the development branch.\n\nYou can use development branch in selected API calls by changing url. For example, you want to list configurations:\n- `GET /v2/storage/components/ex-foo/configs` - in default branch (common usage)\n- `GET /v2/storage/branch/default/components/ex-foo/configs` - in default branch (with `default` as branch prefix) - same result as above\n- `GET /v2/storage/branch/123/components/ex-foo/configs` - in development branch (with `ID` as branch prefix)\n\nLists all branches of the project, including the default branch.", "operationId": "get_/v2/storage/dev-branches::DevBranchesListAction", "responses": { "200": { "description": "List of branches.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DevBranchResponse" } }, "example": [ { "id": 123, "name": "My branch", "description": "", "created": "2020-09-17T12:17:32+0200", "isDefault": false, "creatorToken": { "id": 267, "name": "dev@keboola.com" }, "actor": { "type": "token", "id": "267", "name": "dev@keboola.com", "adminId": null } }, { "id": 5, "name": "Main", "description": "", "created": "2020-09-22T13:05:04+0200", "isDefault": true, "creatorToken": [], "actor": null } ] } } }, "403": { "description": "Returned when the token is not allowed to view development branches." } } }, "post": { "tags": [ "Development Branches" ], "summary": "Create branch", "description": "Creates a new development branch asynchronously. The response is a storage job (`devBranchCreate`); poll its `url` until the job finishes.", "operationId": "post_/v2/storage/dev-branches::DevBranchCreateAction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateDevBranchRequest" } ] } } } }, "responses": { "202": { "description": "Branch creation job accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 347, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/347", "tableId": null, "operationName": "devBranchCreate", "operationParams": { "queue": "main", "values": { "name": "Refactor DB extractors", "description": "" } }, "createdTime": "2020-09-05T15:29:45+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "1", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "Returned when the request is invalid or a branch with the same name already exists (`devBranch.duplicateName`)." }, "403": { "description": "Returned when the token is not allowed to manipulate development branches." } } } }, "/v2/storage/branch/{branchId}/metadata": { "get": { "tags": [ "Metadata" ], "summary": "List branch metadata", "description": "Metadata can be listed for a branch.\n\nAll requests must include the branch (`/branch/{branchId}`) in the URL. This is also true for default (production) branch.\nYou can find out the id of your default branch by calling [List Branches](#tag/Development-Branches) and finding branch with attribute `isDefault` set to `true`.\nOr you can use placeholder `default` to use with project's default branch.", "operationId": "get_/v2/storage/branch/{branchId}/metadata::MetadataListAction", "parameters": [ { "name": "branchId", "in": "path", "description": "Id of the development branch. Use `default` for the project default branch.", "required": true, "schema": { "type": "string" }, "example": "default" } ], "responses": { "200": { "description": "Branch metadata list.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemWithoutProviderResponse" } }, "example": [ { "id": "123", "key": "attribute_key", "value": "attribute_value", "timestamp": "2016-09-19T13:02:11+0200" }, { "id": "124", "key": "another_attribute_key", "value": "attribute_value", "timestamp": "2016-09-19T13:02:11+0200" } ] } } } } }, "post": { "tags": [ "Metadata" ], "summary": "Create or update branch metadata", "description": "Sets multiple metadata with one call. If the given key already exists\nfor the branch, the data will be updated with the new value and timestamp. All metadata associated\nwith the branch are returned.\n\nAll requests must include the branch (`/branch/{branchId}`) in the URL. This is also true for default (production) branch.\nYou can find out the id of your default branch by calling [List Branches](#tag/Development-Branches) and finding branch with attribute `isDefault` set to `true`.\nOr you can use placeholder `default` to use with project's default branch.", "operationId": "post_/v2/storage/branch/{branchId}/metadata::MetadataCreateAction", "parameters": [ { "name": "branchId", "in": "path", "description": "Id of the development branch. Use `default` for the project default branch.", "required": true, "schema": { "type": "string" }, "example": "default" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/MetadataCreateRequest" } ] } } } }, "responses": { "201": { "description": "All metadata associated with the branch.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemWithoutProviderResponse" } }, "example": [ { "id": "19509", "key": "some-key", "value": "Some value", "timestamp": "2017-02-13T23:36:10+0100" } ] } } }, "403": { "description": "Returned when the token cannot manipulate the branch or the metadata key is reserved for internal use (`storage.branches.metadata.reservedKey`)." } } } }, "/v2/storage/branch/{branchId}/metadata/{metadataId}": { "delete": { "tags": [ "Metadata" ], "summary": "Delete branch metadata", "description": "Deletes the specified metadata item from the development branch.\n\nAll requests must include the branch (`/branch/{branchId}`) in the URL. This is also true for default (production) branch.\nYou can find out the id of your default branch by calling [List Branches](#tag/Development-Branches) and finding branch with attribute `isDefault` set to `true`.\nOr you can use placeholder `default` to use with project's default branch.", "operationId": "delete_/v2/storage/branch/{branchId}/metadata/{metadataId}::MetadataDeleteAction", "parameters": [ { "name": "branchId", "in": "path", "description": "Id of the development branch. Use `default` for the project default branch.", "required": true, "schema": { "type": "string" }, "example": "default" }, { "name": "metadataId", "in": "path", "description": "Id of the metadata.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 19509 } ], "responses": { "204": { "description": "Metadata item deleted." }, "403": { "description": "Returned when the metadata key is reserved for internal use (`storage.branches.metadata.reservedKey`)." }, "404": { "description": "Returned when the metadata item is not found (`storage.branches.metadata.notFound`)." } } } }, "/v2/storage/branch/{branchId}/events": { "get": { "tags": [ "Events" ], "summary": "Events list", "description": "For admin tokens will endpoint lists all events in the project. For non-admin tokens will list only events created by the token.\n\nVirtually every interaction of the client (an API call) creates an Event. Apart from that, external events may\nalso be added via an API. Events are stored for a limited time.\n\nId field is deprecated and will be removed in the future. Please use Uuid instead.\n\nEvents can be filtered by various filters:\n- `sinceId`, `maxId` - Events newer or older than the passed id or Uuid (id is deprecated and will be removed in the future)\n- `component` - Component name\n- `configurationId` - Configuration id\n- `runId` - Run id\n- `q` - Advanced search using a query string. [Query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax)\n\nThe events pagination uses two parameters:\n- `limit` - Number of returned events. The default value: 100\n- `offset` - Pagination offset\n\nThe branch variant lists events of the given [Development Branch](#tag/Development-Branches); `default` can be used as `branchId`\nto emulate the call without a development branch, i.e. `GET /v2/storage/events` is the same as `GET /v2/storage/branch/default/events`.", "operationId": "get_/v2/storage/branch/{branchId}/events::EventsListAction", "parameters": [ { "name": "sinceId", "in": "query", "description": "Shows only events after the specified Id or Uuid (id is deprecated and will be removed in the future).", "required": false, "schema": { "type": "string" }, "example": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3" }, { "name": "maxId", "in": "query", "description": "Shows only events before the passed Id or Uuid (id is deprecated and will be removed in the future).", "required": false, "schema": { "type": "string" }, "example": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3" }, { "name": "component", "in": "query", "description": "Shows only events emitted by the specified component.", "required": false, "schema": { "type": "string" }, "example": "keboola.ex-db-snowflake" }, { "name": "configurationId", "in": "query", "description": "Shows only events related to the given configuration Id.", "required": false, "schema": { "type": "string" }, "example": "123456" }, { "name": "runId", "in": "query", "description": "Shows only events with the specified run Id.", "required": false, "schema": { "type": "string" }, "example": "987654321" }, { "name": "q", "in": "query", "description": "Searches events using advanced [Query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax).", "required": false, "schema": { "type": "string" }, "example": "event:storage.tableImportDone" }, { "name": "limit", "in": "query", "description": "Pagination limit. Maximum allowed value is `10000`.", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 10000, "minimum": 0 }, "example": 100 }, { "name": "offset", "in": "query", "description": "Pagination offset.", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "example": 0 }, { "name": "sortOrder", "in": "query", "description": "Sort order of events: `asc` = oldest first, `desc` = newest first.", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] }, "example": "desc" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsListResponse" }, "example": [ { "uuid": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3", "event": "storage.workspaceLoaded", "component": "storage", "message": "Table in.c-application-testing.cashier-data was loaded to the workspace workspace_78423 as my-table.", "description": "", "type": "info", "runId": null, "created": "2017-02-13T16:42:00+0100", "configurationId": null, "objectId": "in.c-application-testing.cashier-data", "objectName": "cashier-data", "objectType": "table", "context": { "remoteAddr": "203.0.113.10", "httpReferer": null, "httpUserAgent": "Keboola Storage PHP Client", "httpUserAgentOriginal": "Keboola Storage PHP Client", "authorization": "token", "apiVersion": "v2" }, "params": { "name": "my-table", "incremental": false }, "results": { "rowsCount": 1024 }, "performance": { "importDuration": 3 }, "token": { "id": 1234, "name": "support@keboola.com" }, "idBranch": null, "uri": "https://connection.keboola.com/v2/storage/events/01958f48-b1fc-7f05-b9b9-8a4a7b385bc3", "attachments": [] } ] } } }, "400": { "description": "Invalid filter parameters, e.g. `limit` out of range, negative `offset` or unknown `sortOrder` (`storage.events.error`)." } } }, "post": { "tags": [ "Events" ], "summary": "Create Event", "description": "Creates a new external event. The maximum allowed size of an event is 200KB. If this is exceeded,\nthe HTTP 400 response code is returned.\n\n`params` and `results` may be sent either as JSON objects or as serialized JSON object strings.\n\nThe branch variant creates the event for the given [Development Branch](#tag/Development-Branches).", "operationId": "post_/v2/storage/branch/{branchId}/events::CreateEventAction", "parameters": [ { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateEventRequest" } ] } } } }, "responses": { "201": { "description": "Event created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventResponse" }, "example": { "id": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3", "uuid": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3" } } } }, "400": { "description": "Missing `component` or `message` (`storage.storage.events.validation`), malformed event data such as invalid JSON in `params`/`results` (`malformedRequest`), or event larger than 200KB (`requestTooLarge`)." } } } }, "/v2/storage/events": { "get": { "tags": [ "Events" ], "summary": "Events list", "description": "For admin tokens will endpoint lists all events in the project. For non-admin tokens will list only events created by the token.\n\nVirtually every interaction of the client (an API call) creates an Event. Apart from that, external events may\nalso be added via an API. Events are stored for a limited time.\n\nId field is deprecated and will be removed in the future. Please use Uuid instead.\n\nEvents can be filtered by various filters:\n- `sinceId`, `maxId` - Events newer or older than the passed id or Uuid (id is deprecated and will be removed in the future)\n- `component` - Component name\n- `configurationId` - Configuration id\n- `runId` - Run id\n- `q` - Advanced search using a query string. [Query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax)\n\nThe events pagination uses two parameters:\n- `limit` - Number of returned events. The default value: 100\n- `offset` - Pagination offset\n\nThe branch variant lists events of the given [Development Branch](#tag/Development-Branches); `default` can be used as `branchId`\nto emulate the call without a development branch, i.e. `GET /v2/storage/events` is the same as `GET /v2/storage/branch/default/events`.", "operationId": "get_/v2/storage/events::EventsListAction", "parameters": [ { "name": "sinceId", "in": "query", "description": "Shows only events after the specified Id or Uuid (id is deprecated and will be removed in the future).", "required": false, "schema": { "type": "string" }, "example": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3" }, { "name": "maxId", "in": "query", "description": "Shows only events before the passed Id or Uuid (id is deprecated and will be removed in the future).", "required": false, "schema": { "type": "string" }, "example": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3" }, { "name": "component", "in": "query", "description": "Shows only events emitted by the specified component.", "required": false, "schema": { "type": "string" }, "example": "keboola.ex-db-snowflake" }, { "name": "configurationId", "in": "query", "description": "Shows only events related to the given configuration Id.", "required": false, "schema": { "type": "string" }, "example": "123456" }, { "name": "runId", "in": "query", "description": "Shows only events with the specified run Id.", "required": false, "schema": { "type": "string" }, "example": "987654321" }, { "name": "q", "in": "query", "description": "Searches events using advanced [Query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax).", "required": false, "schema": { "type": "string" }, "example": "event:storage.tableImportDone" }, { "name": "limit", "in": "query", "description": "Pagination limit. Maximum allowed value is `10000`.", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 10000, "minimum": 0 }, "example": 100 }, { "name": "offset", "in": "query", "description": "Pagination offset.", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "example": 0 }, { "name": "sortOrder", "in": "query", "description": "Sort order of events: `asc` = oldest first, `desc` = newest first.", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] }, "example": "desc" } ], "responses": { "200": { "description": "List of events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsListResponse" }, "example": [ { "uuid": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3", "event": "storage.workspaceLoaded", "component": "storage", "message": "Table in.c-application-testing.cashier-data was loaded to the workspace workspace_78423 as my-table.", "description": "", "type": "info", "runId": null, "created": "2017-02-13T16:42:00+0100", "configurationId": null, "objectId": "in.c-application-testing.cashier-data", "objectName": "cashier-data", "objectType": "table", "context": { "remoteAddr": "203.0.113.10", "httpReferer": null, "httpUserAgent": "Keboola Storage PHP Client", "httpUserAgentOriginal": "Keboola Storage PHP Client", "authorization": "token", "apiVersion": "v2" }, "params": { "name": "my-table", "incremental": false }, "results": { "rowsCount": 1024 }, "performance": { "importDuration": 3 }, "token": { "id": 1234, "name": "support@keboola.com" }, "idBranch": null, "uri": "https://connection.keboola.com/v2/storage/events/01958f48-b1fc-7f05-b9b9-8a4a7b385bc3", "attachments": [] } ] } } }, "400": { "description": "Invalid filter parameters, e.g. `limit` out of range, negative `offset` or unknown `sortOrder` (`storage.events.error`)." } } }, "post": { "tags": [ "Events" ], "summary": "Create Event", "description": "Creates a new external event. The maximum allowed size of an event is 200KB. If this is exceeded,\nthe HTTP 400 response code is returned.\n\n`params` and `results` may be sent either as JSON objects or as serialized JSON object strings.\n\nThe branch variant creates the event for the given [Development Branch](#tag/Development-Branches).", "operationId": "post_/v2/storage/events::CreateEventAction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateEventRequest" } ] } } } }, "responses": { "201": { "description": "Event created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventResponse" }, "example": { "id": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3", "uuid": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3" } } } }, "400": { "description": "Missing `component` or `message` (`storage.storage.events.validation`), malformed event data such as invalid JSON in `params`/`results` (`malformedRequest`), or event larger than 200KB (`requestTooLarge`)." } } } }, "/v2/storage/branch/{branchId}/events/{eventId}": { "get": { "tags": [ "Events" ], "summary": "Event detail", "description": "Obtains information about a event in the project. The branch variant returns the event of the given\n[Development Branch](#tag/Development-Branches).\n\nFor non-admin tokens, events bound to a bucket are only returned when the token has access to that bucket.", "operationId": "get_/v2/storage/branch/{branchId}/events/{eventId}::EventDetailAction", "parameters": [ { "name": "eventId", "in": "path", "description": "Event Id or uuid (id is deprecated and will be removed in the future).", "required": true, "schema": { "type": "string" }, "example": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Event detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventResponse" }, "example": { "uuid": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3", "event": "storage.workspaceLoaded", "component": "storage", "message": "Table in.c-application-testing.cashier-data was loaded to the workspace workspace_78423 as my-table.", "description": "", "type": "info", "runId": null, "created": "2017-02-13T16:42:00+0100", "configurationId": null, "objectId": "in.c-application-testing.cashier-data", "objectName": "cashier-data", "objectType": "table", "context": { "remoteAddr": "203.0.113.10", "httpReferer": null, "httpUserAgent": "Keboola Storage PHP Client", "httpUserAgentOriginal": "Keboola Storage PHP Client", "authorization": "token", "apiVersion": "v2" }, "params": { "name": "my-table", "incremental": false }, "results": { "rowsCount": 1024 }, "performance": { "importDuration": 3 }, "token": { "id": 1234, "name": "support@keboola.com" }, "idBranch": null, "uri": "https://connection.keboola.com/v2/storage/events/01958f48-b1fc-7f05-b9b9-8a4a7b385bc3", "attachments": [] } } } }, "400": { "description": "Event Id is neither an integer nor a valid UUID v7 (`storage.storage.events.invalidId`), or the events backend rejected the request (`storage.events.error`)." }, "403": { "description": "The token has no access to the bucket the event belongs to (`accessDenied`)." }, "404": { "description": "Event not found (`storage.storage.events.notFound`)." } } } }, "/v2/storage/events/{eventId}": { "get": { "tags": [ "Events" ], "summary": "Event detail", "description": "Obtains information about a event in the project. The branch variant returns the event of the given\n[Development Branch](#tag/Development-Branches).\n\nFor non-admin tokens, events bound to a bucket are only returned when the token has access to that bucket.", "operationId": "get_/v2/storage/events/{eventId}::EventDetailAction", "parameters": [ { "name": "eventId", "in": "path", "description": "Event Id or uuid (id is deprecated and will be removed in the future).", "required": true, "schema": { "type": "string" }, "example": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3" } ], "responses": { "200": { "description": "Event detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventResponse" }, "example": { "uuid": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3", "event": "storage.workspaceLoaded", "component": "storage", "message": "Table in.c-application-testing.cashier-data was loaded to the workspace workspace_78423 as my-table.", "description": "", "type": "info", "runId": null, "created": "2017-02-13T16:42:00+0100", "configurationId": null, "objectId": "in.c-application-testing.cashier-data", "objectName": "cashier-data", "objectType": "table", "context": { "remoteAddr": "203.0.113.10", "httpReferer": null, "httpUserAgent": "Keboola Storage PHP Client", "httpUserAgentOriginal": "Keboola Storage PHP Client", "authorization": "token", "apiVersion": "v2" }, "params": { "name": "my-table", "incremental": false }, "results": { "rowsCount": 1024 }, "performance": { "importDuration": 3 }, "token": { "id": 1234, "name": "support@keboola.com" }, "idBranch": null, "uri": "https://connection.keboola.com/v2/storage/events/01958f48-b1fc-7f05-b9b9-8a4a7b385bc3", "attachments": [] } } } }, "400": { "description": "Event Id is neither an integer nor a valid UUID v7 (`storage.storage.events.invalidId`), or the events backend rejected the request (`storage.events.error`)." }, "403": { "description": "The token has no access to the bucket the event belongs to (`accessDenied`)." }, "404": { "description": "Event not found (`storage.storage.events.notFound`)." } } } }, "/v2/storage/branch/{branchId}/files/{fileId}/content": { "get": { "tags": [ "Files" ], "summary": "Get file content", "description": "Returns the raw content of a file for inline preview. Only non-sliced files up to 10 MB are supported. Both encrypted and unencrypted files are supported. Files exceeding the size limit are rejected with 400.", "operationId": "get_/v2/storage/branch/{branchId}/files/{fileId}/content::FileContentAction", "parameters": [ { "name": "fileId", "in": "path", "description": "File Id", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 236504177 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Raw file content. The `Content-Type` is guessed from the file extension by FileContentService; an unrecognized extension falls back to `application/octet-stream`. The response is always served with `X-Content-Type-Options: nosniff`.", "content": { "text/csv": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "string" } }, "application/xml": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/yaml": { "schema": { "type": "string" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/gif": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "image/avif": { "schema": { "type": "string", "format": "binary" } }, "image/bmp": { "schema": { "type": "string", "format": "binary" } }, "image/x-icon": { "schema": { "type": "string", "format": "binary" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Returned when the file is sliced (`storage.files.contentNotAvailable`) or exceeds the 10 MB size limit (`storage.files.contentTooLarge`)." }, "404": { "description": "Returned when the file does not exist (`storage.files.notFound`)." }, "502": { "description": "Returned when the storage backend is unreachable or returned an error (`storage.files.contentStorageUnavailable`)." } } } }, "/v2/storage/files/{fileId}/content": { "get": { "tags": [ "Files" ], "summary": "Get file content", "description": "Returns the raw content of a file for inline preview. Only non-sliced files up to 10 MB are supported. Both encrypted and unencrypted files are supported. Files exceeding the size limit are rejected with 400.", "operationId": "get_/v2/storage/files/{fileId}/content::FileContentAction", "parameters": [ { "name": "fileId", "in": "path", "description": "File Id", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 236504177 } ], "responses": { "200": { "description": "Raw file content. The `Content-Type` is guessed from the file extension by FileContentService; an unrecognized extension falls back to `application/octet-stream`. The response is always served with `X-Content-Type-Options: nosniff`.", "content": { "text/csv": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "string" } }, "application/xml": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/yaml": { "schema": { "type": "string" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/gif": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "image/avif": { "schema": { "type": "string", "format": "binary" } }, "image/bmp": { "schema": { "type": "string", "format": "binary" } }, "image/x-icon": { "schema": { "type": "string", "format": "binary" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Returned when the file is sliced (`storage.files.contentNotAvailable`) or exceeds the 10 MB size limit (`storage.files.contentTooLarge`)." }, "404": { "description": "Returned when the file does not exist (`storage.files.notFound`)." }, "502": { "description": "Returned when the storage backend is unreachable or returned an error (`storage.files.contentStorageUnavailable`)." } } } }, "/v2/storage/branch/{branchId}/files/{fileId}/tags": { "post": { "tags": [ "Files" ], "summary": "Add Tag", "description": "Adds a new tag to a file.", "operationId": "post_/v2/storage/branch/{branchId}/files/{fileId}/tags::FileCreateTagAction", "parameters": [ { "name": "fileId", "in": "path", "description": "File id", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 236504177 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateTagRequest" } ] } } } }, "responses": { "204": { "description": "Tag added." }, "400": { "description": "Returned when the `tag` attribute is missing or blank (`storage.validation`)." }, "404": { "description": "Returned when the file does not exist (`storage.files.notFound`)." } } } }, "/v2/storage/files/{fileId}/tags": { "post": { "tags": [ "Files" ], "summary": "Add Tag", "description": "Adds a new tag to a file.", "operationId": "post_/v2/storage/files/{fileId}/tags::FileCreateTagAction", "parameters": [ { "name": "fileId", "in": "path", "description": "File id", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 236504177 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateTagRequest" } ] } } } }, "responses": { "204": { "description": "Tag added." }, "400": { "description": "Returned when the `tag` attribute is missing or blank (`storage.validation`)." }, "404": { "description": "Returned when the file does not exist (`storage.files.notFound`)." } } } }, "/v2/storage/branch/{branchId}/files/{fileId}": { "get": { "tags": [ "Files" ], "summary": "File detail", "description": "Returns detailed information about a single file.\n\nWhen `federationToken=true` is passed, the response additionally contains provider-specific read credentials\nand the file location: `credentials` + `s3Path` (AWS), `absCredentials` + `absPath` (Azure)\nor `gcsCredentials` + `gcsPath` (GCP).", "operationId": "get_/v2/storage/branch/{branchId}/files/{fileId}::FileDetailAction", "parameters": [ { "name": "fileId", "in": "path", "description": "File Id", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 236504177 }, { "name": "federationToken", "in": "query", "description": "Return credentials with permissions for a direct file download from the file storage. The credentials are valid for 12 hours.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDetailResponse" }, "example": { "id": 236504177, "created": "2017-02-14T09:46:25+0100", "isPublic": false, "isSliced": false, "isEncrypted": true, "name": "235728260.csvmanifest", "fileType": "csv", "url": "https://s3.amazonaws.com/kbc-sapi-files/exp-180/578/files/2017/02/14/236504176.235728260.csvmanifest?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=d76...288", "provider": "aws", "region": "us-east-1", "sizeBytes": 133, "tags": [], "maxAgeDays": 15, "runId": null, "runIds": [], "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "s3Path": { "bucket": "kbc-sapi-files", "key": "exp-180/578/files/2017/02/14/236504176.235728260.csvmanifest" }, "credentials": { "AccessKeyId": "ASI...O7A", "SecretAccessKey": "gIT...RtE", "SessionToken": "Ago...QU=", "Expiration": "2017-02-14T22:10:17+00:00" } } } } }, "404": { "description": "Returned when the file does not exist (`storage.files.notFound`)." } } }, "delete": { "tags": [ "Files" ], "summary": "Delete File", "description": "Deletes a file from storage.\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 [FileDeleteJobResult](#model-FileDeleteJobResult).\n\n Parameters of job will be [FileDeleteJobParams](#components-schemas-FileDeleteJobParams).\n\n[Deprecated] This endpoint can be used synchronously as well.", "operationId": "delete_/v2/storage/branch/{branchId}/files/{fileId}::FileDeleteAction", "parameters": [ { "name": "fileId", "in": "path", "description": "File Id", "required": true, "schema": { "type": "integer", "pattern": "[1-9][0-9]*" }, "example": 236504177 }, { "name": "async", "in": "query", "description": "Delete the file in a background job. Calling the parameter as `async=false` is deprecated.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Synchronous call response without content." }, "404": { "description": "Returned when the file does not exist (`storage.files.notFound`)." }, "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/FileDeleteJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDeleteJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDeleteJobParams" } } } } }, "/v2/storage/files/{fileId}": { "get": { "tags": [ "Files" ], "summary": "File detail", "description": "Returns detailed information about a single file.\n\nWhen `federationToken=true` is passed, the response additionally contains provider-specific read credentials\nand the file location: `credentials` + `s3Path` (AWS), `absCredentials` + `absPath` (Azure)\nor `gcsCredentials` + `gcsPath` (GCP).", "operationId": "get_/v2/storage/files/{fileId}::FileDetailAction", "parameters": [ { "name": "fileId", "in": "path", "description": "File Id", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 236504177 }, { "name": "federationToken", "in": "query", "description": "Return credentials with permissions for a direct file download from the file storage. The credentials are valid for 12 hours.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true } ], "responses": { "200": { "description": "File detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDetailResponse" }, "example": { "id": 236504177, "created": "2017-02-14T09:46:25+0100", "isPublic": false, "isSliced": false, "isEncrypted": true, "name": "235728260.csvmanifest", "fileType": "csv", "url": "https://s3.amazonaws.com/kbc-sapi-files/exp-180/578/files/2017/02/14/236504176.235728260.csvmanifest?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=d76...288", "provider": "aws", "region": "us-east-1", "sizeBytes": 133, "tags": [], "maxAgeDays": 15, "runId": null, "runIds": [], "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "s3Path": { "bucket": "kbc-sapi-files", "key": "exp-180/578/files/2017/02/14/236504176.235728260.csvmanifest" }, "credentials": { "AccessKeyId": "ASI...O7A", "SecretAccessKey": "gIT...RtE", "SessionToken": "Ago...QU=", "Expiration": "2017-02-14T22:10:17+00:00" } } } } }, "404": { "description": "Returned when the file does not exist (`storage.files.notFound`)." } } }, "delete": { "tags": [ "Files" ], "summary": "Delete File", "description": "Deletes a file from storage.\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 [FileDeleteJobResult](#model-FileDeleteJobResult).\n\n Parameters of job will be [FileDeleteJobParams](#components-schemas-FileDeleteJobParams).\n\n[Deprecated] This endpoint can be used synchronously as well.", "operationId": "delete_/v2/storage/files/{fileId}::FileDeleteAction", "parameters": [ { "name": "fileId", "in": "path", "description": "File Id", "required": true, "schema": { "type": "integer", "pattern": "[1-9][0-9]*" }, "example": 236504177 }, { "name": "async", "in": "query", "description": "Delete the file in a background job. Calling the parameter as `async=false` is deprecated.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true } ], "responses": { "204": { "description": "Synchronous call response without content." }, "404": { "description": "Returned when the file does not exist (`storage.files.notFound`)." }, "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/FileDeleteJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDeleteJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDeleteJobParams" } } } } }, "/v2/storage/branch/{branchId}/files/{fileId}/tags/{tagName}": { "delete": { "tags": [ "Files" ], "summary": "Delete Tag", "description": "Deletes a single tag from the specified file.", "operationId": "delete_/v2/storage/branch/{branchId}/files/{fileId}/tags/{tagName}::FileDeleteTagAction", "parameters": [ { "name": "fileId", "in": "path", "description": "File id", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 236504177 }, { "name": "tagName", "in": "path", "description": "Tag name", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "image" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Tag deleted." }, "404": { "description": "Returned when the file does not exist (`storage.files.notFound`)." } } } }, "/v2/storage/files/{fileId}/tags/{tagName}": { "delete": { "tags": [ "Files" ], "summary": "Delete Tag", "description": "Deletes a single tag from the specified file.", "operationId": "delete_/v2/storage/files/{fileId}/tags/{tagName}::FileDeleteTagAction", "parameters": [ { "name": "fileId", "in": "path", "description": "File id", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 236504177 }, { "name": "tagName", "in": "path", "description": "Tag name", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "image" } ], "responses": { "204": { "description": "Tag deleted." }, "404": { "description": "Returned when the file does not exist (`storage.files.notFound`)." } } } }, "/v2/storage/branch/{branchId}/files": { "get": { "tags": [ "Files" ], "summary": "List Files", "description": "Lists all files uploaded by your token. If the `canReadAllFileUploads` permission is set for your token,\nall file uploads for project will be returned.\n\n*Note*: There can be a delay of up to one second before any file change is propagated into the\nlist of files (including addition and removal of a file).\n\nFilters are passed as query string parameters.", "operationId": "get_/v2/storage/branch/{branchId}/files::FileListAction", "parameters": [ { "name": "sinceId", "in": "query", "description": "Shows only files after the specified Id.", "required": false, "schema": { "type": "string" }, "example": "236504000" }, { "name": "maxId", "in": "query", "description": "Shows only files before the passed Id.", "required": false, "schema": { "type": "string" }, "example": "236504177" }, { "name": "tags", "in": "query", "description": "Shows only files with one or more of the specified tags. Pass as an array, e.g. `tags[]=tag1&tags[]=tag2`.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "tag1", "tag2" ] }, { "name": "q", "in": "query", "description": "Searches files using advanced [Query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax).", "required": false, "schema": { "type": "string" }, "example": "name:*.csv" }, { "name": "runId", "in": "query", "description": "Shows only files with the given run Id.", "required": false, "schema": { "type": "string" }, "example": "12345.67890" }, { "name": "limit", "in": "query", "description": "Pagination limit.", "required": false, "schema": { "type": "integer", "default": 100 }, "example": 100 }, { "name": "offset", "in": "query", "description": "Pagination offset.", "required": false, "schema": { "type": "integer", "default": 0 }, "example": 0 }, { "name": "showExpired", "in": "query", "description": "Include expired files in response.", "required": false, "schema": { "type": "boolean", "default": false }, "example": false }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of files.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FileResponse" } }, "example": [ { "id": 236504177, "created": "2017-02-14T09:46:25+0100", "isPublic": false, "isSliced": false, "isEncrypted": true, "name": "235728260.csvmanifest", "fileType": "csv", "url": "https://s3.amazonaws.com/kbc-sapi-files/exp-180/578/files/2017/02/14/236504176.235728260.csvmanifest?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=9872bf...", "provider": "aws", "region": "us-east-1", "sizeBytes": 133, "tags": [], "maxAgeDays": 15, "runId": null, "runIds": [], "creatorToken": { "id": 27978, "description": "dev@keboola.com" } } ] } } }, "400": { "description": "Returned when a parameter is invalid (`storage.validation`), the `q` query has invalid syntax (`query.syntax`) or the search fails (`storage.files.filesError`)." } } } }, "/v2/storage/files": { "get": { "tags": [ "Files" ], "summary": "List Files", "description": "Lists all files uploaded by your token. If the `canReadAllFileUploads` permission is set for your token,\nall file uploads for project will be returned.\n\n*Note*: There can be a delay of up to one second before any file change is propagated into the\nlist of files (including addition and removal of a file).\n\nFilters are passed as query string parameters.", "operationId": "get_/v2/storage/files::FileListAction", "parameters": [ { "name": "sinceId", "in": "query", "description": "Shows only files after the specified Id.", "required": false, "schema": { "type": "string" }, "example": "236504000" }, { "name": "maxId", "in": "query", "description": "Shows only files before the passed Id.", "required": false, "schema": { "type": "string" }, "example": "236504177" }, { "name": "tags", "in": "query", "description": "Shows only files with one or more of the specified tags. Pass as an array, e.g. `tags[]=tag1&tags[]=tag2`.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "tag1", "tag2" ] }, { "name": "q", "in": "query", "description": "Searches files using advanced [Query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax).", "required": false, "schema": { "type": "string" }, "example": "name:*.csv" }, { "name": "runId", "in": "query", "description": "Shows only files with the given run Id.", "required": false, "schema": { "type": "string" }, "example": "12345.67890" }, { "name": "limit", "in": "query", "description": "Pagination limit.", "required": false, "schema": { "type": "integer", "default": 100 }, "example": 100 }, { "name": "offset", "in": "query", "description": "Pagination offset.", "required": false, "schema": { "type": "integer", "default": 0 }, "example": 0 }, { "name": "showExpired", "in": "query", "description": "Include expired files in response.", "required": false, "schema": { "type": "boolean", "default": false }, "example": false } ], "responses": { "200": { "description": "List of files.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FileResponse" } }, "example": [ { "id": 236504177, "created": "2017-02-14T09:46:25+0100", "isPublic": false, "isSliced": false, "isEncrypted": true, "name": "235728260.csvmanifest", "fileType": "csv", "url": "https://s3.amazonaws.com/kbc-sapi-files/exp-180/578/files/2017/02/14/236504176.235728260.csvmanifest?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=9872bf...", "provider": "aws", "region": "us-east-1", "sizeBytes": 133, "tags": [], "maxAgeDays": 15, "runId": null, "runIds": [], "creatorToken": { "id": 27978, "description": "dev@keboola.com" } } ] } } }, "400": { "description": "Returned when a parameter is invalid (`storage.validation`), the `q` query has invalid syntax (`query.syntax`) or the search fails (`storage.files.filesError`)." } } } }, "/v2/storage/branch/{branchId}/files/prepare": { "post": { "tags": [ "Files" ], "summary": "Create File Resource", "description": "This method allows you to upload a file to KBC File Storage. The upload should be done in two steps:\n1. Create a new file resource (use this API call).\n2. Use the provided credentials to actually upload the file data to the storage provider.\n\nFor a more detailed guide on the file upload, see the corresponding part of the\n[Developers documentation](https://developers.keboola.com/integrate/storage/api/import-export/#manually-uploading-a-file).\n\nFile Storage is used for storing arbitrary files. This is used for data imported into tables and data exported\nfrom tables. Additionally, the File storage can be used for data backup and exchange between project participants.\nBy default, all files are stored for **15 days**. They can be stored permanently by using the `isPermanent` parameter.\nFiles can also be tagged to categorize file uploads. When the `X-KBC-RunId` header is provided, it is stored as the file `runId`.\n\nInternally, all files are stored encrypted and are private. When you access the file through the API,\na URL with one hour expiration is generated.\n\nLarge files may be split into slices (chunks). A sliced file must have the `isSliced` parameter set to `true`. In that case\nthe provided key (blob) points to a **manifest file**. The manifest file contains the actual list of uploaded chunks. When uploading a sliced\nfile, you have to use the provided key as a prefix for chunks and generate the manifest file with the list of uploaded chunks.\nSee the [Developers documentation](https://developers.keboola.com/integrate/storage/api/import-export/#working-with-sliced-files)\nfor a detailed guide on sliced files.\n\nThe accepted request attributes depend on the file storage provider of the project (`S3FilePrepareRequest` for AWS,\n`AbsFilePrepareRequest` for Azure, `GcsFilePrepareRequest` for GCP). The response contains provider-specific upload\nparameters: `uploadParams` (AWS), `absUploadParams` (Azure) or `gcsUploadParams` (GCP).", "operationId": "post_/v2/storage/branch/{branchId}/files/prepare::FilePrepareAction", "parameters": [ { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AbsFilePrepareRequest" }, { "$ref": "#/components/schemas/GcsFilePrepareRequest" }, { "$ref": "#/components/schemas/S3FilePrepareRequest" } ] }, "example": { "name": "someFile.csv", "tags": [ "tag1", "tag2" ], "sizeBytes": 12345, "federationToken": true } } } }, "responses": { "200": { "description": "Created file resource including provider-specific upload parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilePrepareResponse" }, "example": { "id": 236518631, "created": "2017-02-14T10:34:45+0100", "isPublic": false, "isSliced": false, "isEncrypted": false, "name": "somefile.csv", "fileType": "csv", "url": "https://s3.amazonaws.com/kbc-sapi-files/exp-180/578/files/2017/02/14/236518630.somefile.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=374...a4c", "provider": "aws", "region": "us-east-1", "sizeBytes": 12345, "tags": [ "tag1", "tag2" ], "maxAgeDays": 15, "runId": null, "runIds": [], "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "uploadParams": { "key": "exp-180/578/files/2017/02/14/236518630.somefile.csv", "bucket": "kbc-sapi-files", "acl": "private", "credentials": { "AccessKeyId": "ASI...D2Q", "SecretAccessKey": "H+/...BYy", "SessionToken": "Ago...sUF", "Expiration": "2017-02-14T21:34:46+00:00" } } } } } }, "400": { "description": "Returned when the request is invalid (`filePrepare.validationError`) or when a form upload without `federationToken` is requested on AWS (`storage.files.formUploadIsDeprecated`)." } } } }, "/v2/storage/files/prepare": { "post": { "tags": [ "Files" ], "summary": "Create File Resource", "description": "This method allows you to upload a file to KBC File Storage. The upload should be done in two steps:\n1. Create a new file resource (use this API call).\n2. Use the provided credentials to actually upload the file data to the storage provider.\n\nFor a more detailed guide on the file upload, see the corresponding part of the\n[Developers documentation](https://developers.keboola.com/integrate/storage/api/import-export/#manually-uploading-a-file).\n\nFile Storage is used for storing arbitrary files. This is used for data imported into tables and data exported\nfrom tables. Additionally, the File storage can be used for data backup and exchange between project participants.\nBy default, all files are stored for **15 days**. They can be stored permanently by using the `isPermanent` parameter.\nFiles can also be tagged to categorize file uploads. When the `X-KBC-RunId` header is provided, it is stored as the file `runId`.\n\nInternally, all files are stored encrypted and are private. When you access the file through the API,\na URL with one hour expiration is generated.\n\nLarge files may be split into slices (chunks). A sliced file must have the `isSliced` parameter set to `true`. In that case\nthe provided key (blob) points to a **manifest file**. The manifest file contains the actual list of uploaded chunks. When uploading a sliced\nfile, you have to use the provided key as a prefix for chunks and generate the manifest file with the list of uploaded chunks.\nSee the [Developers documentation](https://developers.keboola.com/integrate/storage/api/import-export/#working-with-sliced-files)\nfor a detailed guide on sliced files.\n\nThe accepted request attributes depend on the file storage provider of the project (`S3FilePrepareRequest` for AWS,\n`AbsFilePrepareRequest` for Azure, `GcsFilePrepareRequest` for GCP). The response contains provider-specific upload\nparameters: `uploadParams` (AWS), `absUploadParams` (Azure) or `gcsUploadParams` (GCP).", "operationId": "post_/v2/storage/files/prepare::FilePrepareAction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AbsFilePrepareRequest" }, { "$ref": "#/components/schemas/GcsFilePrepareRequest" }, { "$ref": "#/components/schemas/S3FilePrepareRequest" } ] }, "example": { "name": "someFile.csv", "tags": [ "tag1", "tag2" ], "sizeBytes": 12345, "federationToken": true } } } }, "responses": { "200": { "description": "Created file resource including provider-specific upload parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilePrepareResponse" }, "example": { "id": 236518631, "created": "2017-02-14T10:34:45+0100", "isPublic": false, "isSliced": false, "isEncrypted": false, "name": "somefile.csv", "fileType": "csv", "url": "https://s3.amazonaws.com/kbc-sapi-files/exp-180/578/files/2017/02/14/236518630.somefile.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=374...a4c", "provider": "aws", "region": "us-east-1", "sizeBytes": 12345, "tags": [ "tag1", "tag2" ], "maxAgeDays": 15, "runId": null, "runIds": [], "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "uploadParams": { "key": "exp-180/578/files/2017/02/14/236518630.somefile.csv", "bucket": "kbc-sapi-files", "acl": "private", "credentials": { "AccessKeyId": "ASI...D2Q", "SecretAccessKey": "H+/...BYy", "SessionToken": "Ago...sUF", "Expiration": "2017-02-14T21:34:46+00:00" } } } } } }, "400": { "description": "Returned when the request is invalid (`filePrepare.validationError`) or when a form upload without `federationToken` is requested on AWS (`storage.files.formUploadIsDeprecated`)." } } } }, "/v2/storage/branch/{branchId}/files/{fileId}/refresh": { "put": { "tags": [ "Files" ], "summary": "Refresh File Credentials", "description": "**Endpoint is used to generate new credentials only for files stored in GCS.**\n\nBecause for GCS the maximum lifetime of a credentials are only one hour,\nso if in case of longer uploads than one hour we have to generate a new credentials with one hour validity after this time.\n\n**We can generate new credentials up to 12h after the first creation of a file using Create File Resource.**", "operationId": "put_/v2/storage/branch/{branchId}/files/{fileId}/refresh::RefreshAction", "parameters": [ { "name": "fileId", "in": "path", "description": "File Id", "required": true, "schema": { "type": "integer", "pattern": "[1-9][0-9]*" }, "example": 236518631 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File detail with refreshed `gcsUploadParams`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilePrepareResponse" }, "example": { "id": 236518631, "created": "2017-02-14T10:34:45+0100", "isPublic": false, "isSliced": false, "isEncrypted": true, "name": "somefile.csv", "fileType": "csv", "url": "https://storage.googleapis.com/kbc-ci-connection-files-storage/exp-15/23058/files/2022/11/09/851783.somefile.csv?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=3600&X-Goog-Signature=57f3...", "provider": "gcp", "region": "us-east-1", "sizeBytes": 12345, "tags": [ "tag1", "tag2" ], "maxAgeDays": 15, "runId": null, "runIds": [], "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "gcsUploadParams": { "projectId": "ci-connection-361807", "bucket": "kbc-ci-connection-files-storage", "key": "exp-15/23058/files/2022/11/09/851783.somefile.csv", "access_token": "ya29.dr...", "expires_in": 3599, "token_type": "Bearer" } } } } }, "400": { "description": "Returned when the file is not stored in GCS (`storage.refreshFileBackendNotSupported`)." }, "404": { "description": "Returned when the file does not exist (`storage.files.notFound`)." }, "422": { "description": "Returned when the file is older than 12 hours (`storage.refreshTimeExceeded`)." } } } }, "/v2/storage/files/{fileId}/refresh": { "put": { "tags": [ "Files" ], "summary": "Refresh File Credentials", "description": "**Endpoint is used to generate new credentials only for files stored in GCS.**\n\nBecause for GCS the maximum lifetime of a credentials are only one hour,\nso if in case of longer uploads than one hour we have to generate a new credentials with one hour validity after this time.\n\n**We can generate new credentials up to 12h after the first creation of a file using Create File Resource.**", "operationId": "put_/v2/storage/files/{fileId}/refresh::RefreshAction", "parameters": [ { "name": "fileId", "in": "path", "description": "File Id", "required": true, "schema": { "type": "integer", "pattern": "[1-9][0-9]*" }, "example": 236518631 } ], "responses": { "200": { "description": "File detail with refreshed `gcsUploadParams`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilePrepareResponse" }, "example": { "id": 236518631, "created": "2017-02-14T10:34:45+0100", "isPublic": false, "isSliced": false, "isEncrypted": true, "name": "somefile.csv", "fileType": "csv", "url": "https://storage.googleapis.com/kbc-ci-connection-files-storage/exp-15/23058/files/2022/11/09/851783.somefile.csv?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=3600&X-Goog-Signature=57f3...", "provider": "gcp", "region": "us-east-1", "sizeBytes": 12345, "tags": [ "tag1", "tag2" ], "maxAgeDays": 15, "runId": null, "runIds": [], "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "gcsUploadParams": { "projectId": "ci-connection-361807", "bucket": "kbc-ci-connection-files-storage", "key": "exp-15/23058/files/2022/11/09/851783.somefile.csv", "access_token": "ya29.dr...", "expires_in": 3599, "token_type": "Bearer" } } } } }, "400": { "description": "Returned when the file is not stored in GCS (`storage.refreshFileBackendNotSupported`)." }, "404": { "description": "Returned when the file does not exist (`storage.files.notFound`)." }, "422": { "description": "Returned when the file is older than 12 hours (`storage.refreshTimeExceeded`)." } } } }, "/v2/storage/global-search": { "get": { "tags": [ "Search" ], "summary": "Search storage objects", "description": "Search across storage objects (buckets, tables, columns, configurations) within the organization, optionally narrowed to specific projects via projectIds.", "operationId": "get_/v2/storage/global-search::SearchAction", "parameters": [ { "name": "query", "in": "query", "description": "Search query string.", "required": true, "schema": { "description": "Search query string.", "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return.", "required": false, "schema": { "description": "Maximum number of results to return.", "type": "integer", "default": 10, "minimum": 1 } }, { "name": "offset", "in": "query", "description": "Number of results to skip (pagination).", "required": false, "schema": { "description": "Number of results to skip (pagination).", "type": "integer", "default": 0, "minimum": 0 } }, { "name": "types[]", "in": "query", "description": "Filter by object type. Repeatable.", "required": false, "schema": { "description": "Filter by object type. Repeatable.", "type": "array", "items": { "type": "string", "enum": [ "flow", "bucket", "table", "transformation", "configuration", "configuration-row", "workspace", "shared-code" ] }, "nullable": true } }, { "name": "projectIds[]", "in": "query", "description": "Narrow the search to specific project ids. Repeatable.", "required": false, "schema": { "description": "Narrow the search to specific project ids. Repeatable.", "type": "array", "items": { "type": "integer" }, "nullable": true } }, { "name": "branchTypes[]", "in": "query", "description": "Filter by branch type. Repeatable.", "required": false, "schema": { "description": "Filter by branch type. Repeatable.", "type": "array", "items": { "type": "string", "enum": [ "production", "development" ] }, "nullable": true } }, { "name": "branchIds[]", "in": "query", "description": "Filter by branch ids. Repeatable.", "required": false, "schema": { "description": "Filter by branch ids. Repeatable.", "type": "array", "items": { "type": "integer" }, "nullable": true } }, { "name": "mode", "in": "query", "description": "Search mode. Allowed values: standard, regex. Default: standard.\n\nstandard: full-text search with normalisation (accent folding, lower-casing, word splitting).\nregex: Lucene regexp matched against the original (un-normalised) storage id and object name.\n - Matches if the pattern matches the id OR the name.\n - Whole-term semantics: \"report\" does NOT match \"monthly_report\"; use \".*report.*\" to match a substring.\n - Case-insensitive.\n - Object names longer than 256 characters are not searchable in regex mode (ids are not length-limited).\n - An invalid or overly long pattern returns HTTP 400.", "required": false, "schema": { "description": "Search mode. Allowed values: standard, regex. Default: standard.\n\nstandard: full-text search with normalisation (accent folding, lower-casing, word splitting).\nregex: Lucene regexp matched against the original (un-normalised) storage id and object name.\n - Matches if the pattern matches the id OR the name.\n - Whole-term semantics: \"report\" does NOT match \"monthly_report\"; use \".*report.*\" to match a substring.\n - Case-insensitive.\n - Object names longer than 256 characters are not searchable in regex mode (ids are not length-limited).\n - An invalid or overly long pattern returns HTTP 400.", "type": "string", "default": "standard", "enum": [ "standard", "regex" ] } } ], "responses": { "200": { "description": "Search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalSearchResponse" } } } }, "400": { "description": "Invalid query, invalid regex pattern, or pattern exceeds the maximum allowed length." } } } }, "/v2/storage/jobs/{jobId}": { "get": { "tags": [ "Jobs" ], "summary": "Job detail", "description": "Retrieves information about a single job.", "operationId": "get_/v2/storage/jobs/{jobId}::JobDetailAction", "parameters": [ { "name": "jobId", "in": "path", "description": "Id of the job.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 22077337 } ], "responses": { "200": { "description": "Job detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 22077337, "status": "success", "url": "https://connection.keboola.com/v2/storage/jobs/22077337", "tableId": null, "operationName": "workspaceLoad", "operationParams": { "workspaceId": "78423", "preserve": false, "input": [ { "source": "in.c-application-testing.cashier-data", "destination": "my-table" } ], "queue": "main_fast" }, "createdTime": "2017-02-13T16:41:18+0100", "startTime": "2017-02-13T16:41:18+0100", "endTime": "2017-02-13T16:42:00+0100", "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": true, "outBytes": 7168, "outBytesUncompressed": 0 } } } } }, "403": { "description": "Returned when the job belongs to another project or the token has no access to the job bucket." }, "404": { "description": "Returned when the job does not exist (`storage.storageJobs.notFound`)." } } } }, "/v2/storage/jobs": { "get": { "tags": [ "Jobs" ], "summary": "Jobs list", "description": "Jobs are objects that manage asynchronous tasks, these are all potentially long-running actions such as loading table data, snapshotting, table structure modifications. Jobs are created by actions on target resources, e.g., an asynchronous import request creates a table import job. For each new job, the Id and URL of the job is returned.\n\nWhen working with jobs, follow these steps:\n1. **Start the job** - Job resource is created and a URL for polling is returned.\n2. **Poll job status** - Poll the job URL in a loop until the job `status` is set to `success` or `error`.\n3. **Check the results** - When the job is finished, the `results` field will contain the actual result of the original request.\n\nAvailable Statuses:\n- `waiting` - The job is in the queue and is waiting for execution.\n- `processing` - The job is being processed by a worker.\n- `success` - The job is done with a success.\n- `error` - The job is done with an error.\n\nLists jobs of the project. Query parameters filter the list; `limit` defaults to 100 and `offset` to 0. The `*_from` / `*_to` filters are not applied when the corresponding exact-time filter is used, and `excluded_storage_job_status` is not applied when `storage_job_status` is used. Time values use the `Y-m-d H:i:s` format.", "operationId": "get_/v2/storage/jobs::StorageJobsListAction", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of jobs to return (pagination).", "required": false, "schema": { "description": "Maximum number of jobs to return (pagination).", "type": "integer", "nullable": true } }, { "name": "offset", "in": "query", "description": "Offset for pagination.", "required": false, "schema": { "description": "Offset for pagination.", "type": "integer", "nullable": true } }, { "name": "storage_job_status[]", "in": "query", "description": "Filter by job status.", "required": false, "schema": { "description": "Filter by job status.", "type": "array", "items": { "type": "string" }, "nullable": true } }, { "name": "excluded_storage_job_status[]", "in": "query", "description": "Exclude jobs with these statuses.", "required": false, "schema": { "description": "Exclude jobs with these statuses.", "type": "array", "items": { "type": "string" }, "nullable": true } }, { "name": "created_time", "in": "query", "description": "Filter by exact created time.", "required": false, "schema": { "description": "Filter by exact created time.", "type": "string", "format": "date-time", "nullable": true } }, { "name": "created_time_from", "in": "query", "description": "Filter jobs created after this time.", "required": false, "schema": { "description": "Filter jobs created after this time.", "type": "string", "format": "date-time", "nullable": true } }, { "name": "created_time_to", "in": "query", "description": "Filter jobs created before this time.", "required": false, "schema": { "description": "Filter jobs created before this time.", "type": "string", "format": "date-time", "nullable": true } }, { "name": "start_time", "in": "query", "description": "Filter by exact start time.", "required": false, "schema": { "description": "Filter by exact start time.", "type": "string", "format": "date-time", "nullable": true } }, { "name": "start_time_from", "in": "query", "description": "Filter jobs started after this time.", "required": false, "schema": { "description": "Filter jobs started after this time.", "type": "string", "format": "date-time", "nullable": true } }, { "name": "start_time_to", "in": "query", "description": "Filter jobs started before this time.", "required": false, "schema": { "description": "Filter jobs started before this time.", "type": "string", "format": "date-time", "nullable": true } }, { "name": "end_time", "in": "query", "description": "Filter by exact end time.", "required": false, "schema": { "description": "Filter by exact end time.", "type": "string", "format": "date-time", "nullable": true } }, { "name": "end_time_from", "in": "query", "description": "Filter jobs ended after this time.", "required": false, "schema": { "description": "Filter jobs ended after this time.", "type": "string", "format": "date-time", "nullable": true } }, { "name": "end_time_to", "in": "query", "description": "Filter jobs ended before this time.", "required": false, "schema": { "description": "Filter jobs ended before this time.", "type": "string", "format": "date-time", "nullable": true } } ], "responses": { "200": { "description": "List of storage jobs.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JobResponse" } }, "example": [ { "id": 22077337, "status": "success", "url": "https://connection.keboola.com/v2/storage/jobs/22077337", "tableId": null, "operationName": "workspaceLoad", "operationParams": { "workspaceId": "78423", "preserve": false, "input": [ { "source": "in.c-application-testing.cashier-data", "destination": "my-table" } ], "queue": "main_fast" }, "createdTime": "2017-02-13T16:41:18+0100", "startTime": "2017-02-13T16:41:18+0100", "endTime": "2017-02-13T16:42:00+0100", "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": true, "outBytes": 7168, "outBytesUncompressed": 0 } } ] } } }, "400": { "description": "Returned when the query parameters are invalid (unknown status, bad time format, limit out of range)." } } } }, "/v2/storage/merge-request/{id}/merge": { "put": { "tags": [ "Development Branches" ], "summary": "Merge a merge request", "description": "Apply changes in MR and all changes in configurations are moved to the production (default) branch. Returns a job that tracks the merge progress.", "operationId": "put_/v2/storage/merge-request/{id}/merge::MergeAction", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "202": { "description": "Merge job has been created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "403": { "description": "Returned when the token does not have the required role or the project feature is not enabled." }, "404": { "description": "Returned when the merge request does not exist." }, "409": { "description": "Returned when the branch is not ready to merge or merge validation fails." } } } }, "/v2/storage/merge-request/{id}/approve": { "put": { "tags": [ "Development Branches" ], "summary": "Approve a merge request", "description": "Each project has defined required number of approvals. If the last approval arrives, MR changes it state to `approved`.", "operationId": "put_/v2/storage/merge-request/{id}/approve::MergeRequestApproveAction", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": { "description": "Approved merge request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeRequestWithChangeLogResponse" } } } }, "403": { "description": "Returned when the token does not have the required role or the project feature is not enabled." }, "404": { "description": "Returned when the merge request does not exist." }, "422": { "description": "Returned when the merge request cannot be approved in its current state." } } } }, "/v2/storage/merge-request/{id}/conflicts": { "get": { "tags": [ "Development Branches" ], "summary": "Get merge request conflicts", "description": "Returns the list of conflicting configurations between the source (dev) branch and the target (default) branch of the merge request. A conflict means the merge cannot proceed without resolving it (for example, the configuration was changed in both the dev branch and the default branch since the dev branch last took it from the default branch, i.e. branch creation, rebase or reset to default; in projects with a protected default branch any change in the default branch counts).\n\nThe endpoint is primarily intended for UI consumption \u2014 callers can detect conflicts before attempting a merge. An empty array means the merge request can be merged without conflicts.", "operationId": "get_/v2/storage/merge-request/{id}/conflicts::MergeRequestConflictsAction", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": { "description": "List of merge conflicts between the dev and default branch. Empty array means no conflicts.", "content": { "application/json": { "schema": { "type": "array", "items": { "required": [ "message", "componentId", "configurationId", "isDeleted", "devBranchVersionIdentifier", "defaultBranchVersionIdentifier" ], "properties": { "message": { "type": "string" }, "componentId": { "type": "string" }, "configurationId": { "type": "string" }, "isDeleted": { "type": "boolean" }, "devBranchVersionIdentifier": { "type": "string" }, "defaultBranchVersionIdentifier": { "type": "string" } }, "type": "object" } } } } }, "404": { "description": "Returned when the merge request does not exist." } } } }, "/v2/storage/merge-request": { "get": { "tags": [ "Development Branches" ], "summary": "List merge requests", "description": "List all merge requests available in the project defined by token.", "operationId": "get_/v2/storage/merge-request::MergeRequestListAction", "responses": { "200": { "description": "List of merge requests.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MergeRequestResponse" } } } } } } }, "post": { "tags": [ "Development Branches" ], "summary": "Create a merge request", "description": "Creates a merge request for a development branch. Only one open merge request per branch is allowed.", "operationId": "post_/v2/storage/merge-request::MergeRequestCreateAction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeRequestCreateRequest" } } } }, "responses": { "201": { "description": "Created merge request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeRequestResponse" } } } }, "403": { "description": "Returned when the token does not have the required role or the project feature is not enabled." }, "404": { "description": "Returned when the specified branch does not exist." }, "422": { "description": "Returned when a reviewer ID is not eligible for this project." } } } }, "/v2/storage/merge-request/{id}": { "get": { "tags": [ "Development Branches" ], "summary": "Get merge request detail", "description": "Detail of Merge request also contains `content` of changed objects.", "operationId": "get_/v2/storage/merge-request/{id}::MergeRequestDetailAction", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } }, { "name": "include", "in": "query", "description": "Comma-separated list of data to include. Allowed values: activityLog.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Merge request detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeRequestDetailResponse" } } } }, "404": { "description": "Returned when the merge request does not exist." } } }, "put": { "tags": [ "Development Branches" ], "summary": "Update a merge request", "description": "Updates title, description, external id, auto-merge strategy or reviewers of the merge request. Omit an attribute to keep it unchanged.", "operationId": "put_/v2/storage/merge-request/{id}::MergeRequestUpdateAction", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeRequestUpdateRequest" } } } }, "responses": { "200": { "description": "Updated merge request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeRequestResponse" } } } }, "403": { "description": "Returned when the token does not have the required role, the project feature is not enabled, or the merge request is in a state that does not allow the requested update (in projects with the \"protected-default-branch\" feature only the \"development\" state is editable; in other projects the terminal states \"published\" and \"canceled\" are blocked)." }, "404": { "description": "Returned when the merge request does not exist." }, "422": { "description": "Returned when a reviewer ID is not eligible for this project." } } } }, "/v2/storage/merge-request/{id}/request-changes": { "put": { "tags": [ "Development Branches" ], "summary": "Request changes on a merge request", "description": "Requesting changes will remove all approvals and move the Merge request to `development` state.", "operationId": "put_/v2/storage/merge-request/{id}/request-changes::MergeRequestRejectAction", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeRequestRejectRequest2" } } } }, "responses": { "200": { "description": "Merge request with changes requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeRequestWithChangeLogResponse" } } } }, "403": { "description": "Returned when the token does not have the required role or the project feature is not enabled." }, "404": { "description": "Returned when the merge request does not exist." }, "422": { "description": "Returned when the merge request cannot request changes in its current state." } } } }, "/v2/storage/merge-request/{id}/request-review": { "put": { "tags": [ "Development Branches" ], "summary": "Request review for a merge request", "description": "Will move Merge request state `development` -> `in_review`. If branch has an open Merge request in state different from `development`, it is considered as locked and no updates on it are available.", "operationId": "put_/v2/storage/merge-request/{id}/request-review::MergeRequestRequestReviewAction", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": { "description": "Merge request with review requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeRequestWithChangeLogResponse" } } } }, "403": { "description": "Returned when the token does not have the required role or the project feature is not enabled." }, "404": { "description": "Returned when the merge request does not exist." }, "422": { "description": "Returned when the merge request cannot request review in its current state." } } } }, "/v2/storage/scheduled-tasks/{taskId}": { "delete": { "tags": [ "Scheduled tasks" ], "summary": "Delete task", "description": "Deletes a scheduled task.", "operationId": "delete_/v2/storage/scheduled-tasks/{taskId}::ScheduledTaskDeleteAction", "parameters": [ { "name": "taskId", "in": "path", "description": "UUID (v7) of the scheduled task to delete.", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}" }, "example": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b" } ], "responses": { "204": { "description": "Scheduled task deleted." }, "403": { "description": "The token does not have write access to the bucket the task refreshes, or, for a linked bucket, cannot manage buckets (`accessDenied`)." }, "404": { "description": "Returned when the scheduled task does not exist in the token's project (`storage.scheduledTasks.notFound`)." } } } }, "/v2/storage/branch/{branchId}/search/component-configurations": { "get": { "tags": [ "Search" ], "summary": "Search component configurations by metadata", "description": "Search all component configurations accessible by the token by any combination of\n`idComponent`, `configurationId` and `metadataKeys`. Available only in branch context.\n\nBy default, each matching configuration is returned with just its `idComponent` and\n`configurationId`. Pass `include=filteredMetadata` to also return the metadata entries that\nmatched the search.", "operationId": "get_/v2/storage/branch/{branchId}/search/component-configurations::SearchComponentConfigurationsAction", "parameters": [ { "name": "idComponent", "in": "query", "description": "Component identifier to filter by.", "required": false, "schema": { "type": "string" } }, { "name": "configurationId", "in": "query", "description": "Configuration identifier to filter by.", "required": false, "schema": { "type": "string" } }, { "name": "metadataKeys", "in": "query", "description": "Metadata keys to search for.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "include", "in": "query", "description": "Comma-separated list of resources to include (e.g. \"filteredMetadata\").", "required": false, "schema": { "type": "string" } }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of component configurations matching the search criteria.", "content": { "application/json": { "schema": { "type": "array", "items": { "required": [ "idComponent", "configurationId" ], "properties": { "idComponent": { "type": "string" }, "configurationId": { "type": "string" }, "metadata": { "description": "Metadata of the configuration matching the searched keys. Present only with `include=filteredMetadata`.", "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationMetadataResponse" } } }, "type": "object" } } } } } } } }, "/v2/storage/search/tables": { "get": { "tags": [ "Search" ], "summary": "Search Tables", "description": "Search all tables accessible by the token by either metadataKey, metadataValue or metadataProvider. By default, all tables are returned with their attributes and information about the containing bucket. At least one of parameters metadataKey|metadataValue|metadataProvider must be provided.\n\nThe `include` parameter is a comma separated list of resources to include for each table: `buckets`, `columns`, `metadata`, `columnMetadata`, `sourceMetadata` (for alias tables, includes source table metadata in `sourceTable.metadata`; works across projects for linked buckets), `sourceColumnMetadata` (for alias tables, includes source column metadata in `sourceTable.columnMetadata`).", "operationId": "get_/v2/storage/search/tables::SearchTablesAction", "parameters": [ { "name": "metadataKey", "in": "query", "description": "Metadata key to search for.", "required": false, "schema": { "description": "Metadata key to search for.", "type": "string", "nullable": true } }, { "name": "metadataValue", "in": "query", "description": "Metadata value to search for.", "required": false, "schema": { "description": "Metadata value to search for.", "type": "string", "nullable": true } }, { "name": "metadataProvider", "in": "query", "description": "Metadata provider to search for.", "required": false, "schema": { "description": "Metadata provider to search for.", "type": "string", "nullable": true } }, { "name": "include", "in": "query", "description": "Resources to include for each table: buckets, columns, metadata, columnMetadata, sourceMetadata, sourceColumnMetadata. Accepts a comma-separated string or a repeated array. Default: attributes,buckets.", "required": false, "schema": { "description": "Resources to include for each table: buckets, columns, metadata, columnMetadata, sourceMetadata, sourceColumnMetadata. Accepts a comma-separated string or a repeated array. Default: attributes,buckets.", "example": "buckets,metadata", "nullable": true, "oneOf": [ { "description": "Comma-separated list of resources.", "type": "string" }, { "description": "Repeated array of resources.", "type": "array", "items": { "type": "string" } } ] }, "example": "buckets,metadata" } ], "responses": { "200": { "description": "List of tables matching the search criteria.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SearchTablesResponse" } }, "example": [ { "uri": "https://connection.keboola.com/v2/storage/tables/in.c-application-testing.cashier-data", "id": "in.c-application-testing.cashier-data", "name": "cashier-data", "displayName": "cashier-data-displayName", "transactional": false, "primaryKey": [], "created": "2016-06-23T20:41:07+0200", "lastImportDate": "2016-07-07T11:25:32+0200", "lastChangeDate": "2016-07-07T11:25:34+0200", "rowsCount": 18, "dataSizeBytes": 12288, "isAlias": false, "isAliasable": true, "isTyped": false, "timestampType": "MANAGED", "tableType": "table", "path": "kbc_578.c-application-testing.cashier-data", "bucket": { "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-application-testing", "id": "in.c-application-testing", "name": "c-application-testing", "displayName": "application-testing", "stage": "in", "description": "Main project storage", "created": "2015-02-05T10:57:08+0100", "lastChangeDate": "2017-02-12T10:36:15+0100", "isReadOnly": false, "dataSizeBytes": 685750272, "rowsCount": 2438881, "isMaintenance": false, "backend": "snowflake", "sharing": null }, "metadata": [ { "id": "207947778", "key": "KBC.datatype.basetype", "value": "INTEGER", "provider": "user", "timestamp": "2019-08-14T16:55:34+0200" } ] } ] } } }, "400": { "description": "Returned when none of metadataKey, metadataValue, metadataProvider is provided." } } } }, "/v2/storage/branch/{branchId}/shared-buckets": { "get": { "tags": [ "Buckets" ], "summary": "Shared buckets list", "description": "Lists buckets which may be shared to the project (buckets shared within the organization the token can link). Requires the token to be able to manage buckets.", "operationId": "get_/v2/storage/branch/{branchId}/shared-buckets::SharedBucketsListAction", "parameters": [ { "name": "include", "in": "query", "description": "Comma-separated list of resources to include for each bucket. Available resources: `metadata`.", "required": false, "schema": { "type": "string" }, "example": "metadata" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of shared buckets.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SharedBucketResponse" } }, "example": [ { "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", "hasExternalSchema": false, "databaseName": null, "path": "database_name.c-main", "project": { "id": 123, "name": "Project name" }, "color": null, "tables": [ { "id": "in.c-main.languages", "name": "languages", "displayName": "languages-display-name", "path": "database_name.c-main.languages" } ], "sharingParameters": [], "sharedBy": { "id": 5, "name": "dev@keboola.com", "date": "2020-02-03T14:58:29+0100" }, "sharedByActor": { "type": "token", "id": "5", "name": "dev@keboola.com", "adminId": null }, "owner": null } ] } } }, "403": { "description": "The token cannot manage buckets (`accessDenied`)." } } } }, "/v2/storage/shared-buckets": { "get": { "tags": [ "Buckets" ], "summary": "Shared buckets list", "description": "Lists buckets which may be shared to the project (buckets shared within the organization the token can link). Requires the token to be able to manage buckets.", "operationId": "get_/v2/storage/shared-buckets::SharedBucketsListAction", "parameters": [ { "name": "include", "in": "query", "description": "Comma-separated list of resources to include for each bucket. Available resources: `metadata`.", "required": false, "schema": { "type": "string" }, "example": "metadata" } ], "responses": { "200": { "description": "List of shared buckets.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SharedBucketResponse" } }, "example": [ { "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", "hasExternalSchema": false, "databaseName": null, "path": "database_name.c-main", "project": { "id": 123, "name": "Project name" }, "color": null, "tables": [ { "id": "in.c-main.languages", "name": "languages", "displayName": "languages-display-name", "path": "database_name.c-main.languages" } ], "sharingParameters": [], "sharedBy": { "id": 5, "name": "dev@keboola.com", "date": "2020-02-03T14:58:29+0100" }, "sharedByActor": { "type": "token", "id": "5", "name": "dev@keboola.com", "adminId": null }, "owner": null } ] } } }, "403": { "description": "The token cannot manage buckets (`accessDenied`)." } } } }, "/v2/storage/sharing-targets": { "get": { "tags": [ "Buckets" ], "summary": "Sharing targets list", "description": "Lists the projects and users a bucket of the caller's project can be shared to: every project of\nthe organization and every admin of those projects.\n\nRequires an admin token whose admin either has the `share` role in the project or is a member\nof the project's organization. A `share`-role admin gets the lists even without organization\nmembership.", "operationId": "get_/v2/storage/sharing-targets::SharingTargetsListAction", "responses": { "200": { "description": "Projects and users a bucket can be shared to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharingTargetsListResponse" } } } }, "403": { "description": "The token is not an admin token, or its admin has neither the `share` role in the project nor organization membership (`accessDenied`)." } } } }, "/v2/storage/snapshots/{snapshotId}": { "get": { "tags": [ "Table Snapshotting" ], "summary": "Snapshot Detail", "description": "Retrieves information about a single table snapshot. Use the List Table Snapshots call to find the snapshot ID. Available in the default branch only.", "operationId": "get_/v2/storage/snapshots/{snapshotId}::SnapshotDetailAction", "parameters": [ { "name": "snapshotId", "in": "path", "description": "ID of the snapshot.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 20 } ], "responses": { "200": { "description": "Snapshot detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotDetailResponse" }, "example": { "id": "20", "description": "", "createdTime": "2013-08-12T12:33:04+0200", "type": "table", "creatorToken": { "id": 221, "description": "Master Token" }, "actor": { "type": "token", "id": "221", "name": "Master Token", "adminId": null }, "uri": "https://connection.keboola.com/v2/storage/snapshots/20", "dataFileId": 161757, "table": { "id": "in.c-dalsi.alias", "primaryKey": [], "attributes": [], "columns": [ "id", "name" ] } } } } }, "403": { "description": "The token does not have access to the bucket of the snapshotted table (`accessDenied`)." }, "404": { "description": "The snapshot was not found (`storage.snapshots.notFound`)." } } }, "delete": { "tags": [ "Table Snapshotting" ], "summary": "Delete Table Snapshot", "description": "Removes a table snapshot. The current table data is not modified. Use the List Table Snapshots call to find the snapshot ID. The snapshot is removed in a background job; to see the job detail use the Job Detail endpoint. Available in the default branch only.", "operationId": "delete_/v2/storage/snapshots/{snapshotId}::SnapshotDeleteAction", "parameters": [ { "name": "snapshotId", "in": "path", "description": "ID of the snapshot.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 80954 } ], "responses": { "202": { "description": "Snapshot deletion job enqueued; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 1189, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/1189", "tableId": "in.c-main.another", "operationName": "tableSnapshotDelete", "operationParams": { "snapshotId": "80954" }, "createdTime": "2013-07-08T10:01:03+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "221", "description": "Master Token" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "403": { "description": "The token does not have write access to the bucket of the snapshotted table (`accessDenied`)." }, "404": { "description": "The snapshot or its bucket was not found (`storage.snapshots.notFound`, `storage.buckets.notFound`)." } } } }, "/v2/storage/stats": { "get": { "tags": [ "Stats" ], "summary": "Stats detail", "description": "Gets stats for a given Run Id. Provides the count of imported/exported tables and files in a specified run with durations.", "operationId": "get_/v2/storage/stats::StatsListAction", "parameters": [ { "name": "runId", "in": "query", "description": "Id of the run to list stats for.", "required": true, "schema": { "description": "Id of the run to list stats for.", "type": "string" } } ], "responses": { "200": { "description": "Statistics for the run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsListResponse" }, "example": { "tables": { "import": { "totalCount": 1, "tables": [ { "id": "out.c-futurelytics.order_lines", "count": 1, "durationTotalSeconds": 103.53275680542 } ] }, "export": { "totalCount": 0, "tables": [] } }, "files": { "total": { "count": 5, "dataSizeBytes": { "total": 4916667019, "mean": 983333403.8, "max": 4552728847, "min": 51 } }, "tags": { "other": 0, "tags": [] } } } } } }, "400": { "description": "Returned when `runId` is missing or blank." } } } }, "/v2/storage": { "get": { "tags": [ "Miscellaneous" ], "summary": "Storage API index", "description": "Returns information about the stack: services, features and available components. See the\n[Keboola Developers documentation](https://developers.keboola.com/overview/) for more about\nthe component architecture.\n\nIn case the system, or a project is under maintenance, you will receive a `503` response. Maintenance typically applies to a single project, for example due to migration. Be sure to use the `Retry-After` header when accessing the API programatically.", "operationId": "get_/v2/storage::StorageIndexAction", "parameters": [ { "name": "exclude", "in": "query", "description": "Comma-separated list of items to exclude from the response. `components` omits the `components` field; `componentDetails` reduces each component to `id`, `name`, `type`, `ico64`, `ico128`, `features`, `flags`, `description` and `categories`.", "required": false, "schema": { "type": "string" }, "example": "componentDetails" } ], "responses": { "200": { "description": "Stack info including services, features, and components.", "content": { "application/json": { "schema": { "required": [ "stack", "host", "api", "version", "revision", "documentation", "services", "features", "urlTemplates" ], "properties": { "stack": { "description": "Identifier of the stack the project runs on.", "type": "string" }, "host": { "description": "Hostname of the API node that served the request.", "type": "string" }, "api": { "type": "string", "example": "storage" }, "version": { "description": "API version resolved from the request.", "type": "string", "example": "v2" }, "revision": { "description": "Deployed application revision.", "type": "string" }, "documentation": { "type": "string", "example": "https://api.keboola.com/?service=storage" }, "services": { "type": "array", "items": { "required": [ "id", "url" ], "properties": { "id": { "type": "string", "example": "docker-runner" }, "url": { "type": "string", "example": "https://docker-runner.keboola.com" } }, "type": "object" } }, "features": { "type": "array", "items": { "type": "string" } }, "urlTemplates": { "required": [ "orchestrationJob" ], "properties": { "orchestrationJob": { "type": "string" } }, "type": "object" }, "components": { "description": "Present unless excluded via `exclude=components`. Each item is `ComponentMinimalInfoResponse` with `exclude=componentDetails`, otherwise `ComponentArrayRead`.", "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/ComponentArrayRead" }, { "$ref": "#/components/schemas/ComponentMinimalInfoResponse" } ] } } }, "type": "object" } } } }, "503": { "description": "Returned by any Storage API endpoint when the authenticated project is under maintenance (disabled, e.g. during a migration). Use the `Retry-After` header when accessing the API programmatically.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "maintenance" }, "estimatedEndTime": { "type": "string", "format": "date-time", "example": "2013-05-25T10:30:44+02:00", "nullable": true }, "reason": { "type": "string", "example": "The system is down for maintenance", "nullable": true } }, "type": "object" } } } } } } }, "/v2/storage/branch/{branchId}/tables/{tableId}/alias-columns-auto-sync": { "post": { "tags": [ "Table Aliases" ], "summary": "Enable Column Synchronization", "description": "Enables automatic column synchronization between the alias and source table. All columns from the source table will be immediately synchronized into the alias table and kept in sync on later source column changes. The persisted alias VIEW is recreated when the backend uses one.", "operationId": "post_/v2/storage/branch/{branchId}/tables/{tableId}/alias-columns-auto-sync::AliasColumnsAutoSyncEnableAction", "parameters": [ { "name": "tableId", "in": "path", "description": "ID of the alias table (e.g. `in.c-main.test-alias`).", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main.test-alias" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Alias columns auto-sync enabled." }, "400": { "description": "The table is not a simple alias (`storage.tables.aliasColumnsAutoSyncNotAllowed`), or its bucket is exposed on Snowflake and the alias reads a linked or external bucket (`storage.tables.aliasSourceOutsideProjectInExposedBucket`)." }, "409": { "description": "Another operation holds the alias lock (`core.lock.lockIsAlreadyUsed`); retry." }, "403": { "description": "Access denied." }, "404": { "description": "The table or its bucket was not found (`storage.tables.notFound`, `storage.buckets.notFound`)." }, "503": { "description": "The bucket or its backend is under maintenance." } } }, "delete": { "tags": [ "Table Aliases" ], "summary": "Disable Column Synchronization", "description": "Disables automatic column synchronization between the alias and source table. Columns from the source table will not be synchronized with the alias table any more: the alias column list is frozen at the source table's current columns, and when you add new columns into the source table, they will not propagate to the alias. Later you can modify the alias columns by the table columns methods. The persisted alias VIEW is recreated when the backend uses one. Rejected when the alias has dependent aliases of its own.", "operationId": "delete_/v2/storage/branch/{branchId}/tables/{tableId}/alias-columns-auto-sync::AliasColumnsAutoSyncDisableAction", "parameters": [ { "name": "tableId", "in": "path", "description": "ID of the alias table (e.g. `in.c-main.test-alias`).", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main.test-alias" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Alias columns auto-sync disabled." }, "400": { "description": "The table is not a simple alias (`storage.tables.aliasColumnsAutoSyncNotAllowed`), has dependent aliases (`storage.tables.hasDependentAliases`), or its bucket is exposed on Snowflake and the alias reads a linked or external bucket (`storage.tables.aliasSourceOutsideProjectInExposedBucket`)." }, "409": { "description": "Another operation holds the alias lock (`core.lock.lockIsAlreadyUsed`); retry." }, "403": { "description": "Access denied." }, "404": { "description": "The table or its bucket was not found (`storage.tables.notFound`, `storage.buckets.notFound`)." }, "503": { "description": "The bucket or its backend is under maintenance." } } } }, "/v2/storage/tables/{tableId}/alias-columns-auto-sync": { "post": { "tags": [ "Table Aliases" ], "summary": "Enable Column Synchronization", "description": "Enables automatic column synchronization between the alias and source table. All columns from the source table will be immediately synchronized into the alias table and kept in sync on later source column changes. The persisted alias VIEW is recreated when the backend uses one.", "operationId": "post_/v2/storage/tables/{tableId}/alias-columns-auto-sync::AliasColumnsAutoSyncEnableAction", "parameters": [ { "name": "tableId", "in": "path", "description": "ID of the alias table (e.g. `in.c-main.test-alias`).", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main.test-alias" } ], "responses": { "204": { "description": "Alias columns auto-sync enabled." }, "400": { "description": "The table is not a simple alias (`storage.tables.aliasColumnsAutoSyncNotAllowed`), or its bucket is exposed on Snowflake and the alias reads a linked or external bucket (`storage.tables.aliasSourceOutsideProjectInExposedBucket`)." }, "409": { "description": "Another operation holds the alias lock (`core.lock.lockIsAlreadyUsed`); retry." }, "403": { "description": "Access denied." }, "404": { "description": "The table or its bucket was not found (`storage.tables.notFound`, `storage.buckets.notFound`)." }, "503": { "description": "The bucket or its backend is under maintenance." } } }, "delete": { "tags": [ "Table Aliases" ], "summary": "Disable Column Synchronization", "description": "Disables automatic column synchronization between the alias and source table. Columns from the source table will not be synchronized with the alias table any more: the alias column list is frozen at the source table's current columns, and when you add new columns into the source table, they will not propagate to the alias. Later you can modify the alias columns by the table columns methods. The persisted alias VIEW is recreated when the backend uses one. Rejected when the alias has dependent aliases of its own.", "operationId": "delete_/v2/storage/tables/{tableId}/alias-columns-auto-sync::AliasColumnsAutoSyncDisableAction", "parameters": [ { "name": "tableId", "in": "path", "description": "ID of the alias table (e.g. `in.c-main.test-alias`).", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main.test-alias" } ], "responses": { "204": { "description": "Alias columns auto-sync disabled." }, "400": { "description": "The table is not a simple alias (`storage.tables.aliasColumnsAutoSyncNotAllowed`), has dependent aliases (`storage.tables.hasDependentAliases`), or its bucket is exposed on Snowflake and the alias reads a linked or external bucket (`storage.tables.aliasSourceOutsideProjectInExposedBucket`)." }, "409": { "description": "Another operation holds the alias lock (`core.lock.lockIsAlreadyUsed`); retry." }, "403": { "description": "Access denied." }, "404": { "description": "The table or its bucket was not found (`storage.tables.notFound`, `storage.buckets.notFound`)." }, "503": { "description": "The bucket or its backend is under maintenance." } } } }, "/v2/storage/tables/{tableId}/alias-filter": { "post": { "tags": [ "Table Aliases" ], "summary": "Update Alias Filter", "description": "Using this API call, you can update an existing filter. You can also set a new filter, but the alias must be created with the `aliasFilter` parameter.\n\nFields omitted from the request keep the table's current filter value. Only simple aliases without dependent aliases are accepted. Filtered aliases are deprecated. Not available in development branches.", "operationId": "post_/v2/storage/tables/{tableId}/alias-filter::AliasFilterSetAction", "parameters": [ { "name": "tableId", "in": "path", "description": "ID of the alias table (e.g. `in.c-main.test-alias`).", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main.test-alias" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SetAliasFilterRequest" } ] } } } }, "responses": { "200": { "description": "The alias table with the filter applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AliasFilterSetResponse" }, "example": { "uri": "https://connection.keboola.com/v2/storage/tables/in.c-main.test-alias", "id": "in.c-main.test-alias", "name": "test-alias", "displayName": "test-alias", "transactional": false, "primaryKey": [], "indexType": null, "indexKey": [], "distributionType": null, "distributionKey": [], "syntheticPrimaryKeyEnabled": false, "created": "2017-02-13T13:53:31+0100", "lastImportDate": "2016-07-07T11:25:32+0200", "lastChangeDate": "2016-07-07T11:25:34+0200", "rowsCount": null, "dataSizeBytes": null, "isAlias": true, "isAliasable": false, "isTyped": false, "isDescriptionSystemManaged": false, "timestampType": "MANAGED", "tableType": "table", "path": "database_name.c-main.test-alias", "sourceTable": { "id": "in.c-main.data", "uri": "https://connection.keboola.com/v2/storage/tables/in.c-main.data", "project": { "id": 578, "name": "Odinuv Sandbox" } }, "aliasColumnsAutoSync": false, "aliasFilter": { "column": "campaign_id", "operator": "eq", "values": [ "68abf5473f" ] }, "isPersisted": false } } } }, "400": { "description": "The table is not a simple alias (`storage.tables.aliasFilteringNotAllowed`), the table has dependent aliases (`storage.tables.hasDependentAliases`), the filter column does not exist on the source table (`storage.tables.columnNotExists`), the request failed validation (`storage.tables.validation`), or the source table does not support timestamp based filters (`storage.tables.doesNotSupportTimestampBasedFilters`)." }, "403": { "description": "Access denied." }, "404": { "description": "The table or its bucket was not found (`storage.tables.notFound`, `storage.buckets.notFound`)." }, "503": { "description": "The bucket or its backend is under maintenance." } } }, "delete": { "tags": [ "Table Aliases" ], "summary": "Remove Alias Filter", "description": "Deletes a filter from an alias. The alias table will contain all rows from the source table and the alias statistics are restored from its source table. Filtered aliases are deprecated. Not available in development branches.", "operationId": "delete_/v2/storage/tables/{tableId}/alias-filter::AliasFilterDeleteAction", "parameters": [ { "name": "tableId", "in": "path", "description": "ID of the alias table (e.g. `in.c-main.test-alias`).", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main.test-alias" } ], "responses": { "204": { "description": "Alias filter removed." }, "400": { "description": "The table is not a simple alias (`storage.tables.aliasFilteringNotAllowed`)." }, "403": { "description": "Access denied." }, "404": { "description": "The table or its bucket was not found (`storage.tables.notFound`, `storage.buckets.notFound`)." }, "503": { "description": "The bucket or its backend is under maintenance." } } } }, "/v2/storage/branch/{branchId}/tables/{id}/columns": { "post": { "tags": [ "Tables" ], "summary": "Add column to table", "description": "Adds a new column to an existing table.\n\n*Attributes `definition` and `basetype` are allowed (and required) for typed tables created via table definition.*\nThe request body shape depends on the table backend: `SnowflakeAddColumnToTableRequest` / `BigqueryAddColumnToTableRequest` for typed tables, `ColumnCreateRequest` for untyped tables.\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 [ColumnCreateJobResult](#model-ColumnCreateJobResult).\n\n Parameters of job will be [TableColumnAddJobParams](#components-schemas-TableColumnAddJobParams).", "operationId": "post_/v2/storage/branch/{branchId}/tables/{id}/columns::ColumnCreateAction", "parameters": [ { "name": "id", "in": "path", "description": "Table string id (e.g. `in.c-main.orders`).", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.orders" }, { "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": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SnowflakeAddColumnToTableRequest" }, { "$ref": "#/components/schemas/BigqueryAddColumnToTableRequest" }, { "$ref": "#/components/schemas/ColumnCreateRequest" } ] }, "example": { "name": "new-column" } } } }, "responses": { "400": { "description": "Invalid request body, or the backend does not support adding columns (`storage.driver.unsupportedOperation`)." }, "404": { "description": "The table or its bucket was not found (`storage.tables.notFound`)." }, "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/ColumnCreateJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/ColumnCreateJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/TableColumnAddJobParams" } } } } }, "/v2/storage/tables/{id}/columns": { "post": { "tags": [ "Tables" ], "summary": "Add column to table", "description": "Adds a new column to an existing table.\n\n*Attributes `definition` and `basetype` are allowed (and required) for typed tables created via table definition.*\nThe request body shape depends on the table backend: `SnowflakeAddColumnToTableRequest` / `BigqueryAddColumnToTableRequest` for typed tables, `ColumnCreateRequest` for untyped tables.\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 [ColumnCreateJobResult](#model-ColumnCreateJobResult).\n\n Parameters of job will be [TableColumnAddJobParams](#components-schemas-TableColumnAddJobParams).", "operationId": "post_/v2/storage/tables/{id}/columns::ColumnCreateAction", "parameters": [ { "name": "id", "in": "path", "description": "Table string id (e.g. `in.c-main.orders`).", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.orders" }, { "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/SnowflakeAddColumnToTableRequest" }, { "$ref": "#/components/schemas/BigqueryAddColumnToTableRequest" }, { "$ref": "#/components/schemas/ColumnCreateRequest" } ] }, "example": { "name": "new-column" } } } }, "responses": { "400": { "description": "Invalid request body, or the backend does not support adding columns (`storage.driver.unsupportedOperation`)." }, "404": { "description": "The table or its bucket was not found (`storage.tables.notFound`)." }, "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/ColumnCreateJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/ColumnCreateJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/TableColumnAddJobParams" } } } } }, "/v2/storage/branch/{branchId}/tables/{tableId}/columns/{columnName}": { "delete": { "tags": [ "Tables" ], "summary": "Delete column from table", "description": "Deletes an existing column from an existing table.\nUse the optional `force` parameter to delete the column from table aliases too.\nThe job rejects deleting the last remaining column, a column that is part of the primary key, or a column referenced by an alias, unless `force` is set.\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 [ColumnDeleteJobResult](#model-ColumnDeleteJobResult).\n\n Parameters of job will be [TableColumnDeleteJobParams](#components-schemas-TableColumnDeleteJobParams).", "operationId": "delete_/v2/storage/branch/{branchId}/tables/{tableId}/columns/{columnName}::ColumnDeleteAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Table string id (e.g. `in.c-main.orders`).", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.orders" }, { "name": "columnName", "in": "path", "description": "Name of the column to delete.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "new-column" }, { "name": "force", "in": "query", "description": "Delete the column from the table and its aliases. All aliases must have `aliasColumnsAutoSync` enabled.", "required": false, "schema": { "type": "boolean", "default": false } }, { "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": { "400": { "description": "The backend does not support dropping columns (`storage.driver.unsupportedOperation`)." }, "404": { "description": "Either the table or its bucket was not found (`storage.tables.notFound`)." }, "403": { "description": "Access to the table was 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/ColumnDeleteJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/ColumnDeleteJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/TableColumnDeleteJobParams" } } } } }, "/v2/storage/tables/{tableId}/columns/{columnName}": { "delete": { "tags": [ "Tables" ], "summary": "Delete column from table", "description": "Deletes an existing column from an existing table.\nUse the optional `force` parameter to delete the column from table aliases too.\nThe job rejects deleting the last remaining column, a column that is part of the primary key, or a column referenced by an alias, unless `force` is set.\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 [ColumnDeleteJobResult](#model-ColumnDeleteJobResult).\n\n Parameters of job will be [TableColumnDeleteJobParams](#components-schemas-TableColumnDeleteJobParams).", "operationId": "delete_/v2/storage/tables/{tableId}/columns/{columnName}::ColumnDeleteAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Table string id (e.g. `in.c-main.orders`).", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.orders" }, { "name": "columnName", "in": "path", "description": "Name of the column to delete.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "new-column" }, { "name": "force", "in": "query", "description": "Delete the column from the table and its aliases. All aliases must have `aliasColumnsAutoSync` enabled.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "X-KBC-Backend", "in": "header", "schema": { "schema": "BackendConfigurationRequest", "properties": { "context": { "type": "string", "nullable": true, "minLength": 1 } }, "type": "object" } } ], "responses": { "400": { "description": "The backend does not support dropping columns (`storage.driver.unsupportedOperation`)." }, "404": { "description": "Either the table or its bucket was not found (`storage.tables.notFound`)." }, "403": { "description": "Access to the table was 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/ColumnDeleteJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/ColumnDeleteJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/TableColumnDeleteJobParams" } } } } }, "/v2/storage/branch/{branchId}/tables/{id}/columns/{column}/definition": { "put": { "tags": [ "Tables" ], "summary": "Update Column Definition", "description": "Updates a column of a table with typed columns. *Snowflake, BigQuery only.*\n\nRequest is handled asynchronously which means that the create request is created and added to a queue and the job resource URL for status polling is returned.\n\n*BigQuery* executes each change of definition in a single atomic operation. If one of the operations fails (e.g. trying to set string DEFAULT value on NUMERIC column), job ends in error (even if other operations succeeded) with description of each operation.\n\nSupported alterations:\n\n| | Snowflake | BigQuery |\n| --- | --- | --- |\n| Add default | \u274c | \u2705 |\n| Change default | \u274c | \u2705 |\n| Drop default | \u2705 | \u2705 |\n| Set as nullable | \u2705 | \u2705 |\n| Set as required | \u2705 | \u274c |\n| Change type | \u274c | \u274c |\n| Increase the length of a text column | \u2705 | \u2705 |\n| Decrease the length of a text column | \u274c | \u274c |\n| Increase the precision of a numeric column | \u2705 | \u2705 |\n| Decrease the precision of a numeric column | \u274c | \u274c |\n| Change the scale of a numeric column | \u274c | \u2705 |\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 [TableColumnsDefinitionUpdateJobParams](#components-schemas-TableColumnsDefinitionUpdateJobParams).", "operationId": "put_/v2/storage/branch/{branchId}/tables/{id}/columns/{column}/definition::DefinitionUpdateAction", "parameters": [ { "name": "id", "in": "path", "description": "The table Id.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.orders" }, { "name": "column", "in": "path", "description": "The column name.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "short_int" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SnowflakeColumnsDefinitionUpdateRequest" }, { "$ref": "#/components/schemas/BigQueryColumnsDefinitionUpdateRequest" } ] } } } }, "responses": { "400": { "description": "Validation error in the request payload, or the external table schema is outdated." }, "403": { "description": "Access to the table was denied." }, "404": { "description": "Either bucket (`storage.buckets.notFound`), table (`storage.tables.notFound`) or column was not found." }, "422": { "description": "The backend does not support column 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/TableColumnsDefinitionUpdateJobParams" } } } } }, "/v2/storage/tables/{id}/columns/{column}/definition": { "put": { "tags": [ "Tables" ], "summary": "Update Column Definition", "description": "Updates a column of a table with typed columns. *Snowflake, BigQuery only.*\n\nRequest is handled asynchronously which means that the create request is created and added to a queue and the job resource URL for status polling is returned.\n\n*BigQuery* executes each change of definition in a single atomic operation. If one of the operations fails (e.g. trying to set string DEFAULT value on NUMERIC column), job ends in error (even if other operations succeeded) with description of each operation.\n\nSupported alterations:\n\n| | Snowflake | BigQuery |\n| --- | --- | --- |\n| Add default | \u274c | \u2705 |\n| Change default | \u274c | \u2705 |\n| Drop default | \u2705 | \u2705 |\n| Set as nullable | \u2705 | \u2705 |\n| Set as required | \u2705 | \u274c |\n| Change type | \u274c | \u274c |\n| Increase the length of a text column | \u2705 | \u2705 |\n| Decrease the length of a text column | \u274c | \u274c |\n| Increase the precision of a numeric column | \u2705 | \u2705 |\n| Decrease the precision of a numeric column | \u274c | \u274c |\n| Change the scale of a numeric column | \u274c | \u2705 |\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 [TableColumnsDefinitionUpdateJobParams](#components-schemas-TableColumnsDefinitionUpdateJobParams).", "operationId": "put_/v2/storage/tables/{id}/columns/{column}/definition::DefinitionUpdateAction", "parameters": [ { "name": "id", "in": "path", "description": "The table Id.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.orders" }, { "name": "column", "in": "path", "description": "The column name.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "short_int" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SnowflakeColumnsDefinitionUpdateRequest" }, { "$ref": "#/components/schemas/BigQueryColumnsDefinitionUpdateRequest" } ] } } } }, "responses": { "400": { "description": "Validation error in the request payload, or the external table schema is outdated." }, "403": { "description": "Access to the table was denied." }, "404": { "description": "Either bucket (`storage.buckets.notFound`), table (`storage.tables.notFound`) or column was not found." }, "422": { "description": "The backend does not support column 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/TableColumnsDefinitionUpdateJobParams" } } } } }, "/v2/storage/branch/{branchId}/tables/{id}/rows": { "delete": { "tags": [ "Tables" ], "summary": "Delete table rows", "description": "Deletes all rows matching the specified filter. Without any filter the request is rejected unless `allowTruncate` is set.\nFilters can be sent as a JSON body or, for backwards compatibility, as query string parameters.\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 [DeleteRowsJobResult](#model-DeleteRowsJobResult).\n\n Parameters of job will be [TableRowsDeleteJobParams](#components-schemas-TableRowsDeleteJobParams).", "operationId": "delete_/v2/storage/branch/{branchId}/tables/{id}/rows::DeleteRowsAction", "parameters": [ { "name": "id", "in": "path", "description": "Table string id (e.g. `in.c-main.orders`).", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.orders" }, { "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": { "properties": { "changedSince": { "description": "Filtering by import date - the import timestamp is stored within each row. Accepts a unix timestamp or any date accepted by strtotime.", "type": "string", "example": "-2 days", "nullable": true }, "changedUntil": { "description": "Filtering by import date - the import timestamp is stored within each row. Accepts a unix timestamp or any date accepted by strtotime.", "type": "string", "example": "2013-02-12T15:19:21+00:00", "nullable": true }, "whereColumn": { "description": "Deprecated, use `whereFilters` instead. Column for deleting only matching rows.", "type": "string", "example": "id", "nullable": true, "deprecated": true }, "whereValues": { "description": "Deprecated, use `whereFilters` instead. Values for deleting only matching rows.", "type": "array", "items": { "type": "string" }, "example": [ "12344" ], "nullable": true, "deprecated": true }, "whereOperator": { "description": "Deprecated, use `whereFilters` instead. Operator for value comparison.", "type": "string", "nullable": true, "deprecated": true, "default": "eq", "enum": [ "eq", "ne" ] }, "whereFilters": { "description": "Row filters; all filters must match.", "type": "array", "items": { "required": [ "column" ], "properties": { "column": { "description": "Column which should be matched.", "type": "string", "example": "id" }, "operator": { "description": "Operator for value comparison. `eq`/`ne` can be used with multiple values; `gt|ge|lt|le` require `dataType`.", "type": "string", "default": "eq", "enum": [ "eq", "ne", "gt", "ge", "lt", "le" ] }, "values": { "description": "Values to compare. Exclusive with `valuesByTableInWorkspace`.", "type": "array", "items": { "type": "string" }, "example": [ "12344" ] }, "valuesByTableInWorkspace": { "description": "Take the values from a column of a table in a workspace. Exclusive with `values`. Snowflake/BigQuery only.", "properties": { "workspaceId": { "description": "ID of the workspace (returned by Storage API).", "type": "integer", "example": 12345 }, "table": { "description": "Exact name of the table present in the workspace.", "type": "string", "example": "ids_to_delete" }, "column": { "description": "Column whose values (all rows) are used to delete rows by. Its data type has to match the filtered column.", "type": "string", "example": "id" } }, "type": "object" }, "dataType": { "description": "Required for comparing numeric values with `gt|ge|lt|le`. Snowflake accepts only `INTEGER` and `DOUBLE`; BigQuery converts the listed types to its equivalents.", "type": "string", "enum": [ "INTEGER", "DOUBLE", "BIGINT", "REAL", "DECIMAL" ] }, "type": { "description": "How filter values are interpreted. `TIME_STRING` values are parsed as date/time strings (strtotime or unix timestamp) and converted to UTC timestamps; `dataType` must be empty.", "type": "string", "default": "SCALAR", "enum": [ "SCALAR", "TIME_STRING" ] } }, "type": "object" }, "nullable": true }, "allowTruncate": { "description": "Confirms that you really want to delete all rows when no filter is specified.", "type": "boolean", "default": false } }, "type": "object" }, "example": { "whereFilters": [ { "column": "id", "operator": "eq", "values": [ "12344" ] } ] } } } }, "responses": { "400": { "description": "Invalid filter, the table is an alias (`storage.tables.aliasRowsDeleteNotAllowed`), no filter without `allowTruncate` (`storage.tables.validation.unintendedTruncation`), the backend does not support the operation (`storage.driver.unsupportedOperation`), the workspace is a read-only reader workspace, or the table does not support timestamp-based filters." }, "403": { "description": "The token has no write access to the bucket (`accessDenied`)." }, "404": { "description": "The table or its bucket was not found (`storage.tables.notFound`)." }, "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/DeleteRowsJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteRowsJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/TableRowsDeleteJobParams" } } } } }, "/v2/storage/tables/{id}/rows": { "delete": { "tags": [ "Tables" ], "summary": "Delete table rows", "description": "Deletes all rows matching the specified filter. Without any filter the request is rejected unless `allowTruncate` is set.\nFilters can be sent as a JSON body or, for backwards compatibility, as query string parameters.\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 [DeleteRowsJobResult](#model-DeleteRowsJobResult).\n\n Parameters of job will be [TableRowsDeleteJobParams](#components-schemas-TableRowsDeleteJobParams).", "operationId": "delete_/v2/storage/tables/{id}/rows::DeleteRowsAction", "parameters": [ { "name": "id", "in": "path", "description": "Table string id (e.g. `in.c-main.orders`).", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.orders" }, { "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": { "properties": { "changedSince": { "description": "Filtering by import date - the import timestamp is stored within each row. Accepts a unix timestamp or any date accepted by strtotime.", "type": "string", "example": "-2 days", "nullable": true }, "changedUntil": { "description": "Filtering by import date - the import timestamp is stored within each row. Accepts a unix timestamp or any date accepted by strtotime.", "type": "string", "example": "2013-02-12T15:19:21+00:00", "nullable": true }, "whereColumn": { "description": "Deprecated, use `whereFilters` instead. Column for deleting only matching rows.", "type": "string", "example": "id", "nullable": true, "deprecated": true }, "whereValues": { "description": "Deprecated, use `whereFilters` instead. Values for deleting only matching rows.", "type": "array", "items": { "type": "string" }, "example": [ "12344" ], "nullable": true, "deprecated": true }, "whereOperator": { "description": "Deprecated, use `whereFilters` instead. Operator for value comparison.", "type": "string", "nullable": true, "deprecated": true, "default": "eq", "enum": [ "eq", "ne" ] }, "whereFilters": { "description": "Row filters; all filters must match.", "type": "array", "items": { "required": [ "column" ], "properties": { "column": { "description": "Column which should be matched.", "type": "string", "example": "id" }, "operator": { "description": "Operator for value comparison. `eq`/`ne` can be used with multiple values; `gt|ge|lt|le` require `dataType`.", "type": "string", "default": "eq", "enum": [ "eq", "ne", "gt", "ge", "lt", "le" ] }, "values": { "description": "Values to compare. Exclusive with `valuesByTableInWorkspace`.", "type": "array", "items": { "type": "string" }, "example": [ "12344" ] }, "valuesByTableInWorkspace": { "description": "Take the values from a column of a table in a workspace. Exclusive with `values`. Snowflake/BigQuery only.", "properties": { "workspaceId": { "description": "ID of the workspace (returned by Storage API).", "type": "integer", "example": 12345 }, "table": { "description": "Exact name of the table present in the workspace.", "type": "string", "example": "ids_to_delete" }, "column": { "description": "Column whose values (all rows) are used to delete rows by. Its data type has to match the filtered column.", "type": "string", "example": "id" } }, "type": "object" }, "dataType": { "description": "Required for comparing numeric values with `gt|ge|lt|le`. Snowflake accepts only `INTEGER` and `DOUBLE`; BigQuery converts the listed types to its equivalents.", "type": "string", "enum": [ "INTEGER", "DOUBLE", "BIGINT", "REAL", "DECIMAL" ] }, "type": { "description": "How filter values are interpreted. `TIME_STRING` values are parsed as date/time strings (strtotime or unix timestamp) and converted to UTC timestamps; `dataType` must be empty.", "type": "string", "default": "SCALAR", "enum": [ "SCALAR", "TIME_STRING" ] } }, "type": "object" }, "nullable": true }, "allowTruncate": { "description": "Confirms that you really want to delete all rows when no filter is specified.", "type": "boolean", "default": false } }, "type": "object" }, "example": { "whereFilters": [ { "column": "id", "operator": "eq", "values": [ "12344" ] } ] } } } }, "responses": { "400": { "description": "Invalid filter, the table is an alias (`storage.tables.aliasRowsDeleteNotAllowed`), no filter without `allowTruncate` (`storage.tables.validation.unintendedTruncation`), the backend does not support the operation (`storage.driver.unsupportedOperation`), the workspace is a read-only reader workspace, or the table does not support timestamp-based filters." }, "403": { "description": "The token has no write access to the bucket (`accessDenied`)." }, "404": { "description": "The table or its bucket was not found (`storage.tables.notFound`)." }, "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/DeleteRowsJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteRowsJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/TableRowsDeleteJobParams" } } } } }, "/v2/storage/branch/{branchId}/tables/{tableId}/export-async": { "post": { "tags": [ "Tables" ], "summary": "Asynchronous Export", "description": "Exports data into File Storage. The Id of the created file is returned.\nThis task is asynchronous; Id of the created file is stored in the `results` of the created job when the job is finished.\n\n#### Rows filtering\nExported rows can be filtered by `whereFilters`. Examples of filtering by `userId` column:\n\n- Single value filter: `{\"whereFilters\": [{\"column\": \"UserID\", \"values\": [\"123\"]}]}` equals to `UserId = 123`.\n- Multiple values: `{\"whereFilters\": [{\"column\": \"UserID\", \"values\": [\"123\", \"234\"]}]}` equals to `UserId IN (123,234)`.\n- Non equals operator: `{\"whereFilters\": [{\"column\": \"UserID\", \"values\": [\"123\"], \"operator\": \"ne\"}]}` equals to `UserId != 123`.\n- Greater than with cast: `{\"whereFilters\": [{\"column\": \"Price\", \"values\": [\"40.3\"], \"operator\": \"gt\", \"dataType\": \"DOUBLE\"}]}` equals to `try_to_double(Price) > 40.3`.\n- Date/time values: `{\"whereFilters\": [{\"column\": \"created_at\", \"values\": [\"2023-01-01 00:00:00\"], \"operator\": \"ge\", \"type\": \"TIME_STRING\"}]}`; values can also be unix timestamps (`\"1672531200\"`) or relative (`\"-2 days\"`).\n- Multiple filter objects are joined by AND.\n\nThe comparison operator essentially behaves like the SQL `IN` (and `NOT IN`) operator: `eq` matches if any value matches, `ne` matches if none of the values match.\n\n#### Rows sorting\nExported rows can be sorted by multiple columns via `orderBy`:\n\n- `{\"orderBy\": [{\"column\": \"UserId\"}]}` equals to `ORDER BY UserId ASC`.\n- `{\"orderBy\": [{\"column\": \"UserId\", \"order\": \"DESC\"}]}` equals to `ORDER BY UserId DESC`.\n- `{\"orderBy\": [{\"column\": \"Price\", \"order\": \"DESC\", \"dataType\": \"DOUBLE\"}]}` equals to `ORDER BY try_to_double(Price) DESC`.\n\n#### Caching\nAsynchronous exports support internal caching. When the export file for certain table export parameters was created and there were no changes in the table data since, the previous cached file will be returned.\n\n#### Job results\nOnce the job is finished, the job result shows information about the created file and caching: `{\"file\": {\"id\": 234}, \"cacheHit\": false}`.\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 [TableExportAsyncJobResponse](#model-TableExportAsyncJobResponse).\n\n Parameters of job will be [TableExportJobParams](#components-schemas-TableExportJobParams).", "operationId": "post_/v2/storage/branch/{branchId}/tables/{tableId}/export-async::ExportAsyncAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Table Id.", "required": true, "schema": { "type": "string", "pattern": "[A-Za-z0-9\\.\\-_]+" }, "example": "in.c-main.test" }, { "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/ExportTableRequest2" } } } }, "responses": { "404": { "description": "Table (`storage.tables.notFound`) or source branch not found." }, "400": { "description": "Invalid export options, or a dev-branch source used from the protected production branch." }, "403": { "description": "Token does not have read access to the table." }, "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/TableExportAsyncJobResponse" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/TableExportAsyncJobResponse" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/TableExportJobParams" } } } } }, "/v2/storage/tables/{tableId}/export-async": { "post": { "tags": [ "Tables" ], "summary": "Asynchronous Export", "description": "Exports data into File Storage. The Id of the created file is returned.\nThis task is asynchronous; Id of the created file is stored in the `results` of the created job when the job is finished.\n\n#### Rows filtering\nExported rows can be filtered by `whereFilters`. Examples of filtering by `userId` column:\n\n- Single value filter: `{\"whereFilters\": [{\"column\": \"UserID\", \"values\": [\"123\"]}]}` equals to `UserId = 123`.\n- Multiple values: `{\"whereFilters\": [{\"column\": \"UserID\", \"values\": [\"123\", \"234\"]}]}` equals to `UserId IN (123,234)`.\n- Non equals operator: `{\"whereFilters\": [{\"column\": \"UserID\", \"values\": [\"123\"], \"operator\": \"ne\"}]}` equals to `UserId != 123`.\n- Greater than with cast: `{\"whereFilters\": [{\"column\": \"Price\", \"values\": [\"40.3\"], \"operator\": \"gt\", \"dataType\": \"DOUBLE\"}]}` equals to `try_to_double(Price) > 40.3`.\n- Date/time values: `{\"whereFilters\": [{\"column\": \"created_at\", \"values\": [\"2023-01-01 00:00:00\"], \"operator\": \"ge\", \"type\": \"TIME_STRING\"}]}`; values can also be unix timestamps (`\"1672531200\"`) or relative (`\"-2 days\"`).\n- Multiple filter objects are joined by AND.\n\nThe comparison operator essentially behaves like the SQL `IN` (and `NOT IN`) operator: `eq` matches if any value matches, `ne` matches if none of the values match.\n\n#### Rows sorting\nExported rows can be sorted by multiple columns via `orderBy`:\n\n- `{\"orderBy\": [{\"column\": \"UserId\"}]}` equals to `ORDER BY UserId ASC`.\n- `{\"orderBy\": [{\"column\": \"UserId\", \"order\": \"DESC\"}]}` equals to `ORDER BY UserId DESC`.\n- `{\"orderBy\": [{\"column\": \"Price\", \"order\": \"DESC\", \"dataType\": \"DOUBLE\"}]}` equals to `ORDER BY try_to_double(Price) DESC`.\n\n#### Caching\nAsynchronous exports support internal caching. When the export file for certain table export parameters was created and there were no changes in the table data since, the previous cached file will be returned.\n\n#### Job results\nOnce the job is finished, the job result shows information about the created file and caching: `{\"file\": {\"id\": 234}, \"cacheHit\": false}`.\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 [TableExportAsyncJobResponse](#model-TableExportAsyncJobResponse).\n\n Parameters of job will be [TableExportJobParams](#components-schemas-TableExportJobParams).", "operationId": "post_/v2/storage/tables/{tableId}/export-async::ExportAsyncAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Table Id.", "required": true, "schema": { "type": "string", "pattern": "[A-Za-z0-9\\.\\-_]+" }, "example": "in.c-main.test" }, { "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/ExportTableRequest2" } } } }, "responses": { "404": { "description": "Table (`storage.tables.notFound`) or source branch not found." }, "400": { "description": "Invalid export options, or a dev-branch source used from the protected production branch." }, "403": { "description": "Token does not have read access to the table." }, "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/TableExportAsyncJobResponse" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/TableExportAsyncJobResponse" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/TableExportJobParams" } } } } }, "/v2/storage/branch/{branchId}/tables/{id}/import-async": { "post": { "tags": [ "Tables" ], "summary": "Import data asynchronously", "description": "Imports data into an existing table from a CSV file or from a workspace. The source is selected by the request body.\n\n#### From a CSV file\nThe actual data must be provided in **dataFileId**. An imported file can be sliced into multiple chunks; the conditions described in [File Uploads](#tag/Files) must be satisfied.\nThe CSV file can be raw or gzipped. Gzipped files must have the extension `.gz`. A typical asynchronous import negotiation consists of these steps:\n\n1. Upload a CSV file using [File Upload](#tag/Files).\n2. Submit an asynchronous import request with `dataFileId` set to the File ID returned in the previous step.\n3. Poll job resource returned in the previous step until the `status` is `success` or `error`.\n\nSpecific behavior of BigQuery: if the `treatValuesAsNull` parameter is an empty array in the request, no values will be converted to NULL.\n\n#### From a workspace\nThe actual data must be provided in **dataWorkspaceId** and **dataObject** (older `dataTableName` is deprecated). Import from table and file workspace is supported.\n\n- For **table workspace** use `dataWorkspaceId` and set `dataObject` with name of source table.\n- For **file workspace** use `dataWorkspaceId` and `dataObject` can be a single file `file.csv`, a folder `folder/` (mind the trailing slash) or a manifest `file.csvmanifest`.\n- For **file workspace** always use `columns[]` attribute with list of imported columns.\n\nFurther information can be found in the [Developers Documentation](https://developers.keboola.com/integrate/storage/api/import-export/).", "operationId": "post_/v2/storage/branch/{branchId}/tables/{id}/import-async::ImportAsyncAction", "parameters": [ { "name": "id", "in": "path", "description": "Target table ID.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.test" }, { "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": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ImportDataAsyncFromFileRequest" }, { "$ref": "#/components/schemas/ImportDataAsyncFromWorkspaceRequest" } ] } } } }, "responses": { "202": { "description": "Import job accepted; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 22070846, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/22070846", "tableId": "in.c-main.test", "operationName": "tableImport", "operationParams": { "params": { "incremental": false, "source": [], "withoutHeaders": false, "columns": [], "delimiter": ",", "enclosure": "\"" }, "source": { "fileId": 12345, "type": "file" }, "queue": "main_fast" }, "createdTime": "2017-02-13T12:51:48+0100", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "Validation error, import into an alias table, import from a reader workspace or a deactivated one (`workspace.workspaceDeactivated`), or the backend does not support the operation (`storage.driver.unsupportedOperation`)." }, "403": { "description": "Write access to the table or access to the source file was denied." }, "404": { "description": "Table (`storage.tables.notFound`), bucket (`storage.buckets.notFound`), source file or branch was not found." } } } }, "/v2/storage/tables/{id}/import-async": { "post": { "tags": [ "Tables" ], "summary": "Import data asynchronously", "description": "Imports data into an existing table from a CSV file or from a workspace. The source is selected by the request body.\n\n#### From a CSV file\nThe actual data must be provided in **dataFileId**. An imported file can be sliced into multiple chunks; the conditions described in [File Uploads](#tag/Files) must be satisfied.\nThe CSV file can be raw or gzipped. Gzipped files must have the extension `.gz`. A typical asynchronous import negotiation consists of these steps:\n\n1. Upload a CSV file using [File Upload](#tag/Files).\n2. Submit an asynchronous import request with `dataFileId` set to the File ID returned in the previous step.\n3. Poll job resource returned in the previous step until the `status` is `success` or `error`.\n\nSpecific behavior of BigQuery: if the `treatValuesAsNull` parameter is an empty array in the request, no values will be converted to NULL.\n\n#### From a workspace\nThe actual data must be provided in **dataWorkspaceId** and **dataObject** (older `dataTableName` is deprecated). Import from table and file workspace is supported.\n\n- For **table workspace** use `dataWorkspaceId` and set `dataObject` with name of source table.\n- For **file workspace** use `dataWorkspaceId` and `dataObject` can be a single file `file.csv`, a folder `folder/` (mind the trailing slash) or a manifest `file.csvmanifest`.\n- For **file workspace** always use `columns[]` attribute with list of imported columns.\n\nFurther information can be found in the [Developers Documentation](https://developers.keboola.com/integrate/storage/api/import-export/).", "operationId": "post_/v2/storage/tables/{id}/import-async::ImportAsyncAction", "parameters": [ { "name": "id", "in": "path", "description": "Target table ID.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.test" }, { "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/ImportDataAsyncFromFileRequest" }, { "$ref": "#/components/schemas/ImportDataAsyncFromWorkspaceRequest" } ] } } } }, "responses": { "202": { "description": "Import job accepted; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 22070846, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/22070846", "tableId": "in.c-main.test", "operationName": "tableImport", "operationParams": { "params": { "incremental": false, "source": [], "withoutHeaders": false, "columns": [], "delimiter": ",", "enclosure": "\"" }, "source": { "fileId": 12345, "type": "file" }, "queue": "main_fast" }, "createdTime": "2017-02-13T12:51:48+0100", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } } } }, "400": { "description": "Validation error, import into an alias table, import from a reader workspace or a deactivated one (`workspace.workspaceDeactivated`), or the backend does not support the operation (`storage.driver.unsupportedOperation`)." }, "403": { "description": "Write access to the table or access to the source file was denied." }, "404": { "description": "Table (`storage.tables.notFound`), bucket (`storage.buckets.notFound`), source file or branch was not found." } } } }, "/v2/storage/branch/{branchId}/tables/{tableId}/import": { "post": { "tags": [ "Tables" ], "summary": "Import data into a table (synchronous, deprecated)", "description": "Imports an uploaded CSV file into an existing table and waits for the import to finish.\nThis endpoint is deprecated; use the asynchronous\n`POST /v2/storage/tables/{id}/import-async` endpoint instead.\n\nThe CSV file must have a header row with column names, unless `withoutHeaders` is used.\nEvery column already present in the table must also be present in the CSV; any CSV column\nnot yet on the table is created automatically. The file may be compressed - a `.gz`,\n`.gzip` or `.zip` extension makes it unpacked before the import.", "operationId": "post_/v2/storage/branch/{branchId}/tables/{tableId}/import::ImportSyncAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Table string id (e.g. `in.c-main.users`).", "required": true, "schema": { "type": "string", "pattern": "[^/]+" } }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "description": "The imported data is taken from \"dataString\" (inline CSV) when it is set to a non-empty value other than \"0\"; otherwise the uploaded \"data\" file is used. If neither yields data the request fails with a 400 error.", "properties": { "data": { "description": "CSV file to import. Used when \"dataString\" is empty, unset, or \"0\".", "type": "string", "format": "binary" }, "dataString": { "description": "Inline CSV data. Takes precedence over \"data\" unless it is empty or \"0\".", "type": "string" }, "incremental": { "description": "When true, the data is appended to the table instead of replacing it.", "type": "boolean" }, "delimiter": { "description": "Field delimiter, default \",\".", "type": "string" }, "enclosure": { "description": "Field enclosure, default '\"'.", "type": "string" }, "escapedBy": { "description": "Escape character, default none.", "type": "string" }, "columns": { "description": "Comma separated list of column names, used when the file has no header.", "type": "string" }, "withoutHeaders": { "description": "When true, the first row is treated as data and the table column order is used.", "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "The import result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportSyncResponse" } } } }, "400": { "description": "Validation error in the upload, CSV or import." }, "403": { "description": "Write access to the table bucket was denied." }, "404": { "description": "The table was not found, or synchronous import is disabled on this stack." }, "503": { "description": "The bucket or its backend is under maintenance." } } } }, "/v2/storage/tables/{tableId}/import": { "post": { "tags": [ "Tables" ], "summary": "Import data into a table (synchronous, deprecated)", "description": "Imports an uploaded CSV file into an existing table and waits for the import to finish.\nThis endpoint is deprecated; use the asynchronous\n`POST /v2/storage/tables/{id}/import-async` endpoint instead.\n\nThe CSV file must have a header row with column names, unless `withoutHeaders` is used.\nEvery column already present in the table must also be present in the CSV; any CSV column\nnot yet on the table is created automatically. The file may be compressed - a `.gz`,\n`.gzip` or `.zip` extension makes it unpacked before the import.", "operationId": "post_/v2/storage/tables/{tableId}/import::ImportSyncAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Table string id (e.g. `in.c-main.users`).", "required": true, "schema": { "type": "string", "pattern": "[^/]+" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "description": "The imported data is taken from \"dataString\" (inline CSV) when it is set to a non-empty value other than \"0\"; otherwise the uploaded \"data\" file is used. If neither yields data the request fails with a 400 error.", "properties": { "data": { "description": "CSV file to import. Used when \"dataString\" is empty, unset, or \"0\".", "type": "string", "format": "binary" }, "dataString": { "description": "Inline CSV data. Takes precedence over \"data\" unless it is empty or \"0\".", "type": "string" }, "incremental": { "description": "When true, the data is appended to the table instead of replacing it.", "type": "boolean" }, "delimiter": { "description": "Field delimiter, default \",\".", "type": "string" }, "enclosure": { "description": "Field enclosure, default '\"'.", "type": "string" }, "escapedBy": { "description": "Escape character, default none.", "type": "string" }, "columns": { "description": "Comma separated list of column names, used when the file has no header.", "type": "string" }, "withoutHeaders": { "description": "When true, the first row is treated as data and the table column order is used.", "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "The import result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportSyncResponse" } } } }, "400": { "description": "Validation error in the upload, CSV or import." }, "403": { "description": "Write access to the table bucket was denied." }, "404": { "description": "The table was not found, or synchronous import is disabled on this stack." }, "503": { "description": "The bucket or its backend is under maintenance." } } } }, "/v2/storage/branch/{branchId}/tables/{tableId}/primary-key": { "post": { "tags": [ "Tables" ], "summary": "Create primary key", "description": "If a primary key is set, updates can be done on the table. A primary key can be composed of multiple columns.\nRejected when the table already has a primary key, when the backend does not support primary keys, or when the table has the synthetic primary key feature enabled.\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 [PrimaryKeyCreateJobResult](#model-PrimaryKeyCreateJobResult).\n\n Parameters of job will be [TablePrimaryKeyAddJobParams](#components-schemas-TablePrimaryKeyAddJobParams).", "operationId": "post_/v2/storage/branch/{branchId}/tables/{tableId}/primary-key::PrimaryKeyCreateAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Table string id (e.g. `in.c-main.orders`).", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.orders" }, { "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": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreatePrimaryKeyRequest" } ] } } } }, "responses": { "400": { "description": "No primary key columns were specified (`storage.validation.primaryKey`), the backend does not support primary keys (`storage.driver.unsupportedOperation`), or the table has the synthetic primary key feature enabled (`storage.tables.syntheticPrimaryKeyEnabled`)." }, "404": { "description": "Either the table or its bucket was not found (`storage.tables.notFound`)." }, "403": { "description": "Access to the table was 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/PrimaryKeyCreateJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimaryKeyCreateJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/TablePrimaryKeyAddJobParams" } } } }, "delete": { "tags": [ "Tables" ], "summary": "Remove primary key", "description": "Removes the primary key from a table.\nRejected when the backend does not support primary keys, or when the table has the synthetic primary key feature enabled.\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 [PrimaryKeyDeleteJobResult](#model-PrimaryKeyDeleteJobResult).", "operationId": "delete_/v2/storage/branch/{branchId}/tables/{tableId}/primary-key::PrimaryKeyDeleteAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Table string id (e.g. `in.c-main.orders`).", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.orders" }, { "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": { "400": { "description": "The backend does not support primary keys (`storage.driver.unsupportedOperation`), or the table has the synthetic primary key feature enabled (`storage.tables.syntheticPrimaryKeyEnabled`)." }, "404": { "description": "Either the table or its bucket was not found (`storage.tables.notFound`)." }, "403": { "description": "Access to the table was 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/PrimaryKeyDeleteJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimaryKeyDeleteJobResult" } } } } }, "/v2/storage/tables/{tableId}/primary-key": { "post": { "tags": [ "Tables" ], "summary": "Create primary key", "description": "If a primary key is set, updates can be done on the table. A primary key can be composed of multiple columns.\nRejected when the table already has a primary key, when the backend does not support primary keys, or when the table has the synthetic primary key feature enabled.\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 [PrimaryKeyCreateJobResult](#model-PrimaryKeyCreateJobResult).\n\n Parameters of job will be [TablePrimaryKeyAddJobParams](#components-schemas-TablePrimaryKeyAddJobParams).", "operationId": "post_/v2/storage/tables/{tableId}/primary-key::PrimaryKeyCreateAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Table string id (e.g. `in.c-main.orders`).", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.orders" }, { "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/CreatePrimaryKeyRequest" } ] } } } }, "responses": { "400": { "description": "No primary key columns were specified (`storage.validation.primaryKey`), the backend does not support primary keys (`storage.driver.unsupportedOperation`), or the table has the synthetic primary key feature enabled (`storage.tables.syntheticPrimaryKeyEnabled`)." }, "404": { "description": "Either the table or its bucket was not found (`storage.tables.notFound`)." }, "403": { "description": "Access to the table was 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/PrimaryKeyCreateJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimaryKeyCreateJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/TablePrimaryKeyAddJobParams" } } } }, "delete": { "tags": [ "Tables" ], "summary": "Remove primary key", "description": "Removes the primary key from a table.\nRejected when the backend does not support primary keys, or when the table has the synthetic primary key feature enabled.\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 [PrimaryKeyDeleteJobResult](#model-PrimaryKeyDeleteJobResult).", "operationId": "delete_/v2/storage/tables/{tableId}/primary-key::PrimaryKeyDeleteAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Table string id (e.g. `in.c-main.orders`).", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.orders" }, { "name": "X-KBC-Backend", "in": "header", "schema": { "schema": "BackendConfigurationRequest", "properties": { "context": { "type": "string", "nullable": true, "minLength": 1 } }, "type": "object" } } ], "responses": { "400": { "description": "The backend does not support primary keys (`storage.driver.unsupportedOperation`), or the table has the synthetic primary key feature enabled (`storage.tables.syntheticPrimaryKeyEnabled`)." }, "404": { "description": "Either the table or its bucket was not found (`storage.tables.notFound`)." }, "403": { "description": "Access to the table was 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/PrimaryKeyDeleteJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimaryKeyDeleteJobResult" } } } } }, "/v2/storage/branch/{branchId}/tables/{tableId}/profile": { "post": { "tags": [ "Tables" ], "summary": "Create profile", "description": "Create new data profile of table and its columns. Still under development. Available for BigQuery and Snowflake backends.\nThis request is asynchronous; the job result is the created profile (see `GET /v2/storage/tables/{tableId}/profile/{uuid}`).", "operationId": "post_/v2/storage/branch/{branchId}/tables/{tableId}/profile::ProfileCreateAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Table Id.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.another" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Profile job accepted; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 42, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/42", "tableId": "in.c-main.another", "operationName": "tableProfile", "operationParams": [], "createdTime": "2025-06-02T10:11:12+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "221", "description": "Master Token" } } } } }, "403": { "description": "The token has no write access to the bucket, or no read access to a read-only (linked or external) bucket (`accessDenied`)." }, "404": { "description": "Table (`storage.tables.notFound`) or bucket (`storage.buckets.notFound`) was not found." } } } }, "/v2/storage/tables/{tableId}/profile": { "post": { "tags": [ "Tables" ], "summary": "Create profile", "description": "Create new data profile of table and its columns. Still under development. Available for BigQuery and Snowflake backends.\nThis request is asynchronous; the job result is the created profile (see `GET /v2/storage/tables/{tableId}/profile/{uuid}`).", "operationId": "post_/v2/storage/tables/{tableId}/profile::ProfileCreateAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Table Id.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.another" } ], "responses": { "202": { "description": "Profile job accepted; returns job details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 42, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/42", "tableId": "in.c-main.another", "operationName": "tableProfile", "operationParams": [], "createdTime": "2025-06-02T10:11:12+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "221", "description": "Master Token" } } } } }, "403": { "description": "The token has no write access to the bucket, or no read access to a read-only (linked or external) bucket (`accessDenied`)." }, "404": { "description": "Table (`storage.tables.notFound`) or bucket (`storage.buckets.notFound`) was not found." } } } }, "/v2/storage/branch/{branchId}/tables/{tableId}/profile/{uuid}": { "get": { "tags": [ "Tables" ], "summary": "Get profile", "description": "Returns the latest data profile of the table and its columns. Use `latest` as the profile identifier.\nWhen the table has no profile yet, an empty 200 response is returned.", "operationId": "get_/v2/storage/branch/{branchId}/tables/{tableId}/profile/{uuid}::ProfileDetailAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Table Id.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.another" }, { "name": "uuid", "in": "path", "description": "Profile identifier: `latest` or a profile UUID (v7). Currently the latest profile is returned regardless of the value.", "required": true, "schema": { "type": "string", "pattern": "[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|latest" }, "example": "latest" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Latest table profile, or an empty body when no profile exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" }, "example": { "uuid": "019732aa-6f92-77ea-a715-865a695908b8", "bucketId": 13, "tableName": "in.c-main.another", "createdAt": "2025-06-02 11:55:00", "profile": { "dataSize": 1024, "rowCount": 256, "columnCount": 1 }, "columns": [ { "name": "id", "profile": { "nullCount": 7, "distinctCount": 149, "duplicateCount": 100 } } ], "profiledByToken": { "id": 221, "name": "Master Token" }, "actor": { "type": "token", "id": "221", "name": "Master Token", "adminId": null } } } } }, "403": { "description": "The token has no read access to the bucket (`accessDenied`)." }, "404": { "description": "Table (`storage.tables.notFound`) or bucket (`storage.buckets.notFound`) was not found." } } } }, "/v2/storage/tables/{tableId}/profile/{uuid}": { "get": { "tags": [ "Tables" ], "summary": "Get profile", "description": "Returns the latest data profile of the table and its columns. Use `latest` as the profile identifier.\nWhen the table has no profile yet, an empty 200 response is returned.", "operationId": "get_/v2/storage/tables/{tableId}/profile/{uuid}::ProfileDetailAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Table Id.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.another" }, { "name": "uuid", "in": "path", "description": "Profile identifier: `latest` or a profile UUID (v7). Currently the latest profile is returned regardless of the value.", "required": true, "schema": { "type": "string", "pattern": "[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|latest" }, "example": "latest" } ], "responses": { "200": { "description": "Latest table profile, or an empty body when no profile exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" }, "example": { "uuid": "019732aa-6f92-77ea-a715-865a695908b8", "bucketId": 13, "tableName": "in.c-main.another", "createdAt": "2025-06-02 11:55:00", "profile": { "dataSize": 1024, "rowCount": 256, "columnCount": 1 }, "columns": [ { "name": "id", "profile": { "nullCount": 7, "distinctCount": 149, "duplicateCount": 100 } } ], "profiledByToken": { "id": 221, "name": "Master Token" }, "actor": { "type": "token", "id": "221", "name": "Master Token", "adminId": null } } } } }, "403": { "description": "The token has no read access to the bucket (`accessDenied`)." }, "404": { "description": "Table (`storage.tables.notFound`) or bucket (`storage.buckets.notFound`) was not found." } } } }, "/v2/storage/branch/{branchId}/tables/{id}/pull": { "post": { "tags": [ "Tables" ], "summary": "Pull table from default branch to dev branch", "description": "**EXPERIMENTAL**\n\nPull table from default branch to dev branch with all data and metadata, if table already exists in dev branch, it will be overwritten.\n\nRequest is handled asynchronously which means that the create request is created and added to a queue and the job resource URL for status polling is returned.\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 [DevBranchTablePullJobParams](#components-schemas-DevBranchTablePullJobParams).", "operationId": "post_/v2/storage/branch/{branchId}/tables/{id}/pull::PullAction", "parameters": [ { "name": "branchId", "in": "path", "description": "Id of the development branch.", "required": true, "schema": { "type": "integer" }, "example": 1234 }, { "name": "id", "in": "path", "description": "The table string Id.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-bucket.production-table-1" } ], "responses": { "403": { "description": "Access denied: the token cannot write to the branch, or the branch was not found." }, "404": { "description": "Table (`storage.tables.notFound`) or bucket (`storage.buckets.notFound`) was not found in the default branch." }, "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/DevBranchTablePullJobParams" } } } } }, "/v2/storage/branch/{branchId}/tables/{id}/snapshots": { "get": { "tags": [ "Table Snapshotting" ], "summary": "List Table Snapshots", "description": "Retrieves a list of all snapshots of a table.", "operationId": "get_/v2/storage/branch/{branchId}/tables/{id}/snapshots::TableSnapshotsListAction", "parameters": [ { "name": "id", "in": "path", "description": "Table ID.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.test" }, { "name": "limit", "in": "query", "description": "Pagination limit. Omit (or pass a value <= 0) to return all snapshots.", "required": false, "schema": { "type": "integer" }, "example": 20 }, { "name": "offset", "in": "query", "description": "Pagination offset.", "required": false, "schema": { "type": "integer" }, "example": 0 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of table snapshots.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TableSnapshotResponse" } }, "example": [ { "id": "82629", "description": "Bucket backend migration (mysql -> snowflake)", "createdTime": "2016-05-26T14:26:56+0200", "type": "table", "creatorToken": { "id": 0, "description": "Internal - Bucket backend migration" }, "actor": { "type": "system", "id": "internal-bucket-backend-migration", "name": "Internal - Bucket backend migration", "adminId": null }, "uri": "https://connection.keboola.com/v2/storage/snapshots/82629", "dataFileId": 188803533 } ] } } }, "404": { "description": "The table was not found (`storage.tables.notFound`)." }, "403": { "description": "Access denied." }, "503": { "description": "Bucket or backend is under maintenance." } } }, "post": { "tags": [ "Table Snapshotting" ], "summary": "Create Table Snapshot", "description": "**Snapshot creation is not supported for tables in external buckets.**\n\nCreates a snapshot of the current state of the table. A table snapshot will contain:\n- Table data,\n- Table properties (primary key, etc.).\n\nSnapshots of an alias table contain only alias settings, actual data are not stored with the snapshot.\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 [TableSnapshotCreateJobResult](#model-TableSnapshotCreateJobResult).\n\n Parameters of job will be [TableSnapshotCreateJobParams](#components-schemas-TableSnapshotCreateJobParams).", "operationId": "post_/v2/storage/branch/{branchId}/tables/{id}/snapshots::TableSnapshotCreateAction", "parameters": [ { "name": "id", "in": "path", "description": "Table ID.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.test" }, { "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" }, "example": { "description": "My first snapshot" } } } }, "responses": { "404": { "description": "The table was not found (`storage.tables.notFound`)." }, "400": { "description": "Snapshots are not supported for tables in external buckets (`storage.buckets.snapshotNotSupported`) or by the backend (`storage.driver.unsupportedOperation`)." }, "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" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/TableSnapshotCreateJobParams" } } } } }, "/v2/storage/tables/{id}/snapshots": { "get": { "tags": [ "Table Snapshotting" ], "summary": "List Table Snapshots", "description": "Retrieves a list of all snapshots of a table.", "operationId": "get_/v2/storage/tables/{id}/snapshots::TableSnapshotsListAction", "parameters": [ { "name": "id", "in": "path", "description": "Table ID.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.test" }, { "name": "limit", "in": "query", "description": "Pagination limit. Omit (or pass a value <= 0) to return all snapshots.", "required": false, "schema": { "type": "integer" }, "example": 20 }, { "name": "offset", "in": "query", "description": "Pagination offset.", "required": false, "schema": { "type": "integer" }, "example": 0 } ], "responses": { "200": { "description": "List of table snapshots.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TableSnapshotResponse" } }, "example": [ { "id": "82629", "description": "Bucket backend migration (mysql -> snowflake)", "createdTime": "2016-05-26T14:26:56+0200", "type": "table", "creatorToken": { "id": 0, "description": "Internal - Bucket backend migration" }, "actor": { "type": "system", "id": "internal-bucket-backend-migration", "name": "Internal - Bucket backend migration", "adminId": null }, "uri": "https://connection.keboola.com/v2/storage/snapshots/82629", "dataFileId": 188803533 } ] } } }, "404": { "description": "The table was not found (`storage.tables.notFound`)." }, "403": { "description": "Access denied." }, "503": { "description": "Bucket or backend is under maintenance." } } }, "post": { "tags": [ "Table Snapshotting" ], "summary": "Create Table Snapshot", "description": "**Snapshot creation is not supported for tables in external buckets.**\n\nCreates a snapshot of the current state of the table. A table snapshot will contain:\n- Table data,\n- Table properties (primary key, etc.).\n\nSnapshots of an alias table contain only alias settings, actual data are not stored with the snapshot.\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 [TableSnapshotCreateJobResult](#model-TableSnapshotCreateJobResult).\n\n Parameters of job will be [TableSnapshotCreateJobParams](#components-schemas-TableSnapshotCreateJobParams).", "operationId": "post_/v2/storage/tables/{id}/snapshots::TableSnapshotCreateAction", "parameters": [ { "name": "id", "in": "path", "description": "Table ID.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.test" }, { "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" }, "example": { "description": "My first snapshot" } } } }, "responses": { "404": { "description": "The table was not found (`storage.tables.notFound`)." }, "400": { "description": "Snapshots are not supported for tables in external buckets (`storage.buckets.snapshotNotSupported`) or by the backend (`storage.driver.unsupportedOperation`)." }, "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" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/TableSnapshotCreateJobParams" } } } } }, "/v2/storage/branch/{branchId}/tables": { "get": { "tags": [ "Tables" ], "summary": "List all tables", "description": "Lists all tables accessible by the token. By default, all tables are returned with their attributes and information about the containing bucket.\nUse the `include` query parameter to add columns, metadata, column metadata or (for aliases) source table metadata to each item.", "operationId": "get_/v2/storage/branch/{branchId}/tables::TablesListAction", "parameters": [ { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include", "in": "query", "description": "Comma-separated list of data to include. Allowed values: attributes, buckets, bucketsWithoutSourceTables, columns, metadata, columnMetadata, sourceMetadata, sourceColumnMetadata. Default: attributes,buckets.", "required": false, "schema": { "description": "Comma-separated list of data to include. Allowed values: attributes, buckets, bucketsWithoutSourceTables, columns, metadata, columnMetadata, sourceMetadata, sourceColumnMetadata. Default: attributes,buckets.", "type": "string", "nullable": true } } ], "responses": { "200": { "description": "List of tables.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TableListItemResponse" } }, "example": [ { "uri": "https://connection.keboola.com/v2/storage/tables/in.c-keboola-ex-db-snowflake-528221294.datatypes", "id": "in.c-keboola-ex-db-snowflake-528221294.datatypes", "name": "datatypes", "displayName": "datatypes", "transactional": false, "primaryKey": [], "indexType": null, "indexKey": [], "distributionType": null, "distributionKey": [], "syntheticPrimaryKeyEnabled": false, "created": "2019-08-12T14:36:00+0200", "lastImportDate": "2019-08-12T21:16:41+0200", "lastChangeDate": "2019-08-12T21:16:41+0200", "rowsCount": 2, "dataSizeBytes": 1024, "isAlias": false, "isAliasable": true, "isTyped": false, "isDescriptionSystemManaged": false, "timestampType": "MANAGED", "tableType": "table", "path": "kbc.c-keboola-ex-db-snowflake-528221294.datatypes", "metadata": [ { "id": "206180828", "key": "KBC.createdBy.component.id", "value": "keboola.ex-db-snowflake", "provider": "system", "timestamp": "2019-08-12T14:36:08+0200" } ], "bucket": { "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-keboola-ex-db-snowflake-528221294", "id": "in.c-keboola-ex-db-snowflake-528221294", "name": "c-keboola-ex-db-snowflake-528221294", "displayName": "keboola-ex-db-snowflake-528221294", "stage": "in", "description": "", "tables": "https://connection.keboola.com/v2/storage/buckets/in.c-keboola-ex-db-snowflake-528221294", "created": "2019-08-12T14:35:55+0200", "lastChangeDate": "2019-08-12T21:16:41+0200", "isReadOnly": false, "dataSizeBytes": 1024, "rowsCount": 2, "isMaintenance": false, "backend": "snowflake", "sharing": null, "bucketSharingAllowed": true, "sharedByActor": null } } ] } } } } }, "post": { "tags": [ "Tables" ], "summary": "Create a table (not allowed)", "description": "Rejects every request with 405. A table always belongs to a bucket, so it has to be created through a bucket-scoped endpoint: `POST /buckets/{bucketId}/tables`, `POST /buckets/{bucketId}/tables-async` or `POST /buckets/{bucketId}/tables-definition`.", "operationId": "post_/v2/storage/branch/{branchId}/tables::TableCreateNotAllowedAction", "parameters": [ { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "405": { "description": "Always returned (`storage.tables.createNotAllowed`)." }, "403": { "description": "Access denied." }, "404": { "description": "The branch was not found." } } } }, "/v2/storage/tables": { "get": { "tags": [ "Tables" ], "summary": "List all tables", "description": "Lists all tables accessible by the token. By default, all tables are returned with their attributes and information about the containing bucket.\nUse the `include` query parameter to add columns, metadata, column metadata or (for aliases) source table metadata to each item.", "operationId": "get_/v2/storage/tables::TablesListAction", "parameters": [ { "name": "include", "in": "query", "description": "Comma-separated list of data to include. Allowed values: attributes, buckets, bucketsWithoutSourceTables, columns, metadata, columnMetadata, sourceMetadata, sourceColumnMetadata. Default: attributes,buckets.", "required": false, "schema": { "description": "Comma-separated list of data to include. Allowed values: attributes, buckets, bucketsWithoutSourceTables, columns, metadata, columnMetadata, sourceMetadata, sourceColumnMetadata. Default: attributes,buckets.", "type": "string", "nullable": true } } ], "responses": { "200": { "description": "List of tables.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TableListItemResponse" } }, "example": [ { "uri": "https://connection.keboola.com/v2/storage/tables/in.c-keboola-ex-db-snowflake-528221294.datatypes", "id": "in.c-keboola-ex-db-snowflake-528221294.datatypes", "name": "datatypes", "displayName": "datatypes", "transactional": false, "primaryKey": [], "indexType": null, "indexKey": [], "distributionType": null, "distributionKey": [], "syntheticPrimaryKeyEnabled": false, "created": "2019-08-12T14:36:00+0200", "lastImportDate": "2019-08-12T21:16:41+0200", "lastChangeDate": "2019-08-12T21:16:41+0200", "rowsCount": 2, "dataSizeBytes": 1024, "isAlias": false, "isAliasable": true, "isTyped": false, "isDescriptionSystemManaged": false, "timestampType": "MANAGED", "tableType": "table", "path": "kbc.c-keboola-ex-db-snowflake-528221294.datatypes", "metadata": [ { "id": "206180828", "key": "KBC.createdBy.component.id", "value": "keboola.ex-db-snowflake", "provider": "system", "timestamp": "2019-08-12T14:36:08+0200" } ], "bucket": { "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-keboola-ex-db-snowflake-528221294", "id": "in.c-keboola-ex-db-snowflake-528221294", "name": "c-keboola-ex-db-snowflake-528221294", "displayName": "keboola-ex-db-snowflake-528221294", "stage": "in", "description": "", "tables": "https://connection.keboola.com/v2/storage/buckets/in.c-keboola-ex-db-snowflake-528221294", "created": "2019-08-12T14:35:55+0200", "lastChangeDate": "2019-08-12T21:16:41+0200", "isReadOnly": false, "dataSizeBytes": 1024, "rowsCount": 2, "isMaintenance": false, "backend": "snowflake", "sharing": null, "bucketSharingAllowed": true, "sharedByActor": null } } ] } } } } }, "post": { "tags": [ "Tables" ], "summary": "Create a table (not allowed)", "description": "Rejects every request with 405. A table always belongs to a bucket, so it has to be created through a bucket-scoped endpoint: `POST /buckets/{bucketId}/tables`, `POST /buckets/{bucketId}/tables-async` or `POST /buckets/{bucketId}/tables-definition`.", "operationId": "post_/v2/storage/tables::TableCreateNotAllowedAction", "responses": { "405": { "description": "Always returned (`storage.tables.createNotAllowed`)." }, "403": { "description": "Access denied." }, "404": { "description": "The branch was not found." } } } }, "/v2/storage/branch/{branchId}/tables/{id}/metadata": { "get": { "tags": [ "Metadata" ], "summary": "List table metadata", "description": "Shows all metadata associated with the specified table.", "operationId": "get_/v2/storage/branch/{branchId}/tables/{id}/metadata::TableGetMetadataAction", "parameters": [ { "name": "id", "in": "path", "description": "Id of the table.", "required": true, "schema": { "type": "string", "pattern": "[A-Za-z0-9\\.\\-_]+" }, "example": "in.c-main.customers" }, { "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" } }, "example": [ { "id": "123", "key": "attribute_key", "value": "attribute_value", "provider": "keboola.some-komponent", "timestamp": "2016-09-19T13:02:11+0200" }, { "id": "124", "key": "another_attribute_key", "value": "attribute_value", "provider": "keboola.some-komponent", "timestamp": "2016-09-19T13:02:11+0200" } ] } } }, "403": { "description": "Returned when the token has no read access to the bucket." }, "404": { "description": "Returned when the table is not found (`storage.tables.notFound`)." } } }, "post": { "tags": [ "Metadata" ], "summary": "Create or update table metadata", "description": "Sets multiple metadata for table and columns with one call. If the given key and provider combination already exist\nfor the table, the data will be updated with the new value and timestamp. All metadata associated\nwith the table and columns are returned to the response.\n\nAt least one of the `metadata` or `columnsMetadata` object is required. Using columnName as index for `columnsMetadata` is deprecated and not recommended, rather index it by int. Please add columnName to metadata object as described in example.\n\nWhen the request is not sent as JSON (`application/x-www-form-urlencoded`, deprecated), only the table-level metadata list is returned.", "operationId": "post_/v2/storage/branch/{branchId}/tables/{id}/metadata::TableCreateOrUpdateMetadataAction", "parameters": [ { "name": "id", "in": "path", "description": "Id of the table.", "required": true, "schema": { "type": "string", "pattern": "[A-Za-z0-9\\.\\-_]+" }, "example": "in.c-main.customers" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateTableMetadataRequest" } ] } } } }, "responses": { "201": { "description": "All metadata associated with the table and its columns.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TableCreateOrUpdateMetadataResponse" }, { "description": "Table-level metadata records only; returned when the request is not sent as JSON.", "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } } ] }, "example": { "metadata": [ { "id": "19509", "key": "some-key", "value": "Some value", "provider": "test-component", "timestamp": "2017-02-13T23:36:10+0100" } ], "columnsMetadata": { "id": [ { "id": "19510", "key": "some-key", "value": "Some value", "provider": "test-component", "timestamp": "2017-02-13T23:36:10+0100" } ] } } } } }, "400": { "description": "Returned when the metadata payload is invalid (`storage.metadata.invalidParameter`)." }, "403": { "description": "Returned when the token has no write access to the bucket or the provider is protected (`storage.metadata.invalidProvider`)." }, "404": { "description": "Returned when the table (`storage.tables.notFound`), column (`storage.tables.columnNotFound`) or bucket (`storage.buckets.notFound`) is not found." } } } }, "/v2/storage/tables/{id}/metadata": { "get": { "tags": [ "Metadata" ], "summary": "List table metadata", "description": "Shows all metadata associated with the specified table.", "operationId": "get_/v2/storage/tables/{id}/metadata::TableGetMetadataAction", "parameters": [ { "name": "id", "in": "path", "description": "Id of the table.", "required": true, "schema": { "type": "string", "pattern": "[A-Za-z0-9\\.\\-_]+" }, "example": "in.c-main.customers" } ], "responses": { "200": { "description": "Table metadata list.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } }, "example": [ { "id": "123", "key": "attribute_key", "value": "attribute_value", "provider": "keboola.some-komponent", "timestamp": "2016-09-19T13:02:11+0200" }, { "id": "124", "key": "another_attribute_key", "value": "attribute_value", "provider": "keboola.some-komponent", "timestamp": "2016-09-19T13:02:11+0200" } ] } } }, "403": { "description": "Returned when the token has no read access to the bucket." }, "404": { "description": "Returned when the table is not found (`storage.tables.notFound`)." } } }, "post": { "tags": [ "Metadata" ], "summary": "Create or update table metadata", "description": "Sets multiple metadata for table and columns with one call. If the given key and provider combination already exist\nfor the table, the data will be updated with the new value and timestamp. All metadata associated\nwith the table and columns are returned to the response.\n\nAt least one of the `metadata` or `columnsMetadata` object is required. Using columnName as index for `columnsMetadata` is deprecated and not recommended, rather index it by int. Please add columnName to metadata object as described in example.\n\nWhen the request is not sent as JSON (`application/x-www-form-urlencoded`, deprecated), only the table-level metadata list is returned.", "operationId": "post_/v2/storage/tables/{id}/metadata::TableCreateOrUpdateMetadataAction", "parameters": [ { "name": "id", "in": "path", "description": "Id of the table.", "required": true, "schema": { "type": "string", "pattern": "[A-Za-z0-9\\.\\-_]+" }, "example": "in.c-main.customers" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateTableMetadataRequest" } ] } } } }, "responses": { "201": { "description": "All metadata associated with the table and its columns.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TableCreateOrUpdateMetadataResponse" }, { "description": "Table-level metadata records only; returned when the request is not sent as JSON.", "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } } ] }, "example": { "metadata": [ { "id": "19509", "key": "some-key", "value": "Some value", "provider": "test-component", "timestamp": "2017-02-13T23:36:10+0100" } ], "columnsMetadata": { "id": [ { "id": "19510", "key": "some-key", "value": "Some value", "provider": "test-component", "timestamp": "2017-02-13T23:36:10+0100" } ] } } } } }, "400": { "description": "Returned when the metadata payload is invalid (`storage.metadata.invalidParameter`)." }, "403": { "description": "Returned when the token has no write access to the bucket or the provider is protected (`storage.metadata.invalidProvider`)." }, "404": { "description": "Returned when the table (`storage.tables.notFound`), column (`storage.tables.columnNotFound`) or bucket (`storage.buckets.notFound`) is not found." } } } }, "/v2/storage/branch/{branchId}/tables/{tableId}/data-preview": { "get": { "tags": [ "Tables" ], "summary": "Data preview", "description": "Returns up to 1000 rows from a table in CSV (RFC) or JSON format. Rows can be filtered by the same filters as the asynchronous export\n(`changedSince`, `changedUntil`, `columns`, `whereFilters`, `orderBy`, `fulltextSearch`).\nFor a full table download use the asynchronous export.\n\nThe `isTruncated` flag is `true` if the value is >16k chars and the response type is JSON.\n\n#### HTTP Compression\n\nTo enable compression of the API response traffic, include the HTTP header `Accept-encoding: gzip` with the request.", "operationId": "get_/v2/storage/branch/{branchId}/tables/{tableId}/data-preview::TableDataPreviewAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Table string identifier (e.g. in.c-main.my-table).", "required": true, "schema": { "type": "string", "pattern": "[A-Za-z0-9\\.\\-_]+" } }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Limit the number of returned rows. Maximum allowed value is `1000`.", "required": false, "schema": { "description": "Limit the number of returned rows. Maximum allowed value is `1000`.", "type": "integer", "example": 100, "default": 100, "maximum": 1000, "minimum": 0 }, "example": 100 }, { "name": "changedSince", "in": "query", "description": "Filtering by import date - the import timestamp is stored within each row. Accepts a unix timestamp or any date accepted by strtotime.", "required": false, "schema": { "description": "Filtering by import date - the import timestamp is stored within each row. Accepts a unix timestamp or any date accepted by strtotime.", "type": "string", "example": "-2 days", "nullable": true }, "example": "-2 days" }, { "name": "changedUntil", "in": "query", "description": "Filtering by import date - the import timestamp is stored within each row. Accepts a unix timestamp or any date accepted by strtotime.", "required": false, "schema": { "description": "Filtering by import date - the import timestamp is stored within each row. Accepts a unix timestamp or any date accepted by strtotime.", "type": "string", "example": "2013-02-12T15:19:21+00:00", "nullable": true }, "example": "2013-02-12T15:19:21+00:00" }, { "name": "columns", "in": "query", "description": "Comma separated list of columns to export; by default all columns are exported.", "required": false, "schema": { "description": "Comma separated list of columns to export; by default all columns are exported.", "type": "string", "example": "id,name", "nullable": true }, "example": "id,name" }, { "name": "whereColumn", "in": "query", "description": "Deprecated (use `whereFilters` instead). Column for exporting only matching rows.", "required": false, "deprecated": true, "schema": { "description": "Deprecated (use `whereFilters` instead). Column for exporting only matching rows.", "type": "string", "example": "id", "nullable": true, "deprecated": true }, "example": "id" }, { "name": "whereValues[]", "in": "query", "description": "Deprecated (use `whereFilters` instead). Values for exporting only matching rows.", "required": false, "deprecated": true, "schema": { "description": "Deprecated (use `whereFilters` instead). Values for exporting only matching rows.", "type": "array", "items": { "type": "string" }, "example": [ "26" ], "nullable": true, "deprecated": true }, "example": [ "26" ] }, { "name": "whereOperator", "in": "query", "description": "Deprecated (use `whereFilters` instead). Operator for value comparison: `eq` (can be used with multiple values) or `ne`.", "required": false, "deprecated": true, "schema": { "description": "Deprecated (use `whereFilters` instead). Operator for value comparison: `eq` (can be used with multiple values) or `ne`.", "type": "string", "nullable": true, "deprecated": true, "default": "eq", "enum": [ "eq", "ne" ] } }, { "name": "format", "in": "query", "description": "Output format of the preview: `rfc` returns CSV, `json` returns JSON.", "required": false, "schema": { "description": "Output format of the preview: `rfc` returns CSV, `json` returns JSON.", "type": "string", "example": "json", "nullable": true, "default": "rfc", "enum": [ "rfc", "json" ] }, "example": "json" }, { "name": "whereFilters[]", "in": "query", "description": "Row filters (see the asynchronous export for the filter description). Sent as `whereFilters[0][column]=...`.", "required": false, "schema": { "description": "Row filters (see the asynchronous export for the filter description). Sent as `whereFilters[0][column]=...`.", "type": "array", "items": { "$ref": "#/components/schemas/WhereFiltersObject" }, "nullable": true } }, { "name": "orderBy[]", "in": "query", "description": "Sort specification. Sent as `orderBy[0][column]=...`.", "required": false, "schema": { "description": "Sort specification. Sent as `orderBy[0][column]=...`.", "type": "array", "items": { "$ref": "#/components/schemas/OrderByObject" }, "nullable": true } }, { "name": "fulltextSearch", "in": "query", "description": "Fulltext search over all data in the table. Cannot be combined with `whereFilters`. Snowflake/BigQuery only.", "required": false, "schema": { "description": "Fulltext search over all data in the table. Cannot be combined with `whereFilters`. Snowflake/BigQuery only.", "type": "string", "example": "czech", "nullable": true }, "example": "czech" }, { "name": "cache", "in": "query", "description": "A JSON preview requested without any other parameter is served from a cache that is refreshed whenever the table changes. Set to `0` to always read the data from the backend.", "required": false, "schema": { "description": "A JSON preview requested without any other parameter is served from a cache that is refreshed whenever the table changes. Set to `0` to always read the data from the backend.", "type": "boolean", "example": false, "default": true }, "example": false } ], "responses": { "200": { "description": "Table data in the requested format (CSV or JSON).", "content": { "text/csv": { "schema": { "type": "string" }, "example": "\"id\",\"name\"\n\"26\",\"czech\"\n\"1\",\"english\"\n" }, "application/json": { "schema": { "description": "Each row is an array of cells aligned to \"columns\".", "required": [ "columns", "rows" ], "properties": { "columns": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "array", "items": { "required": [ "columnName", "value", "isTruncated" ], "properties": { "columnName": { "type": "string" }, "value": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "isTruncated": { "type": "boolean" } }, "type": "object" } } } }, "type": "object" }, "example": { "columns": [ "id", "name" ], "rows": [ [ { "columnName": "id", "value": "26", "isTruncated": false }, { "columnName": "name", "value": "czech", "isTruncated": false } ], [ { "columnName": "id", "value": "1", "isTruncated": false }, { "columnName": "name", "value": "english", "isTruncated": false } ] ] } } } }, "400": { "description": "Invalid request parameters, or BigQuery denied reading a column protected by a policy tag (`storage.backend.policyTagAccessDenied`)." }, "404": { "description": "Table not found (`storage.tables.notFound`)." }, "403": { "description": "Token does not have read access to the bucket." } } } }, "/v2/storage/tables/{tableId}/data-preview": { "get": { "tags": [ "Tables" ], "summary": "Data preview", "description": "Returns up to 1000 rows from a table in CSV (RFC) or JSON format. Rows can be filtered by the same filters as the asynchronous export\n(`changedSince`, `changedUntil`, `columns`, `whereFilters`, `orderBy`, `fulltextSearch`).\nFor a full table download use the asynchronous export.\n\nThe `isTruncated` flag is `true` if the value is >16k chars and the response type is JSON.\n\n#### HTTP Compression\n\nTo enable compression of the API response traffic, include the HTTP header `Accept-encoding: gzip` with the request.", "operationId": "get_/v2/storage/tables/{tableId}/data-preview::TableDataPreviewAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Table string identifier (e.g. in.c-main.my-table).", "required": true, "schema": { "type": "string", "pattern": "[A-Za-z0-9\\.\\-_]+" } }, { "name": "limit", "in": "query", "description": "Limit the number of returned rows. Maximum allowed value is `1000`.", "required": false, "schema": { "description": "Limit the number of returned rows. Maximum allowed value is `1000`.", "type": "integer", "example": 100, "default": 100, "maximum": 1000, "minimum": 0 }, "example": 100 }, { "name": "changedSince", "in": "query", "description": "Filtering by import date - the import timestamp is stored within each row. Accepts a unix timestamp or any date accepted by strtotime.", "required": false, "schema": { "description": "Filtering by import date - the import timestamp is stored within each row. Accepts a unix timestamp or any date accepted by strtotime.", "type": "string", "example": "-2 days", "nullable": true }, "example": "-2 days" }, { "name": "changedUntil", "in": "query", "description": "Filtering by import date - the import timestamp is stored within each row. Accepts a unix timestamp or any date accepted by strtotime.", "required": false, "schema": { "description": "Filtering by import date - the import timestamp is stored within each row. Accepts a unix timestamp or any date accepted by strtotime.", "type": "string", "example": "2013-02-12T15:19:21+00:00", "nullable": true }, "example": "2013-02-12T15:19:21+00:00" }, { "name": "columns", "in": "query", "description": "Comma separated list of columns to export; by default all columns are exported.", "required": false, "schema": { "description": "Comma separated list of columns to export; by default all columns are exported.", "type": "string", "example": "id,name", "nullable": true }, "example": "id,name" }, { "name": "whereColumn", "in": "query", "description": "Deprecated (use `whereFilters` instead). Column for exporting only matching rows.", "required": false, "deprecated": true, "schema": { "description": "Deprecated (use `whereFilters` instead). Column for exporting only matching rows.", "type": "string", "example": "id", "nullable": true, "deprecated": true }, "example": "id" }, { "name": "whereValues[]", "in": "query", "description": "Deprecated (use `whereFilters` instead). Values for exporting only matching rows.", "required": false, "deprecated": true, "schema": { "description": "Deprecated (use `whereFilters` instead). Values for exporting only matching rows.", "type": "array", "items": { "type": "string" }, "example": [ "26" ], "nullable": true, "deprecated": true }, "example": [ "26" ] }, { "name": "whereOperator", "in": "query", "description": "Deprecated (use `whereFilters` instead). Operator for value comparison: `eq` (can be used with multiple values) or `ne`.", "required": false, "deprecated": true, "schema": { "description": "Deprecated (use `whereFilters` instead). Operator for value comparison: `eq` (can be used with multiple values) or `ne`.", "type": "string", "nullable": true, "deprecated": true, "default": "eq", "enum": [ "eq", "ne" ] } }, { "name": "format", "in": "query", "description": "Output format of the preview: `rfc` returns CSV, `json` returns JSON.", "required": false, "schema": { "description": "Output format of the preview: `rfc` returns CSV, `json` returns JSON.", "type": "string", "example": "json", "nullable": true, "default": "rfc", "enum": [ "rfc", "json" ] }, "example": "json" }, { "name": "whereFilters[]", "in": "query", "description": "Row filters (see the asynchronous export for the filter description). Sent as `whereFilters[0][column]=...`.", "required": false, "schema": { "description": "Row filters (see the asynchronous export for the filter description). Sent as `whereFilters[0][column]=...`.", "type": "array", "items": { "$ref": "#/components/schemas/WhereFiltersObject" }, "nullable": true } }, { "name": "orderBy[]", "in": "query", "description": "Sort specification. Sent as `orderBy[0][column]=...`.", "required": false, "schema": { "description": "Sort specification. Sent as `orderBy[0][column]=...`.", "type": "array", "items": { "$ref": "#/components/schemas/OrderByObject" }, "nullable": true } }, { "name": "fulltextSearch", "in": "query", "description": "Fulltext search over all data in the table. Cannot be combined with `whereFilters`. Snowflake/BigQuery only.", "required": false, "schema": { "description": "Fulltext search over all data in the table. Cannot be combined with `whereFilters`. Snowflake/BigQuery only.", "type": "string", "example": "czech", "nullable": true }, "example": "czech" }, { "name": "cache", "in": "query", "description": "A JSON preview requested without any other parameter is served from a cache that is refreshed whenever the table changes. Set to `0` to always read the data from the backend.", "required": false, "schema": { "description": "A JSON preview requested without any other parameter is served from a cache that is refreshed whenever the table changes. Set to `0` to always read the data from the backend.", "type": "boolean", "example": false, "default": true }, "example": false } ], "responses": { "200": { "description": "Table data in the requested format (CSV or JSON).", "content": { "text/csv": { "schema": { "type": "string" }, "example": "\"id\",\"name\"\n\"26\",\"czech\"\n\"1\",\"english\"\n" }, "application/json": { "schema": { "description": "Each row is an array of cells aligned to \"columns\".", "required": [ "columns", "rows" ], "properties": { "columns": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "array", "items": { "required": [ "columnName", "value", "isTruncated" ], "properties": { "columnName": { "type": "string" }, "value": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "isTruncated": { "type": "boolean" } }, "type": "object" } } } }, "type": "object" }, "example": { "columns": [ "id", "name" ], "rows": [ [ { "columnName": "id", "value": "26", "isTruncated": false }, { "columnName": "name", "value": "czech", "isTruncated": false } ], [ { "columnName": "id", "value": "1", "isTruncated": false }, { "columnName": "name", "value": "english", "isTruncated": false } ] ] } } } }, "400": { "description": "Invalid request parameters, or BigQuery denied reading a column protected by a policy tag (`storage.backend.policyTagAccessDenied`)." }, "404": { "description": "Table not found (`storage.tables.notFound`)." }, "403": { "description": "Token does not have read access to the bucket." } } } }, "/v2/storage/branch/{branchId}/tables/{tableId}/definition": { "put": { "tags": [ "Tables" ], "summary": "Update Table Definition", "description": "Updates table display name, table description, and multiple column definition patches for a table with typed columns. *Snowflake, BigQuery only.*\n\nRequest is handled asynchronously. The request is added to a queue and the job resource URL for status polling is returned.\n\nSupported column alterations are the same as for [Update Column Definition](#operation/put_/v2/storage/tables/{id}/columns/{column}/definition), except this endpoint does not support changing a column data type.\n\nBackend 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": "The table Id.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.orders" }, { "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": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TableDefinitionUpdateRequest" } ] } } } }, "responses": { "404": { "description": "Either bucket (`storage.buckets.notFound`), table (`storage.tables.notFound`) 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 display name, table description, and multiple column definition patches for a table with typed columns. *Snowflake, BigQuery only.*\n\nRequest is handled asynchronously. The request is added to a queue and the job resource URL for status polling is returned.\n\nSupported column alterations are the same as for [Update Column Definition](#operation/put_/v2/storage/tables/{id}/columns/{column}/definition), except this endpoint does not support changing a column data type.\n\nBackend 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": "The table Id.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.orders" }, { "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/TableDefinitionUpdateRequest" } ] } } } }, "responses": { "404": { "description": "Either bucket (`storage.buckets.notFound`), table (`storage.tables.notFound`) 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": "Table detail", "description": "Obtains information about a table.\n\n- `definition` property is available only for tables with [native datatypes](https://help.keboola.com/storage/tables/data-types/#native-datatypes).\n- Data types in the definition are never alias/synonymous/virtual, they are always base types. E.g. INT = NUMERIC(38,0) for Snowflake.", "operationId": "get_/v2/storage/branch/{branchId}/tables/{id}::TableDetailAction", "parameters": [ { "name": "id", "in": "path", "description": "Table string id (e.g. `in.c-main.orders`).", "required": true, "schema": { "type": "string", "pattern": "[A-Za-z0-9\\.\\-_]+" }, "example": "in.c-application-testing.cashier-data-alias" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Table detail response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableDetailResponse" }, "example": { "uri": "https://connection.keboola.com/v2/storage/tables/in.c-application-testing.cashier-data-alias", "id": "in.c-application-testing.cashier-data-alias", "name": "cashier-data-alias", "displayName": "cashier-data-alias-displayName", "transactional": false, "primaryKey": [], "indexType": null, "indexKey": [], "distributionType": null, "distributionKey": [], "syntheticPrimaryKeyEnabled": false, "created": "2019-08-14T16:54:06+0200", "lastImportDate": "2015-11-03T10:58:31+0100", "lastChangeDate": "2015-11-03T10:58:32+0100", "rowsCount": 199, "dataSizeBytes": 25165824, "isAlias": true, "isAliasable": true, "isTyped": false, "isDescriptionSystemManaged": false, "timestampType": "MANAGED", "tableType": "table", "path": "kbc_578.c-application-testing.cashier-data-alias", "sourceTable": { "id": "in.c-application-testing.cashier-data", "uri": "https://connection.keboola.com/v2/storage/tables/in.c-application-testing.cashier-data", "project": { "id": 123, "name": "Some source project" }, "isAlias": false, "metadata": [], "columnMetadata": { "number_of_items": [ { "id": "207947778", "key": "KBC.datatype.basetype", "value": "INTEGER", "provider": "user", "timestamp": "2019-08-14T16:55:34+0200" } ] }, "definition": { "primaryKeysNames": [], "columns": [ { "name": "visit_id", "definition": { "type": "VARCHAR", "nullable": false, "length": "16777216" }, "basetype": "STRING", "canBeFiltered": true } ] } }, "aliasColumnsAutoSync": true, "isPersisted": false, "columns": [ "time_spent_in_shop", "number_of_items", "customer_shoe_size", "customer_age", "age_segment", "no_segment", "customer_segment", "visit_id" ], "columnMetadata": [], "attributes": [], "metadata": [], "bucket": { "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-application-testing", "id": "in.c-application-testing", "name": "c-application-testing", "displayName": "application-testing", "stage": "in", "description": "", "tables": "https://connection.keboola.com/v2/storage/buckets/in.c-application-testing", "created": "2015-11-03T10:54:55+0100", "lastChangeDate": "2019-08-14T16:54:06+0200", "isReadOnly": false, "dataSizeBytes": 129427968, "rowsCount": 237902, "isMaintenance": false, "backend": "snowflake", "sharing": null, "bucketSharingAllowed": true, "sharedByActor": null, "metadata": [], "backendPath": [ "KBC_PRJ_123", "in.c-main" ] }, "definition": { "primaryKeysNames": [], "columns": [ { "name": "visit_id", "definition": { "type": "VARCHAR", "nullable": false, "length": "16777216" }, "basetype": "STRING", "canBeFiltered": true } ] } } } } }, "404": { "description": "Returned when the table or bucket is not found (`storage.tables.notFound`)." }, "403": { "description": "Access denied to the table." } } }, "delete": { "tags": [ "Tables" ], "summary": "Drop table", "description": "Deletes a table from Storage. In default mode, only a table without any aliases can be deleted.\nUse the optional `force` parameter to delete its aliases too.\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 [TableDeleteJobResult](#model-TableDeleteJobResult).\n\n Parameters of job will be [DeleteTableJobParams](#components-schemas-DeleteTableJobParams).\n\n[Deprecated] This endpoint can be used synchronously as well.", "operationId": "delete_/v2/storage/branch/{branchId}/tables/{id}::TableDeleteAction", "parameters": [ { "name": "id", "in": "path", "description": "Table string id (e.g. `in.c-main.orders`).", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main.orders" }, { "name": "force", "in": "query", "description": "Drops the table and its aliases.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "async", "in": "query", "description": "Execute drop table in an asynchronous job. The synchronous operation is deprecated.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The table was dropped (synchronous, deprecated)." }, "400": { "description": "Synchronous drop only: the table has aliases (`tables.cannotDeletedTableWithAliases`), a dependent view exists, or the backend connection could not be established." }, "403": { "description": "Access to the table was denied." }, "404": { "description": "The table or its bucket was not found (`storage.tables.notFound`)." }, "409": { "description": "Another operation holds a dependent alias' lock (`core.lock.lockIsAlreadyUsed`); retry." }, "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/TableDeleteJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/TableDeleteJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTableJobParams" } } } } }, "/v2/storage/tables/{id}": { "get": { "tags": [ "Tables" ], "summary": "Table detail", "description": "Obtains information about a table.\n\n- `definition` property is available only for tables with [native datatypes](https://help.keboola.com/storage/tables/data-types/#native-datatypes).\n- Data types in the definition are never alias/synonymous/virtual, they are always base types. E.g. INT = NUMERIC(38,0) for Snowflake.", "operationId": "get_/v2/storage/tables/{id}::TableDetailAction", "parameters": [ { "name": "id", "in": "path", "description": "Table string id (e.g. `in.c-main.orders`).", "required": true, "schema": { "type": "string", "pattern": "[A-Za-z0-9\\.\\-_]+" }, "example": "in.c-application-testing.cashier-data-alias" } ], "responses": { "200": { "description": "Table detail response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableDetailResponse" }, "example": { "uri": "https://connection.keboola.com/v2/storage/tables/in.c-application-testing.cashier-data-alias", "id": "in.c-application-testing.cashier-data-alias", "name": "cashier-data-alias", "displayName": "cashier-data-alias-displayName", "transactional": false, "primaryKey": [], "indexType": null, "indexKey": [], "distributionType": null, "distributionKey": [], "syntheticPrimaryKeyEnabled": false, "created": "2019-08-14T16:54:06+0200", "lastImportDate": "2015-11-03T10:58:31+0100", "lastChangeDate": "2015-11-03T10:58:32+0100", "rowsCount": 199, "dataSizeBytes": 25165824, "isAlias": true, "isAliasable": true, "isTyped": false, "isDescriptionSystemManaged": false, "timestampType": "MANAGED", "tableType": "table", "path": "kbc_578.c-application-testing.cashier-data-alias", "sourceTable": { "id": "in.c-application-testing.cashier-data", "uri": "https://connection.keboola.com/v2/storage/tables/in.c-application-testing.cashier-data", "project": { "id": 123, "name": "Some source project" }, "isAlias": false, "metadata": [], "columnMetadata": { "number_of_items": [ { "id": "207947778", "key": "KBC.datatype.basetype", "value": "INTEGER", "provider": "user", "timestamp": "2019-08-14T16:55:34+0200" } ] }, "definition": { "primaryKeysNames": [], "columns": [ { "name": "visit_id", "definition": { "type": "VARCHAR", "nullable": false, "length": "16777216" }, "basetype": "STRING", "canBeFiltered": true } ] } }, "aliasColumnsAutoSync": true, "isPersisted": false, "columns": [ "time_spent_in_shop", "number_of_items", "customer_shoe_size", "customer_age", "age_segment", "no_segment", "customer_segment", "visit_id" ], "columnMetadata": [], "attributes": [], "metadata": [], "bucket": { "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-application-testing", "id": "in.c-application-testing", "name": "c-application-testing", "displayName": "application-testing", "stage": "in", "description": "", "tables": "https://connection.keboola.com/v2/storage/buckets/in.c-application-testing", "created": "2015-11-03T10:54:55+0100", "lastChangeDate": "2019-08-14T16:54:06+0200", "isReadOnly": false, "dataSizeBytes": 129427968, "rowsCount": 237902, "isMaintenance": false, "backend": "snowflake", "sharing": null, "bucketSharingAllowed": true, "sharedByActor": null, "metadata": [], "backendPath": [ "KBC_PRJ_123", "in.c-main" ] }, "definition": { "primaryKeysNames": [], "columns": [ { "name": "visit_id", "definition": { "type": "VARCHAR", "nullable": false, "length": "16777216" }, "basetype": "STRING", "canBeFiltered": true } ] } } } } }, "404": { "description": "Returned when the table or bucket is not found (`storage.tables.notFound`)." }, "403": { "description": "Access denied to the table." } } }, "delete": { "tags": [ "Tables" ], "summary": "Drop table", "description": "Deletes a table from Storage. In default mode, only a table without any aliases can be deleted.\nUse the optional `force` parameter to delete its aliases too.\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 [TableDeleteJobResult](#model-TableDeleteJobResult).\n\n Parameters of job will be [DeleteTableJobParams](#components-schemas-DeleteTableJobParams).\n\n[Deprecated] This endpoint can be used synchronously as well.", "operationId": "delete_/v2/storage/tables/{id}::TableDeleteAction", "parameters": [ { "name": "id", "in": "path", "description": "Table string id (e.g. `in.c-main.orders`).", "required": true, "schema": { "type": "string", "pattern": "[^/]+" }, "example": "in.c-main.orders" }, { "name": "force", "in": "query", "description": "Drops the table and its aliases.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "async", "in": "query", "description": "Execute drop table in an asynchronous job. The synchronous operation is deprecated.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true } ], "responses": { "204": { "description": "The table was dropped (synchronous, deprecated)." }, "400": { "description": "Synchronous drop only: the table has aliases (`tables.cannotDeletedTableWithAliases`), a dependent view exists, or the backend connection could not be established." }, "403": { "description": "Access to the table was denied." }, "404": { "description": "The table or its bucket was not found (`storage.tables.notFound`)." }, "409": { "description": "Another operation holds a dependent alias' lock (`core.lock.lockIsAlreadyUsed`); retry." }, "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/TableDeleteJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/TableDeleteJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTableJobParams" } } } } }, "/v2/storage/branch/{branchId}/tables/{id}/metadata/{metadataId}": { "delete": { "tags": [ "Metadata" ], "summary": "Delete table metadata", "description": "Deletes the specified metadata item from the table.", "operationId": "delete_/v2/storage/branch/{branchId}/tables/{id}/metadata/{metadataId}::TableDeleteMetadataAction", "parameters": [ { "name": "id", "in": "path", "description": "Id of the table.", "required": true, "schema": { "type": "string", "pattern": "[A-Za-z0-9\\.\\-_]+" }, "example": "in.c-main.customers" }, { "name": "metadataId", "in": "path", "description": "Id of the metadata.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 19509 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Metadata item deleted." }, "400": { "description": "Returned when the metadata item cannot be deleted (`KBC.invalid`)." }, "403": { "description": "Returned when the token has no write access to the bucket or the provider is protected (`storage.metadata.invalidProvider`)." }, "404": { "description": "Returned when the table (`storage.tables.notFound`) or the metadata item (`storage.metadata.notFound`) is not found." } } } }, "/v2/storage/tables/{id}/metadata/{metadataId}": { "delete": { "tags": [ "Metadata" ], "summary": "Delete table metadata", "description": "Deletes the specified metadata item from the table.", "operationId": "delete_/v2/storage/tables/{id}/metadata/{metadataId}::TableDeleteMetadataAction", "parameters": [ { "name": "id", "in": "path", "description": "Id of the table.", "required": true, "schema": { "type": "string", "pattern": "[A-Za-z0-9\\.\\-_]+" }, "example": "in.c-main.customers" }, { "name": "metadataId", "in": "path", "description": "Id of the metadata.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 19509 } ], "responses": { "204": { "description": "Metadata item deleted." }, "400": { "description": "Returned when the metadata item cannot be deleted (`KBC.invalid`)." }, "403": { "description": "Returned when the token has no write access to the bucket or the provider is protected (`storage.metadata.invalidProvider`)." }, "404": { "description": "Returned when the table (`storage.tables.notFound`) or the metadata item (`storage.metadata.notFound`) is not found." } } } }, "/v2/storage/branch/{branchId}/tables/{tableId}/events": { "get": { "tags": [ "Tables" ], "summary": "List events for a table", "description": "Returns a list of events for the specified table.", "operationId": "get_/v2/storage/branch/{branchId}/tables/{tableId}/events::TableEventsListAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Identifier of the table to list events for.", "required": true, "schema": { "type": "string", "pattern": "[A-Za-z0-9\\.\\-_]+" } }, { "name": "limit", "in": "query", "description": "Maximum number of events to return", "required": false, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of events to skip", "required": false, "schema": { "type": "integer" } }, { "name": "maxId", "in": "query", "description": "Only include events with ID less than or equal to this value", "required": false, "schema": { "type": "string" } }, { "name": "sinceId", "in": "query", "description": "Only include events with ID greater than this value", "required": false, "schema": { "type": "string" } }, { "name": "component", "in": "query", "description": "Filter events by component", "required": false, "schema": { "type": "string" } }, { "name": "configurationId", "in": "query", "description": "Filter events by configuration ID", "required": false, "schema": { "type": "string" } }, { "name": "runId", "in": "query", "description": "Filter events by run ID", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Full-text search query to filter event data", "required": false, "schema": { "type": "string" } }, { "name": "query", "in": "query", "description": "Deprecated alias of the q parameter.", "required": false, "deprecated": true, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Sort order of events. Use \"asc\" for oldest first or \"desc\" for newest first.", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Table events list response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableEventsListResponse" } } } }, "400": { "description": "Returned when the provided events filter parameters are invalid." }, "403": { "description": "Access denied to the table." }, "404": { "description": "Returned when the table or bucket is not found." }, "503": { "description": "Bucket or its backend connection is under maintenance." } } } }, "/v2/storage/tables/{tableId}/events": { "get": { "tags": [ "Tables" ], "summary": "List events for a table", "description": "Returns a list of events for the specified table.", "operationId": "get_/v2/storage/tables/{tableId}/events::TableEventsListAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Identifier of the table to list events for.", "required": true, "schema": { "type": "string", "pattern": "[A-Za-z0-9\\.\\-_]+" } }, { "name": "limit", "in": "query", "description": "Maximum number of events to return", "required": false, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "Number of events to skip", "required": false, "schema": { "type": "integer" } }, { "name": "maxId", "in": "query", "description": "Only include events with ID less than or equal to this value", "required": false, "schema": { "type": "string" } }, { "name": "sinceId", "in": "query", "description": "Only include events with ID greater than this value", "required": false, "schema": { "type": "string" } }, { "name": "component", "in": "query", "description": "Filter events by component", "required": false, "schema": { "type": "string" } }, { "name": "configurationId", "in": "query", "description": "Filter events by configuration ID", "required": false, "schema": { "type": "string" } }, { "name": "runId", "in": "query", "description": "Filter events by run ID", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Full-text search query to filter event data", "required": false, "schema": { "type": "string" } }, { "name": "query", "in": "query", "description": "Deprecated alias of the q parameter.", "required": false, "deprecated": true, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Sort order of events. Use \"asc\" for oldest first or \"desc\" for newest first.", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Table events list response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableEventsListResponse" } } } }, "400": { "description": "Returned when the provided events filter parameters are invalid." }, "403": { "description": "Access denied to the table." }, "404": { "description": "Returned when the table or bucket is not found." }, "503": { "description": "Bucket or its backend connection is under maintenance." } } } }, "/v2/storage/branch/{branchId}/table-list": { "get": { "tags": [ "Tables" ], "summary": "List tables (cursor-paginated)", "description": "Lists the tables of the branch the token can read, one page at a time. `default` as the branch ID lists\nproduction. A development branch is listed over production: its own tables, and each production table\nthe branch has no table of the same ID for in a bucket the token can read. `branchId` of an item is the\nbranch the table belongs to: an inherited table carries the ID of the default branch, and its detail is\nread through that branch.\n\nReturns a cursor-paginated collection: `data` holds the tables on the page, `meta` the `total` matching the\nfilters regardless of pagination, the applied `limit` and the structure of the `cursor`, and `links`\nabsolute URLs of this endpoint (`self`, `first`, `next`) that keep every active filter. `next` is `null`\non the last page.\n\nAn item is deliberately lighter than the table detail: it carries the fields needed to list and pick\ntables. `include` adds detail fields on request; fetch the table detail (`GET /v2/storage/tables/{tableId}`)\nfor column metadata and everything else.\n\n#### Include\n\n*include* - comma-separated, each value at most once; a field not requested is missing from the item:\n\n* *columns* - `columns`, the column names in the order of the table detail.\n* *metadata* - `metadata`, the table-level metadata as `GET /v2/storage/tables/{tableId}/metadata` returns\n it; on an alias that syncs its columns also `sourceTable.metadata`, the table-level metadata of its root\n source table (in another project too), and `null` there for an alias that does not sync its columns.\n* *definition* - `definition`, the table definition equal to the `definition` of the table detail, built\n from the native column and table fields only. An alias that syncs its columns (a linked-bucket table too)\n takes its column types from its root source table and resolves descriptions along its chain, as the\n detail does. `null` for a typed table whose column types are not all on the native fields yet, and for\n an alias of such a table; the detail reads the legacy metadata for them. The table `description` comes\n from the native field only: the detail falls back to the legacy `KBC.description` table metadata when\n the native field is empty, the list does not.\n\n#### Filtering\n\nFilters use the JSON:API `filter` family and combine with AND:\n\n* *filter[bucketId]* - ID of one bucket, e.g. `in.c-main`. In a development branch it lists the branch's\n tables of that bucket and the ones it inherits from production. A bucket outside the list or one the\n token cannot read answers 404.\n* *filter[ids]* - comma-separated table IDs, at most `page[limit]` of them.\n* *filter[name]* - words separated by whitespace; a table matches when every word is contained in its ID\n (`in.c-main.orders`), its display name or its bucket's display name, ignoring case and accents, in any\n order. `%` and `_` match themselves. A blank value is no filter; the length and the number of words are\n limited by the server. It narrows the listing and keeps its order, cursor and `meta.total`; it does not\n rank, match fuzzily or search columns or metadata.\n* *filter[lastUpdatedBy]* - comma-separated `componentId:configurationId` pairs, e.g.\n `keboola.ex-db-snowflake:123,keboola.snowflake-transformation:456`; unlike `filter[name]`, a blank value is\n rejected. The length of each ID, the number of pairs and the number of distinct components among them\n are limited by the server. A table matches when its own `lastUpdatedBy` has the component ID and the configuration ID of one\n of the pairs, whatever its configuration row and branch. An alias that syncs its columns (a linked-bucket\n table too) never matches: it shows its root table's `lastUpdatedBy`, and the configuration wrote that\n root, which matches in its own project. An alias that does not sync its columns matches on its own values.\n* *filter[sourceTableId]* - ID of a table of the project, e.g. `in.c-main.users`: only the aliases whose direct\n source it is (an alias of an alias names its own source). In a development branch the branch's table of\n that ID and the production one (only the branch's own when `filter[inheritProduction]` is false). An ID of\n no table of the project lists nothing; a value that is no table ID is rejected.\n* *filter[changedSince]* - a unix timestamp or anything `strtotime()` reads, the rule the `changedSince` of\n the table export validates with: e.g. `2026-10-28T10:15:00+01:00`, `1761642900` or `-1 day`. Unlike the\n export, `0` is the epoch and a date before 1970 written as a string is accepted. A value without an\n offset is read in the server's zone (currently Europe/Prague). Times after the year 9999 are\n rejected. A relative value resolves on each request:\n `links.next` carries the resolved time (ISO 8601 with offset), so every page reached through it shares\n one cutoff, while `links.self` and `links.first` keep the value sent; a client that builds `page[after]`\n itself sends that resolved time on later pages. It keeps only the tables whose own\n record changed at or after it (an import, a rename, the description, the primary key, an added or deleted\n column, the statistics). Send the previous poll's time minus a small overlap and deduplicate by `id`.\n Deleted tables are not returned: compare `meta.total` of the unfiltered listing with the tables you hold.\n Changes kept only outside the table record (metadata, a column's type or description) do not count.\n* *filter[inheritProduction]* - `true` (default) or `false`. `false` lists only the development branch's own\n tables; the default branch ignores it.\n\n#### Pagination\n\nTables are ordered `bucket.stage ASC, bucket.name ASC, name ASC`, the order of their IDs.\n\n* *page[limit]* - number of returned tables; the default and the maximum are configured on the server.\n A larger value is rejected, never clamped.\n* *page[after]* - cursor of the last table already read; omit it for the first page. It is the base64url\n (padding optional) of the JSON object `{\"bucket.stage\": , \"bucket.name\": , \"name\": }`\n holding that table's `bucket.stage`, `bucket.name` and `name` as the list prints them, e.g.\n `{\"bucket.stage\":\"in\",\"bucket.name\":\"c-main\",\"name\":\"users\"}` \u2192 `eyJidWNrZXQuc3RhZ2UiOiJpbiIsImJ1Y2tldC5uYW1lIjoiYy1tYWluIiwibmFtZSI6InVzZXJzIn0`.\n `links.next` already carries the cursor of the page's last table; `meta.cursor` repeats this structure.\n\nAn undecodable cursor, bare `limit` / `offset`, `page[offset]`, an unknown `page[...]` or `filter[...]`\nmember, an unknown or repeated `include` value and any other query parameter are rejected with a\nvalidation error.", "operationId": "get_/v2/storage/branch/{branchId}/table-list::TableListV2Action", "parameters": [ { "name": "branchId", "in": "path", "description": "ID of the branch, or `default` for production.", "required": true, "schema": { "type": "string" }, "example": "default" }, { "name": "page", "in": "query", "description": "Pagination: `page[limit]` (default and maximum are configured on the server) and `page[after]`, the cursor of the last row read \u2014 base64url(json) of `{\"bucket.stage\": string, \"bucket.name\": string, \"name\": string}`, rows ordered `bucket.stage ASC, bucket.name ASC, name ASC`. Omit `page[after]` for the first page; `links.next` carries the next one.", "required": false, "style": "deepObject", "explode": true, "schema": { "properties": { "after": { "description": "base64url(json) of `{\"bucket.stage\": string, \"bucket.name\": string, \"name\": string}`.", "type": "string" }, "limit": { "type": "integer", "minimum": 1 } }, "type": "object" } }, { "name": "include", "in": "query", "description": "Comma-separated item fields to add: `columns`, `metadata`, `definition`.", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "columns", "metadata", "definition" ] } } }, { "name": "filter", "in": "query", "description": "Filters, JSON:API style: `filter[]=`. Filters combine with AND.", "required": false, "style": "deepObject", "explode": true, "schema": { "properties": { "bucketId": { "description": "ID of one bucket, e.g. `in.c-main`.", "type": "string" }, "ids": { "description": "Comma-separated table IDs, at most `page[limit]` of them.", "type": "string" }, "sourceTableId": { "description": "ID of a table of the project: only its direct aliases.", "type": "string", "example": "in.c-main.users" }, "changedSince": { "description": "Only the tables whose record changed at or after this time: a unix timestamp or anything strtotime() reads, e.g. `-1 day`; `links.next` carries the resolved absolute time. Deleted tables are not returned.", "type": "string", "example": "2026-10-28T10:15:00+01:00" }, "name": { "description": "Words that must all be contained in the table ID, the table display name or the bucket display name, ignoring case and accents.", "type": "string", "example": "main daily" }, "lastUpdatedBy": { "description": "Comma-separated `componentId:configurationId` pairs; a blank value is rejected. A table matches one of them with its own `lastUpdatedBy`. An alias that syncs its columns never matches.", "type": "string", "example": "keboola.ex-db-snowflake:123" }, "inheritProduction": { "description": "List a development branch over production; `false` lists only its own tables. Ignored in the default branch.", "type": "boolean", "default": true } }, "type": "object" } } ], "responses": { "200": { "description": "Tables on the requested page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableListV2Response" }, "example": { "data": [ { "id": "in.c-main.users", "bucketId": "in.c-main", "name": "users", "displayName": "users", "branchId": 1234, "bucket": { "id": "in.c-main", "name": "c-main", "displayName": "main", "stage": "in", "backend": "snowflake", "idBranch": 1234 }, "primaryKey": [ "id" ], "isAlias": false, "isAliasable": true, "isTyped": true, "tableType": "table", "rowsCount": 1000, "dataSizeBytes": 65536, "created": "2026-10-22T10:00:00+0200", "lastImportDate": "2026-10-22T10:05:00+0200", "lastChangeDate": "2026-10-22T10:05:00+0200", "description": "Registered users", "isDescriptionSystemManaged": false } ], "meta": { "total": 41, "limit": 1, "cursor": { "param": "page[after]", "encoding": "base64url(json)", "fields": [ { "name": "bucket.stage", "type": "string", "nullable": false }, { "name": "bucket.name", "type": "string", "nullable": false }, { "name": "name", "type": "string", "nullable": false } ], "order": "bucket.stage ASC, bucket.name ASC, name ASC" } }, "links": { "self": "https://connection.keboola.com/v2/storage/branch/default/table-list?page[limit]=1&page[after]=eyJidWNrZXQuc3RhZ2UiOiJpbiIsImJ1Y2tldC5uYW1lIjoiYy1tYWluIiwibmFtZSI6Im9yZGVycyJ9", "first": "https://connection.keboola.com/v2/storage/branch/default/table-list?page[limit]=1", "next": "https://connection.keboola.com/v2/storage/branch/default/table-list?page[limit]=1&page[after]=eyJidWNrZXQuc3RhZ2UiOiJpbiIsImJ1Y2tldC5uYW1lIjoiYy1tYWluIiwibmFtZSI6InVzZXJzIn0" } } } } }, "400": { "description": "A `page[...]` or `filter[...]` parameter is invalid: `page[limit]` out of range, more table IDs than `page[limit]`, a `filter[name]` over its length or word limit, a `filter[lastUpdatedBy]` that is blank, is not a list of `componentId:configurationId` pairs, is not valid UTF-8, holds an ID over its length limit or more pairs or distinct components than the server allows, a `filter[changedSince]` that is blank, that strtotime() cannot read or that is after the year 9999, an undecodable cursor, an unknown member or parameter, or a bare `limit`, `offset`, `bucketId`, `ids` or `page[offset]`." }, "404": { "description": "The branch does not exist in the project, or `filter[bucketId]` is not a bucket of the list the token can read." } } } }, "/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 \u2014 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.", "required": true, "schema": { "type": "string", "pattern": ".+" }, "example": "in.c-main.orders" }, { "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" } } } } }, "/v2/storage/branch/{branchId}/tables/{tableId}": { "put": { "tags": [ "Tables" ], "summary": "Update a table", "description": "Renames a table by setting a new display name. With `async=true` the rename is enqueued as a storage job (202). The synchronous variant is deprecated and returns the updated table directly. Linked copies of the table in other projects are renamed as well.\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 [TableUpdateJobResult](#model-TableUpdateJobResult).\n\n Parameters of job will be [TableUpdateJobParams](#components-schemas-TableUpdateJobParams).\n\n[Deprecated] This endpoint can be used synchronously as well. In that case, the final result is returned directly in the response [TableUpdateResponse](#model-TableUpdateResponse).", "operationId": "put_/v2/storage/branch/{branchId}/tables/{tableId}::TableUpdateAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Table string id (e.g. `in.c-main.orders`).", "required": true, "schema": { "type": "string", "pattern": "[A-Za-z0-9\\.\\-_]+" } }, { "name": "async", "in": "query", "description": "When true, the update is performed asynchronously as a job.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TableUpdateRequest" } ] } } } }, "responses": { "200": { "description": "The updated table (synchronous, deprecated).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableUpdateResponse" } } } }, "400": { "description": "The display name failed validation (`storage.tables.validation`) or another table in the same bucket already uses it (`storage.buckets.tableAlreadyExists`)." }, "403": { "description": "Write access to the table was denied." }, "404": { "description": "The table or its bucket was not found." }, "503": { "description": "The bucket or its 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/TableUpdateJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/TableUpdateJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/TableUpdateJobParams" } } } } }, "/v2/storage/tables/{tableId}": { "put": { "tags": [ "Tables" ], "summary": "Update a table", "description": "Renames a table by setting a new display name. With `async=true` the rename is enqueued as a storage job (202). The synchronous variant is deprecated and returns the updated table directly. Linked copies of the table in other projects are renamed as well.\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 [TableUpdateJobResult](#model-TableUpdateJobResult).\n\n Parameters of job will be [TableUpdateJobParams](#components-schemas-TableUpdateJobParams).\n\n[Deprecated] This endpoint can be used synchronously as well. In that case, the final result is returned directly in the response [TableUpdateResponse](#model-TableUpdateResponse).", "operationId": "put_/v2/storage/tables/{tableId}::TableUpdateAction", "parameters": [ { "name": "tableId", "in": "path", "description": "Table string id (e.g. `in.c-main.orders`).", "required": true, "schema": { "type": "string", "pattern": "[A-Za-z0-9\\.\\-_]+" } }, { "name": "async", "in": "query", "description": "When true, the update is performed asynchronously as a job.", "required": false, "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TableUpdateRequest" } ] } } } }, "responses": { "200": { "description": "The updated table (synchronous, deprecated).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableUpdateResponse" } } } }, "400": { "description": "The display name failed validation (`storage.tables.validation`) or another table in the same bucket already uses it (`storage.buckets.tableAlreadyExists`)." }, "403": { "description": "Write access to the table was denied." }, "404": { "description": "The table or its bucket was not found." }, "503": { "description": "The bucket or its 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/TableUpdateJobResult" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/TableUpdateJobResult" } } }, "x-storage-job-params": { "application/json": { "schema": { "$ref": "#/components/schemas/TableUpdateJobParams" } } } } }, "/v2/storage/tickets": { "post": { "tags": [ "Tickets" ], "summary": "Generate New Id", "description": "Tickets are unique sequential 64 bit IDs. Tickets are used to generate unique run identifiers for all components using Keboola Connection.", "operationId": "post_/v2/storage/tickets::GenerateNewId", "responses": { "200": { "description": "New ticket ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateNewIdResponse" }, "example": { "id": "123454352345" } } } } }, "deprecated": true } }, "/v2/storage/tickets/": { "post": { "tags": [ "Tickets" ], "summary": "Generate New Id", "description": "Tickets are unique sequential 64 bit IDs. Tickets are used to generate unique run identifiers for all components using Keboola Connection.", "operationId": "post_/v2/storage/tickets/::GenerateNewId", "responses": { "200": { "description": "New ticket ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateNewIdResponse" }, "example": { "id": "123454352345" } } } } }, "deprecated": true } }, "/v2/storage/tokens": { "get": { "tags": [ "Tokens and Permissions" ], "summary": "List all tokens", "description": "Lists all tokens in the project. A token without the `canManageTokens` permission only sees itself.", "operationId": "get_/v2/storage/tokens::TokensListAction", "responses": { "200": { "description": "Tokens list response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokensListResponse" }, "example": [ { "id": "38", "created": "2012-11-13T16:49:28+0100", "refreshed": "2017-11-13T16:48:28+0100", "description": "", "uri": "https://connection.keboola.com/v2/storage/tokens/38", "isMasterToken": true, "canManageBuckets": true, "canManageTokens": true, "canReadAllFileUploads": true, "canPurgeTrash": true, "canManageProtectedDefaultBranch": false, "canCreateJobs": false, "canReadAllProjectEvents": true, "canManageDevBranches": true, "expires": null, "isExpired": false, "isDisabled": false, "dailyCapacity": 5, "bucketPermissions": { "in.c-main": "manage", "out.c-main": "manage" }, "admin": { "name": "John Doe", "id": 124, "role": "admin" } }, { "id": "40", "created": "2012-11-13T16:49:28+0100", "refreshed": "2017-11-13T16:48:28+0100", "description": "my-token", "uri": "https://connection.keboola.com/v2/storage/tokens/40", "isMasterToken": false, "canManageBuckets": false, "canManageTokens": false, "canReadAllFileUploads": false, "canPurgeTrash": false, "canManageProtectedDefaultBranch": false, "canCreateJobs": false, "canReadAllProjectEvents": false, "canManageDevBranches": false, "expires": null, "isExpired": false, "isDisabled": false, "dailyCapacity": 5, "creatorToken": { "id": 1, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "1", "name": "dev@keboola.com", "adminId": null }, "componentAccess": [ "someComponentName" ], "bucketPermissions": { "in.c-main": "read" } } ] } } } } }, "post": { "tags": [ "Tokens and Permissions" ], "summary": "Create token", "description": "Creates a new token in the project. Note that it is not possible to create a new master token.\n\nIf your admin token does not have the `canManageTokens` permission, you can only create a temporary token with minimal privileges.\nIn this case, you are allowed to set the `description` and token expiration via the `expiresIn` parameter. All other attributes will be ignored.\n\nCreating a token with `canManageProtectedDefaultBranch` additionally requires an application token\nwith scope `storage:tokens:create-protected-default-branch-privileged` in the `X-KBC-ManageApiToken` header.", "operationId": "post_/v2/storage/tokens::TokenCreateAction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TokenCreateRequest" }, { "$ref": "#/components/schemas/TokenCreateLimitedRequest" } ] } } } }, "responses": { "200": { "description": "Created token including its decrypted `token` value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCreateResponse" }, "example": { "id": "484", "created": "2017-11-13T16:48:28+0100", "refreshed": "2017-11-13T16:48:28+0100", "description": "my-new-token", "uri": "https://connection.keboola.com/v2/storage/tokens/484", "isMasterToken": false, "canManageBuckets": false, "canManageTokens": false, "canReadAllFileUploads": false, "canPurgeTrash": false, "canManageProtectedDefaultBranch": false, "canCreateJobs": false, "canReadAllProjectEvents": false, "canManageDevBranches": false, "expires": "2017-11-13T16:49:28+0100", "isExpired": false, "isDisabled": false, "dailyCapacity": 5, "token": "75-12d4bfa4995694a1c956e7bb1eea0df5cc53acdb", "creatorToken": { "id": 1, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "1", "name": "dev@keboola.com", "adminId": null }, "componentAccess": [ "keboola.ex-db-mysql" ], "bucketPermissions": { "in.c-main": "read" } } } } }, "400": { "description": "Invalid request body (`storage.tokens.validation`), invalid `expiresIn` (`storage.tokens.expiresValidation`) or a missing parameter of a limited token (`storage.tokens.missingParam`)." }, "403": { "description": "The authorizing token may not create tokens with the requested privileges (`accessDenied`), or a credential issued by agent provisioning asked for a token without `expiresIn` of 3600 seconds or less (`storage.tokens.agentCredentialNotAllowed`)." }, "404": { "description": "Requested bucket or component permissions are invalid, e.g. the bucket does not exist (`storage.tokens.invalidPermissions`)." } } } }, "/v2/storage/tokens/{id}": { "get": { "tags": [ "Tokens and Permissions" ], "summary": "Token detail", "description": "Returns all properties of a token, including the project it belongs to (`owner`). You can obtain the token ID, for example, using the Token verification call.\n\nRequesting the token used for authorization is always allowed; requesting any other token requires the `canManageTokens` permission.\n\nAvailable both with and without a development branch prefix; the returned token properties and permission rules are the same in either case.", "operationId": "get_/v2/storage/tokens/{id}::TokenDetailAction", "parameters": [ { "name": "id", "in": "path", "description": "Token ID.", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 44 } ], "responses": { "200": { "description": "Token detail response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenVerifyResponse" }, "example": { "id": "44", "created": "2017-02-13T10:27:50+0100", "refreshed": "2017-11-13T16:48:28+0100", "description": "", "uri": "https://connection.keboola.com/v2/storage/tokens/44", "isMasterToken": true, "canManageBuckets": true, "canManageTokens": true, "canReadAllFileUploads": true, "canPurgeTrash": true, "canManageProtectedDefaultBranch": false, "canCreateJobs": false, "canReadAllProjectEvents": true, "canManageDevBranches": true, "expires": null, "isExpired": false, "isDisabled": false, "dailyCapacity": 0, "actor": null, "bucketPermissions": { "in.c-test": "manage" }, "owner": { "id": 58, "name": "Buckets 5", "type": "production", "region": "us-east-1", "created": "2022-08-18T08:47:07+0200", "expires": null, "features": [], "dataSizeBytes": 112128, "rowsCount": 1036, "hasMysql": false, "hasSynapse": false, "hasSnowflake": true, "hasExasol": false, "hasTeradata": false, "hasBigquery": false, "defaultBackend": "snowflake", "hasTryModeOn": "0", "limits": { "storage.dataSizeBytes": { "name": "storage.dataSizeBytes", "value": 50000000000 }, "storage.jobsParallelism": { "name": "storage.jobsParallelism", "value": 10 } }, "metrics": { "storage.dataSizeBytes": { "name": "storage.dataSizeBytes", "value": 112128 }, "storage.rowsCount": { "name": "storage.rowsCount", "value": 1036 } }, "isDisabled": false, "billedMonthlyPrice": null, "dataRetentionTimeInDays": 7, "assignedBackends": [ "snowflake" ], "timezone": null, "isBYODB": false, "usersCount": 2, "fileStorageProvider": "aws" }, "isBYODB": false, "organization": { "id": "123", "created": "2017-02-13T12:01:05+01:00" }, "admin": { "name": "John Doe", "id": 124, "features": [], "isOrganizationMember": true, "role": "admin", "isActivated": true }, "adminOwner": { "id": 124, "name": "John Doe", "email": "john.doe@keboola.com" } } } } }, "403": { "description": "The authorizing token may not read other tokens (`accessDenied`)." }, "404": { "description": "Token not found (`storage.tokens.notFound`)." } } }, "put": { "tags": [ "Tokens and Permissions" ], "summary": "Update token", "description": "Updates token properties. Beware that all current bucket permissions are replaced. If you want to add new\nbucket permissions, don't forget to specify the previous permissions.", "operationId": "put_/v2/storage/tokens/{id}::TokenUpdateAction", "parameters": [ { "name": "id", "in": "path", "description": "Token ID.", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 67319 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateTokenRequest" } ] } } } }, "responses": { "200": { "description": "Updated token. The decrypted `token` value is never returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCreateResponse" }, "example": { "id": "67319", "created": "2017-02-13T10:27:50+0100", "refreshed": "2017-11-13T16:48:28+0100", "description": "New Description", "uri": "https://connection.keboola.com/v2/storage/tokens/67319", "isMasterToken": false, "canManageBuckets": false, "canManageTokens": false, "canReadAllFileUploads": false, "canPurgeTrash": false, "canManageProtectedDefaultBranch": false, "canCreateJobs": false, "canReadAllProjectEvents": false, "canManageDevBranches": false, "expires": null, "isExpired": false, "isDisabled": false, "dailyCapacity": 5, "creatorToken": { "id": 27978, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "dev@keboola.com", "adminId": null }, "bucketPermissions": { "in.c-main": "write" } } } } }, "400": { "description": "Invalid request body (`storage.tokens.validation`) or invalid bucket/component permissions (`storage.tokens.invalidPermissions`)." }, "403": { "description": "The authorizing token may not manage tokens (`accessDenied`)." }, "404": { "description": "Token not found (`storage.tokens.notFound`)." } } }, "delete": { "tags": [ "Tokens and Permissions" ], "summary": "Delete token", "description": "Deletes a token. Only a non-master token (`\"isMasterToken\": false` in the token detail) that is not used by any table trigger can be deleted.", "operationId": "delete_/v2/storage/tokens/{id}::TokenDeleteAction", "parameters": [ { "name": "id", "in": "path", "description": "Token ID.", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 484 } ], "responses": { "204": { "description": "Token deleted." }, "400": { "description": "Token is used by a table trigger and cannot be deleted (`storage.tokens.cannotDeleteDueToOrchestration`)." }, "403": { "description": "The authorizing token may not delete this token (`accessDenied`)." }, "404": { "description": "Token not found (`storage.tokens.notFound`) or the token is a master token (`storage.tokens.cannotDeleteMaster`)." } } } }, "/v2/storage/branch/{branchId}/tokens/{id}": { "get": { "tags": [ "Tokens and Permissions" ], "summary": "Token detail", "description": "Returns all properties of a token, including the project it belongs to (`owner`). You can obtain the token ID, for example, using the Token verification call.\n\nRequesting the token used for authorization is always allowed; requesting any other token requires the `canManageTokens` permission.\n\nAvailable both with and without a development branch prefix; the returned token properties and permission rules are the same in either case.", "operationId": "get_/v2/storage/branch/{branchId}/tokens/{id}::TokenDetailAction", "parameters": [ { "name": "id", "in": "path", "description": "Token ID.", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 44 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Token detail response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenVerifyResponse" }, "example": { "id": "44", "created": "2017-02-13T10:27:50+0100", "refreshed": "2017-11-13T16:48:28+0100", "description": "", "uri": "https://connection.keboola.com/v2/storage/tokens/44", "isMasterToken": true, "canManageBuckets": true, "canManageTokens": true, "canReadAllFileUploads": true, "canPurgeTrash": true, "canManageProtectedDefaultBranch": false, "canCreateJobs": false, "canReadAllProjectEvents": true, "canManageDevBranches": true, "expires": null, "isExpired": false, "isDisabled": false, "dailyCapacity": 0, "actor": null, "bucketPermissions": { "in.c-test": "manage" }, "owner": { "id": 58, "name": "Buckets 5", "type": "production", "region": "us-east-1", "created": "2022-08-18T08:47:07+0200", "expires": null, "features": [], "dataSizeBytes": 112128, "rowsCount": 1036, "hasMysql": false, "hasSynapse": false, "hasSnowflake": true, "hasExasol": false, "hasTeradata": false, "hasBigquery": false, "defaultBackend": "snowflake", "hasTryModeOn": "0", "limits": { "storage.dataSizeBytes": { "name": "storage.dataSizeBytes", "value": 50000000000 }, "storage.jobsParallelism": { "name": "storage.jobsParallelism", "value": 10 } }, "metrics": { "storage.dataSizeBytes": { "name": "storage.dataSizeBytes", "value": 112128 }, "storage.rowsCount": { "name": "storage.rowsCount", "value": 1036 } }, "isDisabled": false, "billedMonthlyPrice": null, "dataRetentionTimeInDays": 7, "assignedBackends": [ "snowflake" ], "timezone": null, "isBYODB": false, "usersCount": 2, "fileStorageProvider": "aws" }, "isBYODB": false, "organization": { "id": "123", "created": "2017-02-13T12:01:05+01:00" }, "admin": { "name": "John Doe", "id": 124, "features": [], "isOrganizationMember": true, "role": "admin", "isActivated": true }, "adminOwner": { "id": 124, "name": "John Doe", "email": "john.doe@keboola.com" } } } } }, "403": { "description": "The authorizing token may not read other tokens (`accessDenied`)." }, "404": { "description": "Token not found (`storage.tokens.notFound`)." } } } }, "/v2/storage/tokens/{id}/events": { "get": { "tags": [ "Events" ], "summary": "Token events list", "description": "Lists all events associated with a particular token.\n\nEvents of the authorized token itself can always be listed. Events of another token require the\npermission to manage tokens.", "operationId": "get_/v2/storage/tokens/{id}/events::TokenEventsListAction", "parameters": [ { "name": "id", "in": "path", "description": "Id of the token.", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 1234 }, { "name": "sinceId", "in": "query", "description": "Shows only events after the specified Id or Uuid (id is deprecated and will be removed in the future).", "required": false, "schema": { "type": "string" }, "example": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3" }, { "name": "maxId", "in": "query", "description": "Shows only events before the passed Id or Uuid (id is deprecated and will be removed in the future).", "required": false, "schema": { "type": "string" }, "example": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3" }, { "name": "component", "in": "query", "description": "Shows only events emitted by the specified component.", "required": false, "schema": { "type": "string" }, "example": "keboola.ex-db-snowflake" }, { "name": "configurationId", "in": "query", "description": "Shows only events related to the given configuration Id.", "required": false, "schema": { "type": "string" }, "example": "123456" }, { "name": "runId", "in": "query", "description": "Shows only events with the specified run Id.", "required": false, "schema": { "type": "string" }, "example": "987654321" }, { "name": "q", "in": "query", "description": "Searches events using advanced [Query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax).", "required": false, "schema": { "type": "string" }, "example": "event:storage.tableImportDone" }, { "name": "limit", "in": "query", "description": "Pagination limit. Maximum allowed value is `10000`.", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 10000, "minimum": 0 }, "example": 100 }, { "name": "offset", "in": "query", "description": "Pagination offset.", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "example": 0 }, { "name": "sortOrder", "in": "query", "description": "Sort order of events: `asc` = oldest first, `desc` = newest first.", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] }, "example": "desc" } ], "responses": { "200": { "description": "List of the token events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsListResponse" }, "example": [ { "uuid": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3", "event": "storage.workspaceLoaded", "component": "storage", "message": "Table in.c-application-testing.cashier-data was loaded to the workspace workspace_78423 as my-table.", "description": "", "type": "info", "runId": null, "created": "2017-02-13T16:42:00+0100", "configurationId": null, "objectId": "in.c-application-testing.cashier-data", "objectName": "cashier-data", "objectType": "table", "context": { "remoteAddr": "203.0.113.10", "httpReferer": null, "httpUserAgent": "Keboola Storage PHP Client", "httpUserAgentOriginal": "Keboola Storage PHP Client", "authorization": "token", "apiVersion": "v2" }, "params": { "name": "my-table", "incremental": false }, "results": { "rowsCount": 1024 }, "performance": { "importDuration": 3 }, "token": { "id": 1234, "name": "support@keboola.com" }, "idBranch": null, "uri": "https://connection.keboola.com/v2/storage/events/01958f48-b1fc-7f05-b9b9-8a4a7b385bc3", "attachments": [] } ] } } }, "400": { "description": "Invalid filter parameters, e.g. `limit` out of range, negative `offset` or unknown `sortOrder` (`storage.events.error`)." }, "403": { "description": "The token is not allowed to manage the requested token." }, "404": { "description": "Token not found (`storage.tokens.notFound`)." } } } }, "/v2/storage/tokens/{id}/refresh": { "post": { "tags": [ "Tokens and Permissions" ], "summary": "Refresh token", "description": "Generates a new token value; the old token value becomes immediately invalid.\nAny token can refresh itself, except a read-only personal access token; refreshing another token\nrequires the `canManageTokens` permission.\n\nThe decrypted `token` value is returned when refreshing a non-master token, the token used for authorization,\nor when the project has a dedicated project feature enabled.", "operationId": "post_/v2/storage/tokens/{id}/refresh::TokenRefreshAction", "parameters": [ { "name": "id", "in": "path", "description": "A valid token ID. You can get it from the Token verification call.", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 48 } ], "responses": { "200": { "description": "Refreshed token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRefreshResponse" }, "example": { "id": "48", "created": "2017-02-13T10:27:50+0100", "refreshed": "2017-11-13T16:48:28+0100", "description": "my-token", "uri": "https://connection.keboola.com/v2/storage/tokens/48", "isMasterToken": false, "canManageBuckets": false, "canManageTokens": false, "canReadAllFileUploads": false, "canPurgeTrash": false, "canManageProtectedDefaultBranch": false, "canCreateJobs": false, "canReadAllProjectEvents": false, "canManageDevBranches": false, "expires": null, "isExpired": false, "isDisabled": false, "dailyCapacity": 5, "token": "48-new-token-value", "creatorToken": { "id": 1, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "1", "name": "dev@keboola.com", "adminId": null }, "bucketPermissions": { "in.c-main": "manage", "out.c-main": "manage" } } } } }, "403": { "description": "The authorizing token may not refresh this token (`accessDenied`), or the request uses a credential issued by agent provisioning (`storage.tokens.agentCredentialNotAllowed`)." }, "404": { "description": "Token not found (`storage.tokens.notFound`)." } } } }, "/v2/storage/tokens/{id}/share": { "post": { "tags": [ "Tokens and Permissions" ], "summary": "Share token", "description": "Use this call whenever you want to securely deliver a token to someone. The link to the token retrieval page will be sent to the\nprovided email address. The link will expire in 2 hours.\n\nMaster tokens and protected-branch tokens cannot be shared; other tokens can be shared only by their creator or the creator's admin.\n\n**Deprecated:** this endpoint will be removed. To get a token value again, use `POST /v2/storage/tokens/{id}/refresh`.\nNote that refreshing generates a new token value and the current value becomes immediately invalid, so every existing\nuser of the token has to be updated.", "operationId": "post_/v2/storage/tokens/{id}/share::TokenShareAction", "parameters": [ { "name": "id", "in": "path", "description": "Token ID.", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 484 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ShareTokenRequest" } ] } } } }, "responses": { "204": { "description": "Token shared, the email was sent." }, "400": { "description": "Invalid request body (`storage.tokens.validation`) or the token is a master token (`storage.token.cannotShareMasterToken`)." }, "403": { "description": "The authorizing token may not manage tokens (`accessDenied`), the token is a protected-branch token (`storage.token.cannotShareProtectedBranchToken`), the caller is not the creator (`storage.tokens.share`), or the request uses a credential issued by agent provisioning (`storage.tokens.agentCredentialNotAllowed`)." }, "404": { "description": "Token not found (`storage.tokens.notFound`)." } }, "deprecated": true } }, "/v2/storage/branch/{branchId}/tokens": { "get": { "tags": [ "Tokens and Permissions" ], "summary": "List all tokens", "description": "Lists all tokens in the project. A token without the `canManageTokens` permission only sees itself.", "operationId": "get_/v2/storage/branch/{branchId}/tokens::TokensListAction", "parameters": [ { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tokens list response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokensListResponse" }, "example": [ { "id": "38", "created": "2012-11-13T16:49:28+0100", "refreshed": "2017-11-13T16:48:28+0100", "description": "", "uri": "https://connection.keboola.com/v2/storage/tokens/38", "isMasterToken": true, "canManageBuckets": true, "canManageTokens": true, "canReadAllFileUploads": true, "canPurgeTrash": true, "canManageProtectedDefaultBranch": false, "canCreateJobs": false, "canReadAllProjectEvents": true, "canManageDevBranches": true, "expires": null, "isExpired": false, "isDisabled": false, "dailyCapacity": 5, "bucketPermissions": { "in.c-main": "manage", "out.c-main": "manage" }, "admin": { "name": "John Doe", "id": 124, "role": "admin" } }, { "id": "40", "created": "2012-11-13T16:49:28+0100", "refreshed": "2017-11-13T16:48:28+0100", "description": "my-token", "uri": "https://connection.keboola.com/v2/storage/tokens/40", "isMasterToken": false, "canManageBuckets": false, "canManageTokens": false, "canReadAllFileUploads": false, "canPurgeTrash": false, "canManageProtectedDefaultBranch": false, "canCreateJobs": false, "canReadAllProjectEvents": false, "canManageDevBranches": false, "expires": null, "isExpired": false, "isDisabled": false, "dailyCapacity": 5, "creatorToken": { "id": 1, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "1", "name": "dev@keboola.com", "adminId": null }, "componentAccess": [ "someComponentName" ], "bucketPermissions": { "in.c-main": "read" } } ] } } } } } }, "/v2/storage/triggers": { "get": { "tags": [ "Triggers" ], "summary": "List", "description": "Lists all triggers of the project with optional filters.", "operationId": "get_/v2/storage/triggers::TriggerListAction", "parameters": [ { "name": "component", "in": "query", "description": "Type of component (typically `orchestration`).", "required": false, "schema": { "description": "Type of component (typically `orchestration`).", "type": "string", "example": "orchestration", "nullable": true }, "example": "orchestration" }, { "name": "configurationId", "in": "query", "description": "ID of component configuration.", "required": false, "schema": { "description": "ID of component configuration.", "type": "string", "example": "config-100", "nullable": true }, "example": "config-100" } ], "responses": { "200": { "description": "List of triggers.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TriggerResponse" } }, "example": [ { "id": "3", "runWithTokenId": 123, "component": "orchestration", "configurationId": "config-100", "lastRun": "2017-02-13T16:42:00+0100", "creatorToken": { "id": 1, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "1", "name": "dev@keboola.com", "adminId": null }, "coolDownPeriodMinutes": 20, "tables": [ { "tableId": "in.c-test.watched-1" }, { "tableId": "in.c-prod.watched-5" } ] } ] } } } } }, "post": { "tags": [ "Triggers" ], "summary": "Create", "description": "Creates a trigger listening on a set of tables.\n\nToken has to be [*master*](https://help.keboola.com/storage/tokens/) (then `runWithTokenId` can be also master). If it isn't master, it has to have `canManageBuckets` permission or `componentAccess` permission for the component which you want to trigger. This also applies when updating and deleting triggers.\nWhen updating the component of trigger you need permissions for both the current component and the component you're updating the trigger to.\n\nWithout `runWithTokenId`, the trigger creates the token it runs with, in the same request, and owns it:\n- The token never expires and is named `[_internal] Token for triggering `.\n- In a project with a protected default branch it can only create jobs; elsewhere it can manage buckets and read all file uploads.\n- Your token has to be able to create that token.\n- If the trigger cannot be created, no token is left behind.\n- Deleting the trigger, or giving it another token, revokes the token.", "operationId": "post_/v2/storage/triggers::TriggerCreateAction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTriggerRequest" } } } }, "responses": { "201": { "description": "Trigger created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerResponse" }, "example": { "id": "3", "runWithTokenId": 123, "component": "orchestration", "configurationId": "config-100", "lastRun": "2017-02-13T16:42:00+0100", "creatorToken": { "id": 1, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "1", "name": "dev@keboola.com", "adminId": null }, "coolDownPeriodMinutes": 20, "tables": [ { "tableId": "in.c-test.watched-1" }, { "tableId": "in.c-prod.watched-5" } ] } } } }, "400": { "description": "Invalid request parameters (`storage.triggers.missingParam`), or invalid `runWithTokenId` (`storage.triggers.invalidTokenPair`, `storage.triggers.invalidRunByToken`)." }, "422": { "description": "Cool down period shorter than 1 minute (`storage.triggers.missingParam`), table from an external bucket (`storage.triggers.triggerOnTableFromExternalBucket`), insufficient privilege for the component (`storage.triggers.insufficientPrivilege`), or no `runWithTokenId` and your token may not create the token the trigger runs with (`storage.triggers.runWithTokenNotCreatable`)." } } } }, "/v2/storage/triggers/": { "get": { "tags": [ "Triggers" ], "summary": "List", "description": "Lists all triggers of the project with optional filters.", "operationId": "get_/v2/storage/triggers/::TriggerListAction", "parameters": [ { "name": "component", "in": "query", "description": "Type of component (typically `orchestration`).", "required": false, "schema": { "description": "Type of component (typically `orchestration`).", "type": "string", "example": "orchestration", "nullable": true }, "example": "orchestration" }, { "name": "configurationId", "in": "query", "description": "ID of component configuration.", "required": false, "schema": { "description": "ID of component configuration.", "type": "string", "example": "config-100", "nullable": true }, "example": "config-100" } ], "responses": { "200": { "description": "List of triggers.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TriggerResponse" } }, "example": [ { "id": "3", "runWithTokenId": 123, "component": "orchestration", "configurationId": "config-100", "lastRun": "2017-02-13T16:42:00+0100", "creatorToken": { "id": 1, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "1", "name": "dev@keboola.com", "adminId": null }, "coolDownPeriodMinutes": 20, "tables": [ { "tableId": "in.c-test.watched-1" }, { "tableId": "in.c-prod.watched-5" } ] } ] } } } } }, "post": { "tags": [ "Triggers" ], "summary": "Create", "description": "Creates a trigger listening on a set of tables.\n\nToken has to be [*master*](https://help.keboola.com/storage/tokens/) (then `runWithTokenId` can be also master). If it isn't master, it has to have `canManageBuckets` permission or `componentAccess` permission for the component which you want to trigger. This also applies when updating and deleting triggers.\nWhen updating the component of trigger you need permissions for both the current component and the component you're updating the trigger to.\n\nWithout `runWithTokenId`, the trigger creates the token it runs with, in the same request, and owns it:\n- The token never expires and is named `[_internal] Token for triggering `.\n- In a project with a protected default branch it can only create jobs; elsewhere it can manage buckets and read all file uploads.\n- Your token has to be able to create that token.\n- If the trigger cannot be created, no token is left behind.\n- Deleting the trigger, or giving it another token, revokes the token.", "operationId": "post_/v2/storage/triggers/::TriggerCreateAction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTriggerRequest" } } } }, "responses": { "201": { "description": "Trigger created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerResponse" }, "example": { "id": "3", "runWithTokenId": 123, "component": "orchestration", "configurationId": "config-100", "lastRun": "2017-02-13T16:42:00+0100", "creatorToken": { "id": 1, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "1", "name": "dev@keboola.com", "adminId": null }, "coolDownPeriodMinutes": 20, "tables": [ { "tableId": "in.c-test.watched-1" }, { "tableId": "in.c-prod.watched-5" } ] } } } }, "400": { "description": "Invalid request parameters (`storage.triggers.missingParam`), or invalid `runWithTokenId` (`storage.triggers.invalidTokenPair`, `storage.triggers.invalidRunByToken`)." }, "422": { "description": "Cool down period shorter than 1 minute (`storage.triggers.missingParam`), table from an external bucket (`storage.triggers.triggerOnTableFromExternalBucket`), insufficient privilege for the component (`storage.triggers.insufficientPrivilege`), or no `runWithTokenId` and your token may not create the token the trigger runs with (`storage.triggers.runWithTokenNotCreatable`)." } } } }, "/v2/storage/triggers/{triggerId}": { "get": { "tags": [ "Triggers" ], "summary": "Get detail", "description": "Get trigger detail.", "operationId": "get_/v2/storage/triggers/{triggerId}::TriggerDetailAction", "parameters": [ { "name": "triggerId", "in": "path", "description": "ID of the trigger you want to get.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 3 } ], "responses": { "200": { "description": "Trigger detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerResponse" }, "example": { "id": "3", "runWithTokenId": 123, "component": "orchestration", "configurationId": "config-100", "lastRun": "2017-02-13T16:42:00+0100", "creatorToken": { "id": 1, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "1", "name": "dev@keboola.com", "adminId": null }, "coolDownPeriodMinutes": 20, "tables": [ { "tableId": "in.c-test.watched-1" }, { "tableId": "in.c-prod.watched-5" } ] } } } }, "404": { "description": "Trigger not found (`storage.triggers.notFound`)." } } }, "put": { "tags": [ "Triggers" ], "summary": "Update", "description": "Updates an existing trigger. All attributes are optional; only the provided ones are changed.\n\nWhen updating the component of trigger you need permissions for both the current component and the component you're updating the trigger to.\n\nGiving a trigger another `runWithTokenId` revokes the token the trigger created for itself, unless another trigger still runs with it.", "operationId": "put_/v2/storage/triggers/{triggerId}::TriggerUpdateAction", "parameters": [ { "name": "triggerId", "in": "path", "description": "ID of the trigger you want to update.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 3 } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTriggerRequest" } } } }, "responses": { "200": { "description": "Trigger updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerResponse" }, "example": { "id": "3", "runWithTokenId": 123, "component": "orchestration", "configurationId": "config-100", "lastRun": "2017-02-13T16:42:00+0100", "creatorToken": { "id": 1, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "1", "name": "dev@keboola.com", "adminId": null }, "coolDownPeriodMinutes": 20, "tables": [ { "tableId": "in.c-test.watched-1" }, { "tableId": "in.c-prod.watched-5" } ] } } } }, "400": { "description": "Invalid request parameters (`storage.triggers.missingParam`), or invalid `runWithTokenId` (`storage.triggers.invalidTokenPair`, `storage.triggers.invalidRunByToken`)." }, "404": { "description": "Trigger not found (`storage.triggers.notFound`)." }, "422": { "description": "Cool down period shorter than 1 minute (`storage.triggers.missingParam`), table from an external bucket (`storage.triggers.triggerOnTableFromExternalBucket`), or insufficient privilege for the component (`storage.triggers.insufficientPrivilege`)." } } }, "delete": { "tags": [ "Triggers" ], "summary": "Delete", "description": "Deletes an existing trigger. The token the trigger created for itself is revoked with it, unless another trigger still runs with it.", "operationId": "delete_/v2/storage/triggers/{triggerId}::TriggerDeleteAction", "parameters": [ { "name": "triggerId", "in": "path", "description": "ID of the trigger you want to delete.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 3 } ], "responses": { "204": { "description": "Trigger deleted." }, "404": { "description": "Trigger not found (`storage.triggers.notFound`)." }, "422": { "description": "Insufficient privilege for the trigger component (`storage.triggers.insufficientPrivilege`)." } } } }, "/v2/storage/triggers/{triggerId}/": { "get": { "tags": [ "Triggers" ], "summary": "Get detail", "description": "Get trigger detail.", "operationId": "get_/v2/storage/triggers/{triggerId}/::TriggerDetailAction", "parameters": [ { "name": "triggerId", "in": "path", "description": "ID of the trigger you want to get.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 3 } ], "responses": { "200": { "description": "Trigger detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerResponse" }, "example": { "id": "3", "runWithTokenId": 123, "component": "orchestration", "configurationId": "config-100", "lastRun": "2017-02-13T16:42:00+0100", "creatorToken": { "id": 1, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "1", "name": "dev@keboola.com", "adminId": null }, "coolDownPeriodMinutes": 20, "tables": [ { "tableId": "in.c-test.watched-1" }, { "tableId": "in.c-prod.watched-5" } ] } } } }, "404": { "description": "Trigger not found (`storage.triggers.notFound`)." } } }, "put": { "tags": [ "Triggers" ], "summary": "Update", "description": "Updates an existing trigger. All attributes are optional; only the provided ones are changed.\n\nWhen updating the component of trigger you need permissions for both the current component and the component you're updating the trigger to.\n\nGiving a trigger another `runWithTokenId` revokes the token the trigger created for itself, unless another trigger still runs with it.", "operationId": "put_/v2/storage/triggers/{triggerId}/::TriggerUpdateAction", "parameters": [ { "name": "triggerId", "in": "path", "description": "ID of the trigger you want to update.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 3 } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTriggerRequest" } } } }, "responses": { "200": { "description": "Trigger updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerResponse" }, "example": { "id": "3", "runWithTokenId": 123, "component": "orchestration", "configurationId": "config-100", "lastRun": "2017-02-13T16:42:00+0100", "creatorToken": { "id": 1, "description": "dev@keboola.com" }, "actor": { "type": "token", "id": "1", "name": "dev@keboola.com", "adminId": null }, "coolDownPeriodMinutes": 20, "tables": [ { "tableId": "in.c-test.watched-1" }, { "tableId": "in.c-prod.watched-5" } ] } } } }, "400": { "description": "Invalid request parameters (`storage.triggers.missingParam`), or invalid `runWithTokenId` (`storage.triggers.invalidTokenPair`, `storage.triggers.invalidRunByToken`)." }, "404": { "description": "Trigger not found (`storage.triggers.notFound`)." }, "422": { "description": "Cool down period shorter than 1 minute (`storage.triggers.missingParam`), table from an external bucket (`storage.triggers.triggerOnTableFromExternalBucket`), or insufficient privilege for the component (`storage.triggers.insufficientPrivilege`)." } } }, "delete": { "tags": [ "Triggers" ], "summary": "Delete", "description": "Deletes an existing trigger. The token the trigger created for itself is revoked with it, unless another trigger still runs with it.", "operationId": "delete_/v2/storage/triggers/{triggerId}/::TriggerDeleteAction", "parameters": [ { "name": "triggerId", "in": "path", "description": "ID of the trigger you want to delete.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 3 } ], "responses": { "204": { "description": "Trigger deleted." }, "404": { "description": "Trigger not found (`storage.triggers.notFound`)." }, "422": { "description": "Insufficient privilege for the trigger component (`storage.triggers.insufficientPrivilege`)." } } } }, "/v2/storage/branch/{branchId}/validate/column-names": { "post": { "tags": [ "Validate" ], "summary": "Validate column names", "description": "Validate strings if they can be used as column names. Column names can be used for example:\n- creating a table (`POST /buckets/{bucketId}/tables-definition`)\n- adding a column (`POST /tables/{tableId}/columns`)", "operationId": "post_/v2/storage/branch/{branchId}/validate/column-names::ValidateColumnNamesAction", "parameters": [ { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ValidateColumnNamesRequest" } ] } } } }, "responses": { "204": { "description": "All column names are valid." }, "422": { "description": "At least one column name is invalid (e.g. contains characters other than alphanumeric and underscore); the validation error lists the offending names." } } } }, "/v2/storage/validate/column-names": { "post": { "tags": [ "Validate" ], "summary": "Validate column names", "description": "Validate strings if they can be used as column names. Column names can be used for example:\n- creating a table (`POST /buckets/{bucketId}/tables-definition`)\n- adding a column (`POST /tables/{tableId}/columns`)", "operationId": "post_/v2/storage/validate/column-names::ValidateColumnNamesAction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ValidateColumnNamesRequest" } ] } } } }, "responses": { "204": { "description": "All column names are valid." }, "422": { "description": "At least one column name is invalid (e.g. contains characters other than alphanumeric and underscore); the validation error lists the offending names." } } } }, "/v2/storage/branch/{branchId}/webalize/column-names": { "post": { "tags": [ "Webalize" ], "summary": "Webalize Column Names", "description": "Webalize strings. Does not validate whether they can be used as database column names.", "operationId": "post_/v2/storage/branch/{branchId}/webalize/column-names::WebalizeColumnNamesAction", "parameters": [ { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebalizeColumnNameRequest" } ] } } } }, "responses": { "200": { "description": "List of webalized column names.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebalizeColumnNamesResponse" }, "example": { "columnNames": [ "First_Column_Name", "Second_Column_Name" ] } } } }, "422": { "description": "Column name cannot be webalized to a valid value (`storage.webalize.columnName.invalid`)." } } } }, "/v2/storage/webalize/column-names": { "post": { "tags": [ "Webalize" ], "summary": "Webalize Column Names", "description": "Webalize strings. Does not validate whether they can be used as database column names.", "operationId": "post_/v2/storage/webalize/column-names::WebalizeColumnNamesAction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebalizeColumnNameRequest" } ] } } } }, "responses": { "200": { "description": "List of webalized column names.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebalizeColumnNamesResponse" }, "example": { "columnNames": [ "First_Column_Name", "Second_Column_Name" ] } } } }, "422": { "description": "Column name cannot be webalized to a valid value (`storage.webalize.columnName.invalid`)." } } } }, "/v2/storage/branch/{branchId}/webalize/display-name": { "post": { "tags": [ "Webalize" ], "summary": "Webalize Display Name", "description": "Webalize string which you want to use as `displayName` for tables (`PUT /tables/{tableId}`)\nand buckets (`PUT /buckets/{bucketId}`).", "operationId": "post_/v2/storage/branch/{branchId}/webalize/display-name::WebalizeDisplayNameAction", "parameters": [ { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebalizeDisplayNameRequest" } ] } } } }, "responses": { "200": { "description": "Webalized display name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebalizeDisplayNameResponse" }, "example": { "displayName": "My-Display-Name" } } } }, "422": { "description": "Display name cannot be webalized to a valid value (`storage.webalize.displayName.invalid`)." } } } }, "/v2/storage/webalize/display-name": { "post": { "tags": [ "Webalize" ], "summary": "Webalize Display Name", "description": "Webalize string which you want to use as `displayName` for tables (`PUT /tables/{tableId}`)\nand buckets (`PUT /buckets/{bucketId}`).", "operationId": "post_/v2/storage/webalize/display-name::WebalizeDisplayNameAction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebalizeDisplayNameRequest" } ] } } } }, "responses": { "200": { "description": "Webalized display name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebalizeDisplayNameResponse" }, "example": { "displayName": "My-Display-Name" } } } }, "422": { "description": "Display name cannot be webalized to a valid value (`storage.webalize.displayName.invalid`)." } } } }, "/v2/storage/branch/{branchId}/input-mapping-load/preview": { "post": { "tags": [ "Workspaces" ], "summary": "Input mapping load preview", "description": "Accepts a component-style input-mapping configuration (the same payload as `/workspaces/{workspaceId}/input-mapping-load`)\nand returns the resolved load types per table for a backend, without targeting a workspace and without creating a job.\nThe backend is resolved per item from the item `backend` field, then the `backend` query parameter, then the project\ndefault; the winner must be one of the project's assigned backends.", "operationId": "post_/v2/storage/branch/{branchId}/input-mapping-load/preview::InputMappingLoadPreviewAction", "parameters": [ { "name": "backend", "in": "query", "description": "Default backend for items that do not set their own `backend`. Must be one of the project's assigned backends. Falls back to the project default when omitted.", "required": false, "schema": { "type": "string", "nullable": true, "default": null }, "example": "snowflake" }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputMappingLoadRequest" }, "example": { "input": [ { "source": "in.c-main.orders", "destination": "orders" }, { "source": "in.c-main.customers", "destination": "customers", "columns": [ "id", "email" ] } ] } } } }, "responses": { "200": { "description": "Validates the payload exactly as the real load would and returns the resolved load types per input table for the resolved backend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputMappingLoadPreviewResponse" }, "example": { "input": [ { "source": "in.c-main.orders", "destination": "orders", "loadType": "CLONE", "possibleLoadTypes": [ "COPY", "CLONE" ] }, { "source": "in.c-main.customers", "destination": "customers", "loadType": "COPY", "possibleLoadTypes": [ "COPY" ] } ] } } } }, "400": { "description": "Invalid request \u2014 validation error, unsupported option, load type not available, or duplicate destination." }, "403": { "description": "Caller does not have access to the requested source table (`workspace.tableAccessDenied`)." }, "404": { "description": "Source bucket or source table not found (`workspace.sourceNotFound`)." }, "422": { "description": "Resolved backend is not assigned to the project, or is unsupported for the requested load (`workspace.backendNotSupported`)." } } } }, "/v2/storage/input-mapping-load/preview": { "post": { "tags": [ "Workspaces" ], "summary": "Input mapping load preview", "description": "Accepts a component-style input-mapping configuration (the same payload as `/workspaces/{workspaceId}/input-mapping-load`)\nand returns the resolved load types per table for a backend, without targeting a workspace and without creating a job.\nThe backend is resolved per item from the item `backend` field, then the `backend` query parameter, then the project\ndefault; the winner must be one of the project's assigned backends.", "operationId": "post_/v2/storage/input-mapping-load/preview::InputMappingLoadPreviewAction", "parameters": [ { "name": "backend", "in": "query", "description": "Default backend for items that do not set their own `backend`. Must be one of the project's assigned backends. Falls back to the project default when omitted.", "required": false, "schema": { "type": "string", "nullable": true, "default": null }, "example": "snowflake" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputMappingLoadRequest" }, "example": { "input": [ { "source": "in.c-main.orders", "destination": "orders" }, { "source": "in.c-main.customers", "destination": "customers", "columns": [ "id", "email" ] } ] } } } }, "responses": { "200": { "description": "Validates the payload exactly as the real load would and returns the resolved load types per input table for the resolved backend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputMappingLoadPreviewResponse" }, "example": { "input": [ { "source": "in.c-main.orders", "destination": "orders", "loadType": "CLONE", "possibleLoadTypes": [ "COPY", "CLONE" ] }, { "source": "in.c-main.customers", "destination": "customers", "loadType": "COPY", "possibleLoadTypes": [ "COPY" ] } ] } } } }, "400": { "description": "Invalid request \u2014 validation error, unsupported option, load type not available, or duplicate destination." }, "403": { "description": "Caller does not have access to the requested source table (`workspace.tableAccessDenied`)." }, "404": { "description": "Source bucket or source table not found (`workspace.sourceNotFound`)." }, "422": { "description": "Resolved backend is not assigned to the project, or is unsupported for the requested load (`workspace.backendNotSupported`)." } } } }, "/v2/storage/branch/{branchId}/workspaces/{workspaceId}/public-key": { "post": { "tags": [ "Workspaces" ], "summary": "Workspace set public-key", "description": "Sets a public key for the workspace user. Supported only on Snowflake. Snowflake supports two public keys to exist;\nwhen the API is called without `keyName`, either a new key is created or the older one is replaced. Use the\n`/public-key/{keyName}` variant to set a specific key (`RSA_PUBLIC_KEY` or `RSA_PUBLIC_KEY_2`).", "operationId": "post_/v2/storage/branch/{branchId}/workspaces/{workspaceId}/public-key::WorkspacesSetPublicKeyAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 234 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetWorkspacePublicKeyRequest" }, "example": { "publicKey": "-----BEGIN PUBLIC KEY-----..." } } } }, "responses": { "200": { "description": "Workspace detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceDetailResponse" } } } }, "400": { "description": "Returned when the backend is not supported (`workspace.backendNotSupported`), the public key is invalid, or the login type does not support certificates." }, "403": { "description": "Returned when the workspace is governed (login type `governed`): no login can be installed on it (`storage.workspace.governedOperationNotAllowed`)." }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." } } } }, "/v2/storage/workspaces/{workspaceId}/public-key": { "post": { "tags": [ "Workspaces" ], "summary": "Workspace set public-key", "description": "Sets a public key for the workspace user. Supported only on Snowflake. Snowflake supports two public keys to exist;\nwhen the API is called without `keyName`, either a new key is created or the older one is replaced. Use the\n`/public-key/{keyName}` variant to set a specific key (`RSA_PUBLIC_KEY` or `RSA_PUBLIC_KEY_2`).", "operationId": "post_/v2/storage/workspaces/{workspaceId}/public-key::WorkspacesSetPublicKeyAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 234 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetWorkspacePublicKeyRequest" }, "example": { "publicKey": "-----BEGIN PUBLIC KEY-----..." } } } }, "responses": { "200": { "description": "Workspace detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceDetailResponse" } } } }, "400": { "description": "Returned when the backend is not supported (`workspace.backendNotSupported`), the public key is invalid, or the login type does not support certificates." }, "403": { "description": "Returned when the workspace is governed (login type `governed`): no login can be installed on it (`storage.workspace.governedOperationNotAllowed`)." }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." } } } }, "/v2/storage/branch/{branchId}/workspaces/{workspaceId}/public-key/{keyName}": { "post": { "tags": [ "Workspaces" ], "summary": "Workspace set public-key", "description": "Sets a public key for the workspace user. Supported only on Snowflake. Snowflake supports two public keys to exist;\nwhen the API is called without `keyName`, either a new key is created or the older one is replaced. Use the\n`/public-key/{keyName}` variant to set a specific key (`RSA_PUBLIC_KEY` or `RSA_PUBLIC_KEY_2`).", "operationId": "post_/v2/storage/branch/{branchId}/workspaces/{workspaceId}/public-key/{keyName}::WorkspacesSetPublicKeyAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 234 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "keyName", "in": "path", "required": true, "schema": { "type": "string", "pattern": "RSA_PUBLIC_KEY|RSA_PUBLIC_KEY_2|BQ_KEY_1|BQ_KEY_2", "enum": [ "RSA_PUBLIC_KEY", "RSA_PUBLIC_KEY_2", "BQ_KEY_1", "BQ_KEY_2" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetWorkspacePublicKeyRequest" }, "example": { "publicKey": "-----BEGIN PUBLIC KEY-----..." } } } }, "responses": { "200": { "description": "Workspace detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceDetailResponse" } } } }, "400": { "description": "Returned when the backend is not supported (`workspace.backendNotSupported`), the public key is invalid, or the login type does not support certificates." }, "403": { "description": "Returned when the workspace is governed (login type `governed`): no login can be installed on it (`storage.workspace.governedOperationNotAllowed`)." }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." } } } }, "/v2/storage/workspaces/{workspaceId}/public-key/{keyName}": { "post": { "tags": [ "Workspaces" ], "summary": "Workspace set public-key", "description": "Sets a public key for the workspace user. Supported only on Snowflake. Snowflake supports two public keys to exist;\nwhen the API is called without `keyName`, either a new key is created or the older one is replaced. Use the\n`/public-key/{keyName}` variant to set a specific key (`RSA_PUBLIC_KEY` or `RSA_PUBLIC_KEY_2`).", "operationId": "post_/v2/storage/workspaces/{workspaceId}/public-key/{keyName}::WorkspacesSetPublicKeyAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 234 }, { "name": "keyName", "in": "path", "required": true, "schema": { "type": "string", "pattern": "RSA_PUBLIC_KEY|RSA_PUBLIC_KEY_2|BQ_KEY_1|BQ_KEY_2", "enum": [ "RSA_PUBLIC_KEY", "RSA_PUBLIC_KEY_2", "BQ_KEY_1", "BQ_KEY_2" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetWorkspacePublicKeyRequest" }, "example": { "publicKey": "-----BEGIN PUBLIC KEY-----..." } } } }, "responses": { "200": { "description": "Workspace detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceDetailResponse" } } } }, "400": { "description": "Returned when the backend is not supported (`workspace.backendNotSupported`), the public key is invalid, or the login type does not support certificates." }, "403": { "description": "Returned when the workspace is governed (login type `governed`): no login can be installed on it (`storage.workspace.governedOperationNotAllowed`)." }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." } } } }, "/v2/storage/branch/{branchId}/workspaces/{workspaceId}/objects/batch-delete": { "post": { "tags": [ "Workspaces" ], "summary": "Batch delete workspace objects", "description": "Deletes multiple tables and views from a workspace in a single async operation. Returns a `workspaceBatchDeleteObjects`\njob. All objects are attempted even if some fail, but the job will be marked as failed if any deletion fails.", "operationId": "post_/v2/storage/branch/{branchId}/workspaces/{workspaceId}/objects/batch-delete::ObjectBatchDeleteAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 456 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteRequest" }, "example": { "objects": [ "MY_TABLE", "MY_VIEW" ] } } } }, "responses": { "202": { "description": "Batch delete job enqueued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 12345, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/12345", "tableId": null, "operationName": "workspaceBatchDeleteObjects", "operationParams": { "workspaceId": 456, "objects": "[\"MY_TABLE\",\"MY_VIEW\"]" }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "user@keboola.com" } } } } }, "400": { "description": "Returned when the request body is invalid (e.g. empty `objects` list), or the workspace is deactivated (`workspace.workspaceDeactivated`)." }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." } } } }, "/v2/storage/workspaces/{workspaceId}/objects/batch-delete": { "post": { "tags": [ "Workspaces" ], "summary": "Batch delete workspace objects", "description": "Deletes multiple tables and views from a workspace in a single async operation. Returns a `workspaceBatchDeleteObjects`\njob. All objects are attempted even if some fail, but the job will be marked as failed if any deletion fails.", "operationId": "post_/v2/storage/workspaces/{workspaceId}/objects/batch-delete::ObjectBatchDeleteAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 456 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteRequest" }, "example": { "objects": [ "MY_TABLE", "MY_VIEW" ] } } } }, "responses": { "202": { "description": "Batch delete job enqueued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 12345, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/12345", "tableId": null, "operationName": "workspaceBatchDeleteObjects", "operationParams": { "workspaceId": 456, "objects": "[\"MY_TABLE\",\"MY_VIEW\"]" }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "user@keboola.com" } } } } }, "400": { "description": "Returned when the request body is invalid (e.g. empty `objects` list), or the workspace is deactivated (`workspace.workspaceDeactivated`)." }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." } } } }, "/v2/storage/branch/{branchId}/workspaces/{workspaceId}/objects": { "get": { "tags": [ "Workspaces" ], "summary": "List workspace objects", "description": "Returns a list of objects (tables and views) present in the workspace schema. Supported on Snowflake and BigQuery\nbackends.", "operationId": "get_/v2/storage/branch/{branchId}/workspaces/{workspaceId}/objects::ObjectListAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 456 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of objects in the workspace.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectListResponse" } }, "example": [ { "name": "MY_TABLE", "type": "table" }, { "name": "MY_VIEW", "type": "view" } ] } } }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." }, "422": { "description": "Returned when the workspace backend is not supported (`workspace.backendNotSupported`)." } } } }, "/v2/storage/workspaces/{workspaceId}/objects": { "get": { "tags": [ "Workspaces" ], "summary": "List workspace objects", "description": "Returns a list of objects (tables and views) present in the workspace schema. Supported on Snowflake and BigQuery\nbackends.", "operationId": "get_/v2/storage/workspaces/{workspaceId}/objects::ObjectListAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 456 } ], "responses": { "200": { "description": "List of objects in the workspace.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectListResponse" } }, "example": [ { "name": "MY_TABLE", "type": "table" }, { "name": "MY_VIEW", "type": "view" } ] } } }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." }, "422": { "description": "Returned when the workspace backend is not supported (`workspace.backendNotSupported`)." } } } }, "/v2/storage/branch/{branchId}/workspaces": { "get": { "tags": [ "Workspaces" ], "summary": "List workspaces", "description": "Returns all workspaces for the project in the given branch. Use `default` as `branchId` (or the variant without\nthe branch prefix) to list workspaces of the default branch.", "operationId": "get_/v2/storage/branch/{branchId}/workspaces::WorkspacesListAction", "parameters": [ { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of workspaces.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceDetailResponse" } }, "example": [ { "id": 234, "type": "table", "name": "boring_wozniak", "component": "wr-db", "configurationId": "aws-1", "configurationVersion": null, "created": "2016-05-17T11:11:20+0200", "connection": { "backend": "snowflake", "region": "us-east1", "host": "keboola.snowflakecomputing.com", "database": "keboola_123", "schema": "boring_wozniak", "warehouse": "SAPI_PROD", "user": "xzy", "loginType": "default", "ssoLoginAvailable": false, "account": "keboola", "role": "boring_wozniak" }, "backendSize": "small", "statementTimeoutSeconds": 0, "creatorToken": { "id": 234, "description": "martin@keboola.com" }, "actor": { "type": "token", "id": "234", "name": "martin@keboola.com", "adminId": null }, "readOnlyStorageAccess": true, "platformUsageType": "user", "state": "active", "deactivateAt": null, "deleteAt": null } ] } } }, "422": { "description": "Returned when a workspace uses an unsupported backend (`workspace.backendNotSupported`)." } } }, "post": { "tags": [ "Workspaces" ], "summary": "Create workspace", "description": "Creates a new workspace and returns its credentials. Workspaces provide a playground for your data. You can load data\nfrom your storage, explore or modify it and then, optionally, load it back to storage tables. A workspace is represented\nby access credentials to a storage backend with permissions to write to the workspace specific database schema.\n\nSet `async=true` to create the workspace in a background job. Calling the endpoint with `async=false` is deprecated.\n\nTo create a workspace bound to a component configuration (including a reader workspace), use the\n`/components/{componentId}/configs/{configurationId}/workspaces` variant of this endpoint.\n\nAll workspaces endpoints can be used with `default` for the `branchId` parameter, which emulates the call without\na development branch: `GET /v2/storage/workspaces` is the same as `GET /v2/storage/branch/default/workspaces`.", "operationId": "post_/v2/storage/branch/{branchId}/workspaces::WorkspaceCreateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Component identifier. Only for the configuration workspace variant of the endpoint.", "required": false, "schema": { "type": "string" }, "example": "keboola.snowflake-transformation" }, { "name": "configurationId", "in": "path", "description": "Configuration identifier. Only for the configuration workspace variant of the endpoint.", "required": false, "schema": { "type": "string" }, "example": "1234567890" }, { "name": "async", "in": "query", "description": "Create workspace in a background job. Calling the parameter as `async=false` is deprecated.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true }, { "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": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateWorkspaceRequest" } ] } } } }, "responses": { "201": { "description": "Synchronous call response (`async=false`). The password (or key/connection string) is returned only here and cannot be retrieved later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCreatedResponse" }, "example": { "id": 234, "type": "table", "name": "boring_wozniak", "component": "wr-db", "configurationId": "aws-1", "configurationVersion": null, "created": "2016-05-17T11:11:20+0200", "connection": { "backend": "snowflake", "region": "us-east1", "host": "keboola.snowflakecomputing.com", "database": "keboola_123", "schema": "boring_wozniak", "warehouse": "SAPI_PROD", "user": "xzy", "loginType": "default", "ssoLoginAvailable": false, "password": "abc", "account": "keboola", "role": "boring_wozniak" }, "backendSize": "small", "statementTimeoutSeconds": 0, "creatorToken": { "id": 234, "description": "martin@keboola.com" }, "actor": { "type": "token", "id": "234", "name": "martin@keboola.com", "adminId": null }, "readOnlyStorageAccess": true, "platformUsageType": "user", "state": "active", "deactivateAt": null, "deleteAt": null } } } }, "202": { "description": "Asynchronous call response (`async=true`) that creates a new `workspaceCreate` job. To see the job detail use the Job Detail endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "workspaceCreate", "operationParams": { "backend": "snowflake", "branchId": 1 }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" } } } } }, "400": { "description": "Returned when the request is invalid, e.g. unsupported backend or backend size (`workspace.backendNotSupported`), dynamic backend size feature not enabled, invalid reader/direct-grant configuration, or a backend driver error." }, "403": { "description": "Returned when the token lacks write access to a direct grant output mapping bucket, or when the user has the read-only role in the project." }, "404": { "description": "Returned when the component or configuration is not found (configuration workspace variant only)." }, "501": { "description": "Returned when creating a configuration workspace in a Snowflake Partner Connect limited project." } } } }, "/v2/storage/workspaces": { "get": { "tags": [ "Workspaces" ], "summary": "List workspaces", "description": "Returns all workspaces for the project in the given branch. Use `default` as `branchId` (or the variant without\nthe branch prefix) to list workspaces of the default branch.", "operationId": "get_/v2/storage/workspaces::WorkspacesListAction", "responses": { "200": { "description": "List of workspaces.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceDetailResponse" } }, "example": [ { "id": 234, "type": "table", "name": "boring_wozniak", "component": "wr-db", "configurationId": "aws-1", "configurationVersion": null, "created": "2016-05-17T11:11:20+0200", "connection": { "backend": "snowflake", "region": "us-east1", "host": "keboola.snowflakecomputing.com", "database": "keboola_123", "schema": "boring_wozniak", "warehouse": "SAPI_PROD", "user": "xzy", "loginType": "default", "ssoLoginAvailable": false, "account": "keboola", "role": "boring_wozniak" }, "backendSize": "small", "statementTimeoutSeconds": 0, "creatorToken": { "id": 234, "description": "martin@keboola.com" }, "actor": { "type": "token", "id": "234", "name": "martin@keboola.com", "adminId": null }, "readOnlyStorageAccess": true, "platformUsageType": "user", "state": "active", "deactivateAt": null, "deleteAt": null } ] } } }, "422": { "description": "Returned when a workspace uses an unsupported backend (`workspace.backendNotSupported`)." } } }, "post": { "tags": [ "Workspaces" ], "summary": "Create workspace", "description": "Creates a new workspace and returns its credentials. Workspaces provide a playground for your data. You can load data\nfrom your storage, explore or modify it and then, optionally, load it back to storage tables. A workspace is represented\nby access credentials to a storage backend with permissions to write to the workspace specific database schema.\n\nSet `async=true` to create the workspace in a background job. Calling the endpoint with `async=false` is deprecated.\n\nTo create a workspace bound to a component configuration (including a reader workspace), use the\n`/components/{componentId}/configs/{configurationId}/workspaces` variant of this endpoint.\n\nAll workspaces endpoints can be used with `default` for the `branchId` parameter, which emulates the call without\na development branch: `GET /v2/storage/workspaces` is the same as `GET /v2/storage/branch/default/workspaces`.", "operationId": "post_/v2/storage/workspaces::WorkspaceCreateAction", "parameters": [ { "name": "componentId", "in": "path", "description": "Component identifier. Only for the configuration workspace variant of the endpoint.", "required": false, "schema": { "type": "string" }, "example": "keboola.snowflake-transformation" }, { "name": "configurationId", "in": "path", "description": "Configuration identifier. Only for the configuration workspace variant of the endpoint.", "required": false, "schema": { "type": "string" }, "example": "1234567890" }, { "name": "async", "in": "query", "description": "Create workspace in a background job. Calling the parameter as `async=false` is deprecated.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true }, { "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/CreateWorkspaceRequest" } ] } } } }, "responses": { "201": { "description": "Synchronous call response (`async=false`). The password (or key/connection string) is returned only here and cannot be retrieved later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCreatedResponse" }, "example": { "id": 234, "type": "table", "name": "boring_wozniak", "component": "wr-db", "configurationId": "aws-1", "configurationVersion": null, "created": "2016-05-17T11:11:20+0200", "connection": { "backend": "snowflake", "region": "us-east1", "host": "keboola.snowflakecomputing.com", "database": "keboola_123", "schema": "boring_wozniak", "warehouse": "SAPI_PROD", "user": "xzy", "loginType": "default", "ssoLoginAvailable": false, "password": "abc", "account": "keboola", "role": "boring_wozniak" }, "backendSize": "small", "statementTimeoutSeconds": 0, "creatorToken": { "id": 234, "description": "martin@keboola.com" }, "actor": { "type": "token", "id": "234", "name": "martin@keboola.com", "adminId": null }, "readOnlyStorageAccess": true, "platformUsageType": "user", "state": "active", "deactivateAt": null, "deleteAt": null } } } }, "202": { "description": "Asynchronous call response (`async=true`) that creates a new `workspaceCreate` job. To see the job detail use the Job Detail endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "workspaceCreate", "operationParams": { "backend": "snowflake", "branchId": 1 }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" } } } } }, "400": { "description": "Returned when the request is invalid, e.g. unsupported backend or backend size (`workspace.backendNotSupported`), dynamic backend size feature not enabled, invalid reader/direct-grant configuration, or a backend driver error." }, "403": { "description": "Returned when the token lacks write access to a direct grant output mapping bucket, or when the user has the read-only role in the project." }, "404": { "description": "Returned when the component or configuration is not found (configuration workspace variant only)." }, "501": { "description": "Returned when creating a configuration workspace in a Snowflake Partner Connect limited project." } } } }, "/v2/storage/branch/{branchId}/workspaces/{workspaceId}": { "get": { "tags": [ "Workspaces" ], "summary": "Workspace detail", "description": "Retrieves information about a given workspace. Note that the password to the workspace can be retrieved only when\nthe workspace is created.", "operationId": "get_/v2/storage/branch/{branchId}/workspaces/{workspaceId}::WorkspacesDetailAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 234 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspace detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceDetailResponse" }, "example": { "id": 234, "type": "table", "name": "boring_wozniak", "component": "wr-db", "configurationId": "aws-1", "configurationVersion": null, "created": "2016-05-17T11:11:20+0200", "connection": { "backend": "snowflake", "region": "us-east1", "host": "keboola.snowflakecomputing.com", "database": "keboola_123", "schema": "boring_wozniak", "warehouse": "SAPI_PROD", "user": "xzy", "loginType": "default", "ssoLoginAvailable": false, "account": "keboola", "role": "boring_wozniak" }, "backendSize": "small", "statementTimeoutSeconds": 0, "creatorToken": { "id": 234, "description": "martin@keboola.com" }, "actor": { "type": "token", "id": "234", "name": "martin@keboola.com", "adminId": null }, "readOnlyStorageAccess": true, "platformUsageType": "user", "state": "active", "deactivateAt": null, "deleteAt": null } } } }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." }, "422": { "description": "Returned when the workspace uses an unsupported backend (`workspace.backendNotSupported`)." } } }, "delete": { "tags": [ "Workspaces" ], "summary": "Delete workspace", "description": "Deletes a workspace. This also irreversibly removes the workspace content.", "operationId": "delete_/v2/storage/branch/{branchId}/workspaces/{workspaceId}::WorkspaceDeleteAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 234 }, { "name": "async", "in": "query", "description": "Workspace will be deleted asynchronously. A `workspaceDelete` job will be created and enqueued.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true }, { "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": { "204": { "description": "Workspace deleted (synchronous call)." }, "202": { "description": "Workspace delete job enqueued (`async=true`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "workspaceDelete", "operationParams": { "workspaceId": 234 }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "martin@keboola.com" } } } } }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." }, "422": { "description": "Returned when the workspace uses an unsupported backend (`workspace.backendNotSupported`)." } } } }, "/v2/storage/workspaces/{workspaceId}": { "get": { "tags": [ "Workspaces" ], "summary": "Workspace detail", "description": "Retrieves information about a given workspace. Note that the password to the workspace can be retrieved only when\nthe workspace is created.", "operationId": "get_/v2/storage/workspaces/{workspaceId}::WorkspacesDetailAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 234 } ], "responses": { "200": { "description": "Workspace detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceDetailResponse" }, "example": { "id": 234, "type": "table", "name": "boring_wozniak", "component": "wr-db", "configurationId": "aws-1", "configurationVersion": null, "created": "2016-05-17T11:11:20+0200", "connection": { "backend": "snowflake", "region": "us-east1", "host": "keboola.snowflakecomputing.com", "database": "keboola_123", "schema": "boring_wozniak", "warehouse": "SAPI_PROD", "user": "xzy", "loginType": "default", "ssoLoginAvailable": false, "account": "keboola", "role": "boring_wozniak" }, "backendSize": "small", "statementTimeoutSeconds": 0, "creatorToken": { "id": 234, "description": "martin@keboola.com" }, "actor": { "type": "token", "id": "234", "name": "martin@keboola.com", "adminId": null }, "readOnlyStorageAccess": true, "platformUsageType": "user", "state": "active", "deactivateAt": null, "deleteAt": null } } } }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." }, "422": { "description": "Returned when the workspace uses an unsupported backend (`workspace.backendNotSupported`)." } } }, "delete": { "tags": [ "Workspaces" ], "summary": "Delete workspace", "description": "Deletes a workspace. This also irreversibly removes the workspace content.", "operationId": "delete_/v2/storage/workspaces/{workspaceId}::WorkspaceDeleteAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 234 }, { "name": "async", "in": "query", "description": "Workspace will be deleted asynchronously. A `workspaceDelete` job will be created and enqueued.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "X-KBC-Backend", "in": "header", "schema": { "schema": "BackendConfigurationRequest", "properties": { "context": { "type": "string", "nullable": true, "minLength": 1 } }, "type": "object" } } ], "responses": { "204": { "description": "Workspace deleted (synchronous call)." }, "202": { "description": "Workspace delete job enqueued (`async=true`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 11, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/11", "tableId": null, "operationName": "workspaceDelete", "operationParams": { "workspaceId": 234 }, "createdTime": "2013-05-31T16:11:05+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "martin@keboola.com" } } } } }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." }, "422": { "description": "Returned when the workspace uses an unsupported backend (`workspace.backendNotSupported`)." } } } }, "/v2/storage/branch/{branchId}/workspaces/{workspaceId}/input-mapping-load": { "post": { "tags": [ "Workspaces" ], "summary": "Input mapping load", "description": "Loads tables from Storage into a Workspace using a `keboola/input-mapping` `Configuration\\Table` payload (snake_case)\naccepted unchanged. This mirrors what component code already produces and removes the need to translate to the SAPI\ncamelCase `/load` shape.\n\nThe endpoint resolves the load type per input item via the canonical `LoadTypeDecider` with priority\n**CLONE > VIEW > COPY**. CLONE is gated by the `bq-enable-clone` feature on BigQuery; VIEW on Snowflake is gated by\nthe `input-mapping-read-only-storage` feature.\n\nEach input item must reference its source via `source` \u2014 the full source table id (e.g. `in.c-bucket.mytable`).\n`where_column` and `where_values` must be provided together (setting one without the other returns HTTP 400).\n\n**Dry-run** (`dryRun=true`): preflight variant that resolves the load type per input item **without** creating a job.\nThe dry-run runs the same validations the real load runs \u2014 a successful 200 dry-run guarantees the same payload\nsubmitted with `dryRun=false` will not be rejected by validation (modulo source state changing between calls).\nIt returns HTTP 200 (not 202) with `loadType` (the type `LoadTypeDecider` would pick) and `possibleLoadTypes`\n(all types acceptable for the item; useful for driving a UI dropdown) per input item.\n\nThis operation is also available scoped to a [Development Branch](#tag/Development-Branches),\nat `/branch/{branchId}/workspaces/{workspaceId}/input-mapping-load`. The `dryRun` query\nparameter and both response shapes behave identically there.", "operationId": "post_/v2/storage/branch/{branchId}/workspaces/{workspaceId}/input-mapping-load::WorkspaceInputMappingLoadAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the target workspace.", "required": true, "schema": { "type": "integer", "pattern": "[1-9][0-9]*" }, "example": 504345774 }, { "name": "dryRun", "in": "query", "description": "If `true`, do not create a job \u2014 return resolved load types per table instead.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true }, { "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": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputMappingLoadRequest" }, "example": { "input": [ { "source": "in.c-main.orders", "destination": "orders" }, { "source": "in.c-main.customers", "destination": "customers", "columns": [ "id", "email" ], "where_column": "country", "where_values": [ "CZ", "SK" ], "where_operator": "eq", "keep_internal_timestamp_column": false } ] } } } }, "responses": { "200": { "description": "Dry-run (`dryRun=true`): the payload was validated exactly as the real load would and the resolved load types per input table are returned. No job is created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputMappingLoadDryRunResponse" }, "example": { "dryRun": true, "operationName": "workspaceLoad", "input": [ { "source": "in.c-main.orders", "destination": "orders", "loadType": "CLONE", "possibleLoadTypes": [ "COPY", "CLONE" ] }, { "source": "in.c-main.customers", "destination": "customers", "loadType": "COPY", "possibleLoadTypes": [ "COPY" ] } ] } } } }, "202": { "description": "Workspace load job enqueued (`dryRun=false`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 75682259, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/75682259", "tableId": null, "operationName": "workspaceLoad", "operationParams": { "workspaceId": "504345774", "preserve": false, "input": [ { "source": "in.c-main.orders", "destination": "orders" } ], "queue": "main" }, "createdTime": "2026-05-12T10:15:52+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" } } } } }, "400": { "description": "Invalid request \u2014 validation error (`workspace.loadRequestBadInput`), unsupported option, load type not available for the item, duplicate destination, `where_column` without `where_values`, or a deactivated workspace (`workspace.workspaceDeactivated`)." }, "403": { "description": "Caller does not have access to the requested source table (`workspace.tableAccessDenied`)." }, "404": { "description": "Workspace (`workspace.workspaceNotFound`) or source table (`workspace.sourceNotFound`) not found." }, "422": { "description": "Unsupported workspace backend for the requested load (`workspace.backendNotSupported`)." } } } }, "/v2/storage/workspaces/{workspaceId}/input-mapping-load": { "post": { "tags": [ "Workspaces" ], "summary": "Input mapping load", "description": "Loads tables from Storage into a Workspace using a `keboola/input-mapping` `Configuration\\Table` payload (snake_case)\naccepted unchanged. This mirrors what component code already produces and removes the need to translate to the SAPI\ncamelCase `/load` shape.\n\nThe endpoint resolves the load type per input item via the canonical `LoadTypeDecider` with priority\n**CLONE > VIEW > COPY**. CLONE is gated by the `bq-enable-clone` feature on BigQuery; VIEW on Snowflake is gated by\nthe `input-mapping-read-only-storage` feature.\n\nEach input item must reference its source via `source` \u2014 the full source table id (e.g. `in.c-bucket.mytable`).\n`where_column` and `where_values` must be provided together (setting one without the other returns HTTP 400).\n\n**Dry-run** (`dryRun=true`): preflight variant that resolves the load type per input item **without** creating a job.\nThe dry-run runs the same validations the real load runs \u2014 a successful 200 dry-run guarantees the same payload\nsubmitted with `dryRun=false` will not be rejected by validation (modulo source state changing between calls).\nIt returns HTTP 200 (not 202) with `loadType` (the type `LoadTypeDecider` would pick) and `possibleLoadTypes`\n(all types acceptable for the item; useful for driving a UI dropdown) per input item.\n\nThis operation is also available scoped to a [Development Branch](#tag/Development-Branches),\nat `/branch/{branchId}/workspaces/{workspaceId}/input-mapping-load`. The `dryRun` query\nparameter and both response shapes behave identically there.", "operationId": "post_/v2/storage/workspaces/{workspaceId}/input-mapping-load::WorkspaceInputMappingLoadAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the target workspace.", "required": true, "schema": { "type": "integer", "pattern": "[1-9][0-9]*" }, "example": 504345774 }, { "name": "dryRun", "in": "query", "description": "If `true`, do not create a job \u2014 return resolved load types per table instead.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true }, { "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": { "$ref": "#/components/schemas/InputMappingLoadRequest" }, "example": { "input": [ { "source": "in.c-main.orders", "destination": "orders" }, { "source": "in.c-main.customers", "destination": "customers", "columns": [ "id", "email" ], "where_column": "country", "where_values": [ "CZ", "SK" ], "where_operator": "eq", "keep_internal_timestamp_column": false } ] } } } }, "responses": { "200": { "description": "Dry-run (`dryRun=true`): the payload was validated exactly as the real load would and the resolved load types per input table are returned. No job is created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputMappingLoadDryRunResponse" }, "example": { "dryRun": true, "operationName": "workspaceLoad", "input": [ { "source": "in.c-main.orders", "destination": "orders", "loadType": "CLONE", "possibleLoadTypes": [ "COPY", "CLONE" ] }, { "source": "in.c-main.customers", "destination": "customers", "loadType": "COPY", "possibleLoadTypes": [ "COPY" ] } ] } } } }, "202": { "description": "Workspace load job enqueued (`dryRun=false`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 75682259, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/75682259", "tableId": null, "operationName": "workspaceLoad", "operationParams": { "workspaceId": "504345774", "preserve": false, "input": [ { "source": "in.c-main.orders", "destination": "orders" } ], "queue": "main" }, "createdTime": "2026-05-12T10:15:52+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" } } } } }, "400": { "description": "Invalid request \u2014 validation error (`workspace.loadRequestBadInput`), unsupported option, load type not available for the item, duplicate destination, `where_column` without `where_values`, or a deactivated workspace (`workspace.workspaceDeactivated`)." }, "403": { "description": "Caller does not have access to the requested source table (`workspace.tableAccessDenied`)." }, "404": { "description": "Workspace (`workspace.workspaceNotFound`) or source table (`workspace.sourceNotFound`) not found." }, "422": { "description": "Unsupported workspace backend for the requested load (`workspace.backendNotSupported`)." } } } }, "/v2/storage/branch/{branchId}/workspaces/{workspaceId}/load": { "post": { "tags": [ "Workspaces" ], "summary": "Load data", "description": "Loads tables from Storage into a Workspace. BigQuery supports only loading as view.\n\nEach `input` item maps a source table (`source`, or `dataFileId` for file workspaces) to a `destination` table in the\nworkspace. Optional per-item settings allow limiting rows (`rows`, `changedSince`, `changedUntil`, `whereFilters`),\nselecting and typing columns (`columns`), incremental loading (`incremental`), overwriting existing tables when\n`preserve` is set (`overwrite`), defining a primary key (`primaryKey`, Snowflake only) and selecting the load type.\n\n`loadType`: default `COPY`. Use `AUTO` to let Storage API decide the best load type. Copy is used always when\nfilters, columns, or incremental are set. `CLONE` is supported on Snowflake and BigQuery backends and accepts only\n`source`, `destination`, `overwrite` and `dropTimestampColumn` options; it is not supported with incremental loading\nor for linked buckets on BigQuery. `VIEW` is experimental for Snowflake (requires feature\n`input-mapping-read-only-storage`, aliases are not supported) and works on BigQuery without a feature (aliases are not\nsupported); a view is created in the workspace instead of loading the table (accepts only `source`, `destination`\nand `overwrite`).\n\n`whereColumn`, `whereValues`, `whereOperator` and `seconds` are deprecated; use `whereFilters`, `changedSince` and\n`changedUntil` instead.\n\nThe load runs as an asynchronous `workspaceLoad` job.", "operationId": "post_/v2/storage/branch/{branchId}/workspaces/{workspaceId}/load::WorkspaceLoadAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 504345774 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadRequest" } } } }, "responses": { "202": { "description": "Workspace load job enqueued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 75682259, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/75682259", "tableId": null, "operationName": "workspaceLoad", "operationParams": { "workspaceId": "504345774", "preserve": false, "input": [ { "source": "in.c-application-testing.carseats", "destination": "table1" }, { "source": "in.c-application-testing.cashier-data", "destination": "table2" } ], "queue": "main" }, "createdTime": "2019-05-13T21:15:52+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" } } } } }, "400": { "description": "Returned when the input mapping is invalid (`workspace.loadRequestBadInput`), the load type is not supported or combined incorrectly, destinations are duplicated, `overwrite` conflicts with `preserve`/`incremental`, the source branch does not exist, the table does not support timestamp based filtering, or the workspace is deactivated (`workspace.workspaceDeactivated`)." }, "403": { "description": "Returned when the token has no access to a source table (`workspace.tableAccessDenied`)." }, "404": { "description": "Returned when the workspace (`workspace.workspaceNotFound`) or a source table (`workspace.sourceNotFound`) is not found." }, "422": { "description": "Returned when the workspace uses an unsupported backend (`workspace.backendNotSupported`)." } } } }, "/v2/storage/workspaces/{workspaceId}/load": { "post": { "tags": [ "Workspaces" ], "summary": "Load data", "description": "Loads tables from Storage into a Workspace. BigQuery supports only loading as view.\n\nEach `input` item maps a source table (`source`, or `dataFileId` for file workspaces) to a `destination` table in the\nworkspace. Optional per-item settings allow limiting rows (`rows`, `changedSince`, `changedUntil`, `whereFilters`),\nselecting and typing columns (`columns`), incremental loading (`incremental`), overwriting existing tables when\n`preserve` is set (`overwrite`), defining a primary key (`primaryKey`, Snowflake only) and selecting the load type.\n\n`loadType`: default `COPY`. Use `AUTO` to let Storage API decide the best load type. Copy is used always when\nfilters, columns, or incremental are set. `CLONE` is supported on Snowflake and BigQuery backends and accepts only\n`source`, `destination`, `overwrite` and `dropTimestampColumn` options; it is not supported with incremental loading\nor for linked buckets on BigQuery. `VIEW` is experimental for Snowflake (requires feature\n`input-mapping-read-only-storage`, aliases are not supported) and works on BigQuery without a feature (aliases are not\nsupported); a view is created in the workspace instead of loading the table (accepts only `source`, `destination`\nand `overwrite`).\n\n`whereColumn`, `whereValues`, `whereOperator` and `seconds` are deprecated; use `whereFilters`, `changedSince` and\n`changedUntil` instead.\n\nThe load runs as an asynchronous `workspaceLoad` job.", "operationId": "post_/v2/storage/workspaces/{workspaceId}/load::WorkspaceLoadAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 504345774 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadRequest" } } } }, "responses": { "202": { "description": "Workspace load job enqueued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 75682259, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/75682259", "tableId": null, "operationName": "workspaceLoad", "operationParams": { "workspaceId": "504345774", "preserve": false, "input": [ { "source": "in.c-application-testing.carseats", "destination": "table1" }, { "source": "in.c-application-testing.cashier-data", "destination": "table2" } ], "queue": "main" }, "createdTime": "2019-05-13T21:15:52+0200", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" } } } } }, "400": { "description": "Returned when the input mapping is invalid (`workspace.loadRequestBadInput`), the load type is not supported or combined incorrectly, destinations are duplicated, `overwrite` conflicts with `preserve`/`incremental`, the source branch does not exist, the table does not support timestamp based filtering, or the workspace is deactivated (`workspace.workspaceDeactivated`)." }, "403": { "description": "Returned when the token has no access to a source table (`workspace.tableAccessDenied`)." }, "404": { "description": "Returned when the workspace (`workspace.workspaceNotFound`) or a source table (`workspace.sourceNotFound`) is not found." }, "422": { "description": "Returned when the workspace uses an unsupported backend (`workspace.backendNotSupported`)." } } } }, "/v2/storage/branch/{branchId}/workspaces/{workspaceId}/password": { "post": { "tags": [ "Workspaces" ], "summary": "Password reset", "description": "Generates a new password for the given workspace. For a file workspace a new token with 24 hours expiration is\nissued; previously created tokens have to expire and cannot be reset. For a BigQuery workspace a new service account\nkey is returned.", "operationId": "post_/v2/storage/branch/{branchId}/workspaces/{workspaceId}/password::WorkspacePasswordAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 234 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "New password (Snowflake), service account credentials (BigQuery) or connection string (file workspace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspacePasswordResetResponse" }, "example": { "password": "2Fd4e1c67a2d28fced849ee1bb76e7391b93eb12" } } } }, "400": { "description": "Returned when password reset is not supported for the workspace login type (`workspace.resetPasswordNotSupported`), file storage or backend (`workspace.backendNotSupported`), or the workspace is deactivated (`workspace.workspaceDeactivated`)." }, "403": { "description": "Returned when the workspace is governed (login type `governed`): no login can be handed out for it (`storage.workspace.governedOperationNotAllowed`)." }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." } } } }, "/v2/storage/workspaces/{workspaceId}/password": { "post": { "tags": [ "Workspaces" ], "summary": "Password reset", "description": "Generates a new password for the given workspace. For a file workspace a new token with 24 hours expiration is\nissued; previously created tokens have to expire and cannot be reset. For a BigQuery workspace a new service account\nkey is returned.", "operationId": "post_/v2/storage/workspaces/{workspaceId}/password::WorkspacePasswordAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 234 } ], "responses": { "201": { "description": "New password (Snowflake), service account credentials (BigQuery) or connection string (file workspace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspacePasswordResetResponse" }, "example": { "password": "2Fd4e1c67a2d28fced849ee1bb76e7391b93eb12" } } } }, "400": { "description": "Returned when password reset is not supported for the workspace login type (`workspace.resetPasswordNotSupported`), file storage or backend (`workspace.backendNotSupported`), or the workspace is deactivated (`workspace.workspaceDeactivated`)." }, "403": { "description": "Returned when the workspace is governed (login type `governed`): no login can be handed out for it (`storage.workspace.governedOperationNotAllowed`)." }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." } } } }, "/v2/storage/branch/{branchId}/workspaces/{workspaceId}/saml2-login": { "get": { "tags": [ "Workspaces" ], "summary": "Initialize Snowflake SSO login", "description": "Issues a signed SAML 2.0 response that lets the current user log into the workspace via Snowflake SSO. Available only\nfor Snowflake workspaces whose backend has SAML2 SSO configured and whose login type allows SSO\n(`connection.ssoLoginAvailable` in the workspace detail). POST the returned `samlResponse` and `relayState` to `acsUrl`.\nAvailable only in the branch-scoped URL form.", "operationId": "get_/v2/storage/branch/{branchId}/workspaces/{workspaceId}/saml2-login::WorkspaceSsoInitializeAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 234 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SAML login payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSaml2LoginResponse" }, "example": { "acsUrl": "https://keboola.snowflakecomputing.com/fed/login", "samlResponse": "PHNhbWxwOlJlc3BvbnNlIC4uLg==", "relayState": "eyJ3b3Jrc3BhY2VJZCI6MjM0fQ", "expiresAt": "2026-08-27T10:05:00+00:00" } } } }, "400": { "description": "Returned when SSO login is not set up or not supported for the workspace backend (`workspace.ssoNotSet`, `workspace.backendNotSupported`)." }, "403": { "description": "Returned when the workspace is governed (login type `governed`), which has no login of its own." }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." } } } }, "/v2/storage/branch/{branchId}/workspaces/{workspaceId}/credentials": { "post": { "tags": [ "Workspaces" ], "summary": "Create credentials", "description": "Create new or fetch existing dedicated credentials for a workspace, to be used e.g. in QueryService. Workspaces created\nwith `loginType=none` do not contain direct connection credentials; create them with this endpoint when a client needs\nto connect directly. Snowflake credentials use key-pair authentication (the private key is returned in\n`connection.privateKey`), BigQuery credentials return a service account key in `connection.credentials`.\nThe credentials hold the same direct grants as the workspace itself, resolved from the workspace's configuration.", "operationId": "post_/v2/storage/branch/{branchId}/workspaces/{workspaceId}/credentials::WorkspaceStorageCredentialsCreateAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "[1-9][0-9]*" }, "example": 254 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceStorageCredentialsCreateRequest" }, "example": [] } } }, "responses": { "200": { "description": "Workspace detail including the credentials secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceDetailResponseWithSecret" }, "example": { "id": 254, "type": "table", "name": "WORKSPACE_123", "component": null, "configurationId": null, "configurationVersion": null, "created": "2025-08-13T15:03:18+0200", "connection": { "backend": "snowflake", "region": "eu-central-1", "host": "kebooladev.snowflakecomputing.com", "database": "DB_123", "schema": "WORKSPACE_123", "warehouse": "DEV", "user": "JSWORKSPACE_123_QS", "loginType": "snowflake-service-keypair", "ssoLoginAvailable": false, "account": "kebooladev", "role": "JSWORKSPACE_123", "privateKey": "-----BEGIN PRIVATE KEY--....", "credentials": { "id": 356 } }, "backendSize": "small", "statementTimeoutSeconds": 0, "creatorToken": { "id": 1, "description": "token" }, "actor": { "type": "token", "id": "1", "name": "token", "adminId": null }, "readOnlyStorageAccess": true, "platformUsageType": "user", "state": "active", "deactivateAt": null, "deleteAt": null } } } }, "400": { "description": "Returned when the workspace backend is not supported (`workspace.backendNotSupported`); only BigQuery and Snowflake are supported. Also returned when the workspace is deactivated (`workspace.workspaceDeactivated`), or when the configuration declares more linked-dataset tables than a BigQuery identity can be bound to (`workspace.directGrantLinkedDatasetTableLimitExceeded`)." }, "403": { "description": "Returned when the workspace is governed (login type `governed`) and the caller is not Query Service (`storage.workspace.governedOperationNotAllowed`)." }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." }, "409": { "description": "Returned when the workspace lock could not be acquired because another credentials operation is in progress (`storage.workspace.lockFailedToAcquire`)." } } } }, "/v2/storage/workspaces/{workspaceId}/credentials": { "post": { "tags": [ "Workspaces" ], "summary": "Create credentials", "description": "Create new or fetch existing dedicated credentials for a workspace, to be used e.g. in QueryService. Workspaces created\nwith `loginType=none` do not contain direct connection credentials; create them with this endpoint when a client needs\nto connect directly. Snowflake credentials use key-pair authentication (the private key is returned in\n`connection.privateKey`), BigQuery credentials return a service account key in `connection.credentials`.\nThe credentials hold the same direct grants as the workspace itself, resolved from the workspace's configuration.", "operationId": "post_/v2/storage/workspaces/{workspaceId}/credentials::WorkspaceStorageCredentialsCreateAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "[1-9][0-9]*" }, "example": 254 } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceStorageCredentialsCreateRequest" }, "example": [] } } }, "responses": { "200": { "description": "Workspace detail including the credentials secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceDetailResponseWithSecret" }, "example": { "id": 254, "type": "table", "name": "WORKSPACE_123", "component": null, "configurationId": null, "configurationVersion": null, "created": "2025-08-13T15:03:18+0200", "connection": { "backend": "snowflake", "region": "eu-central-1", "host": "kebooladev.snowflakecomputing.com", "database": "DB_123", "schema": "WORKSPACE_123", "warehouse": "DEV", "user": "JSWORKSPACE_123_QS", "loginType": "snowflake-service-keypair", "ssoLoginAvailable": false, "account": "kebooladev", "role": "JSWORKSPACE_123", "privateKey": "-----BEGIN PRIVATE KEY--....", "credentials": { "id": 356 } }, "backendSize": "small", "statementTimeoutSeconds": 0, "creatorToken": { "id": 1, "description": "token" }, "actor": { "type": "token", "id": "1", "name": "token", "adminId": null }, "readOnlyStorageAccess": true, "platformUsageType": "user", "state": "active", "deactivateAt": null, "deleteAt": null } } } }, "400": { "description": "Returned when the workspace backend is not supported (`workspace.backendNotSupported`); only BigQuery and Snowflake are supported. Also returned when the workspace is deactivated (`workspace.workspaceDeactivated`), or when the configuration declares more linked-dataset tables than a BigQuery identity can be bound to (`workspace.directGrantLinkedDatasetTableLimitExceeded`)." }, "403": { "description": "Returned when the workspace is governed (login type `governed`) and the caller is not Query Service (`storage.workspace.governedOperationNotAllowed`)." }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." }, "409": { "description": "Returned when the workspace lock could not be acquired because another credentials operation is in progress (`storage.workspace.lockFailedToAcquire`)." } } } }, "/v2/storage/branch/{branchId}/workspaces/{workspaceId}/credentials/{id}": { "get": { "tags": [ "Workspaces" ], "summary": "Credentials detail", "description": "Get details of the specified workspace credentials, including the secret (`connection.privateKey` for Snowflake\nkey-pair credentials, `connection.credentials` for BigQuery, `connection.password` for password based credentials).", "operationId": "get_/v2/storage/branch/{branchId}/workspaces/{workspaceId}/credentials/{id}::WorkspaceStorageCredentialsDetailAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "[1-9][0-9]*" }, "example": 254 }, { "name": "id", "in": "path", "description": "ID of the credentials.", "required": true, "schema": { "type": "integer", "pattern": "[1-9][0-9]*" }, "example": 356 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspace detail including the credentials secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceDetailResponseWithSecret" }, "example": { "id": 254, "type": "table", "name": "WORKSPACE_123", "component": null, "configurationId": null, "configurationVersion": null, "created": "2025-08-13T15:03:18+0200", "connection": { "backend": "snowflake", "region": "eu-central-1", "host": "kebooladev.snowflakecomputing.com", "database": "DB_123", "schema": "WORKSPACE_123", "warehouse": "DEV", "user": "JSWORKSPACE_123_QS", "loginType": "snowflake-service-keypair", "ssoLoginAvailable": false, "account": "kebooladev", "role": "JSWORKSPACE_123", "privateKey": "-----BEGIN PRIVATE KEY--....", "credentials": { "id": 356 } }, "backendSize": "small", "statementTimeoutSeconds": 0, "creatorToken": { "id": 1, "description": "token" }, "actor": { "type": "token", "id": "1", "name": "token", "adminId": null }, "readOnlyStorageAccess": true, "platformUsageType": "user", "state": "active", "deactivateAt": null, "deleteAt": null } } } }, "403": { "description": "Returned when the workspace is governed (login type `governed`) and the caller is not Query Service (`storage.workspace.governedOperationNotAllowed`)." }, "404": { "description": "Returned when the workspace (`workspace.workspaceNotFound`) or the credentials (`workspace.workspaceCredentialNotFound`) are not found." } } }, "delete": { "tags": [ "Workspaces" ], "summary": "Delete credential", "description": "Delete the specified workspace credential from both the database and the backend (BigQuery or Snowflake).\nThe backend user will be invalidated, and on BigQuery its table-level direct grants are stripped first.\nRetry the call when it reports a concurrent action on the workspace.", "operationId": "delete_/v2/storage/branch/{branchId}/workspaces/{workspaceId}/credentials/{id}::WorkspaceStorageCredentialsDeleteAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "[1-9][0-9]*" }, "example": 254 }, { "name": "id", "in": "path", "description": "ID of the credential.", "required": true, "schema": { "type": "integer", "pattern": "[1-9][0-9]*" }, "example": 356 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Credential deleted." }, "403": { "description": "Returned when the workspace is governed (login type `governed`) and the caller is not Query Service (`storage.workspace.governedOperationNotAllowed`)." }, "404": { "description": "Returned when the workspace (`workspace.workspaceNotFound`) or the credentials (`workspace.workspaceCredentialNotFound`) are not found." }, "409": { "description": "Returned when the workspace lock could not be acquired because another credentials or direct-grant operation is in progress (`storage.workspace.lockFailedToAcquire`)." } } } }, "/v2/storage/workspaces/{workspaceId}/credentials/{id}": { "get": { "tags": [ "Workspaces" ], "summary": "Credentials detail", "description": "Get details of the specified workspace credentials, including the secret (`connection.privateKey` for Snowflake\nkey-pair credentials, `connection.credentials` for BigQuery, `connection.password` for password based credentials).", "operationId": "get_/v2/storage/workspaces/{workspaceId}/credentials/{id}::WorkspaceStorageCredentialsDetailAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "[1-9][0-9]*" }, "example": 254 }, { "name": "id", "in": "path", "description": "ID of the credentials.", "required": true, "schema": { "type": "integer", "pattern": "[1-9][0-9]*" }, "example": 356 } ], "responses": { "200": { "description": "Workspace detail including the credentials secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceDetailResponseWithSecret" }, "example": { "id": 254, "type": "table", "name": "WORKSPACE_123", "component": null, "configurationId": null, "configurationVersion": null, "created": "2025-08-13T15:03:18+0200", "connection": { "backend": "snowflake", "region": "eu-central-1", "host": "kebooladev.snowflakecomputing.com", "database": "DB_123", "schema": "WORKSPACE_123", "warehouse": "DEV", "user": "JSWORKSPACE_123_QS", "loginType": "snowflake-service-keypair", "ssoLoginAvailable": false, "account": "kebooladev", "role": "JSWORKSPACE_123", "privateKey": "-----BEGIN PRIVATE KEY--....", "credentials": { "id": 356 } }, "backendSize": "small", "statementTimeoutSeconds": 0, "creatorToken": { "id": 1, "description": "token" }, "actor": { "type": "token", "id": "1", "name": "token", "adminId": null }, "readOnlyStorageAccess": true, "platformUsageType": "user", "state": "active", "deactivateAt": null, "deleteAt": null } } } }, "403": { "description": "Returned when the workspace is governed (login type `governed`) and the caller is not Query Service (`storage.workspace.governedOperationNotAllowed`)." }, "404": { "description": "Returned when the workspace (`workspace.workspaceNotFound`) or the credentials (`workspace.workspaceCredentialNotFound`) are not found." } } }, "delete": { "tags": [ "Workspaces" ], "summary": "Delete credential", "description": "Delete the specified workspace credential from both the database and the backend (BigQuery or Snowflake).\nThe backend user will be invalidated, and on BigQuery its table-level direct grants are stripped first.\nRetry the call when it reports a concurrent action on the workspace.", "operationId": "delete_/v2/storage/workspaces/{workspaceId}/credentials/{id}::WorkspaceStorageCredentialsDeleteAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "[1-9][0-9]*" }, "example": 254 }, { "name": "id", "in": "path", "description": "ID of the credential.", "required": true, "schema": { "type": "integer", "pattern": "[1-9][0-9]*" }, "example": 356 } ], "responses": { "204": { "description": "Credential deleted." }, "403": { "description": "Returned when the workspace is governed (login type `governed`) and the caller is not Query Service (`storage.workspace.governedOperationNotAllowed`)." }, "404": { "description": "Returned when the workspace (`workspace.workspaceNotFound`) or the credentials (`workspace.workspaceCredentialNotFound`) are not found." }, "409": { "description": "Returned when the workspace lock could not be acquired because another credentials or direct-grant operation is in progress (`storage.workspace.lockFailedToAcquire`)." } } } }, "/v2/storage/branch/{branchId}/workspaces/{workspaceId}/table-export": { "post": { "tags": [ "Workspaces" ], "summary": "Export table from workspace", "description": "Export a table from a workspace to file storage. This endpoint creates an asynchronous `workspaceTableExport` job\nthat exports the specified table from the workspace schema to file storage. The exported file can then be downloaded\nusing the file ID returned in the job results.\n\n**Note:** Supported for Snowflake and BigQuery workspaces.\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 [TableExportJobResponse](#model-TableExportJobResponse).", "operationId": "post_/v2/storage/branch/{branchId}/workspaces/{workspaceId}/table-export::WorkspaceTableExportAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 504345774 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Table, file name and file type to export.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTableExportRequest" }, "example": { "tableName": "my_table", "fileName": "custom_export", "fileType": "csv", "gzip": true } } } }, "responses": { "400": { "description": "Returned when the table is not found in the workspace or the table cannot be exported (`storage.workspace.cannotExportTableFromWorkspace`), the workspace backend is not supported (`workspace.backendNotSupported`), or the workspace is deactivated (`workspace.workspaceDeactivated`)." }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." }, "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/TableExportJobResponse" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/TableExportJobResponse" } } } } }, "/v2/storage/workspaces/{workspaceId}/table-export": { "post": { "tags": [ "Workspaces" ], "summary": "Export table from workspace", "description": "Export a table from a workspace to file storage. This endpoint creates an asynchronous `workspaceTableExport` job\nthat exports the specified table from the workspace schema to file storage. The exported file can then be downloaded\nusing the file ID returned in the job results.\n\n**Note:** Supported for Snowflake and BigQuery workspaces.\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 [TableExportJobResponse](#model-TableExportJobResponse).", "operationId": "post_/v2/storage/workspaces/{workspaceId}/table-export::WorkspaceTableExportAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "\\d+" }, "example": 504345774 } ], "requestBody": { "description": "Table, file name and file type to export.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTableExportRequest" }, "example": { "tableName": "my_table", "fileName": "custom_export", "fileType": "csv", "gzip": true } } } }, "responses": { "400": { "description": "Returned when the table is not found in the workspace or the table cannot be exported (`storage.workspace.cannotExportTableFromWorkspace`), the workspace backend is not supported (`workspace.backendNotSupported`), or the workspace is deactivated (`workspace.workspaceDeactivated`)." }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." }, "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/TableExportJobResponse" } } } } }, "x-storage-job-result": { "application/json": { "schema": { "$ref": "#/components/schemas/TableExportJobResponse" } } } } }, "/v2/storage/branch/{branchId}/workspaces/{workspaceId}/unload": { "post": { "tags": [ "Workspaces" ], "summary": "Unload workspace", "description": "Validates the workspace's component configuration (transformation, data app, or SQL workspace) and\nexamines its output mapping for tables using the direct-grant strategy, then enqueues a refresh job\nfor them.\n\nReturns an array of jobs instead of a single job.", "operationId": "post_/v2/storage/branch/{branchId}/workspaces/{workspaceId}/unload::WorkspaceUnloadAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "Workspace identifier.", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } }, { "name": "only-direct-grants", "in": "query", "description": "Filter to only process tables with direct-grant strategy.", "required": false, "schema": { "type": "boolean" } }, { "name": "onlyDirectGrants", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Workspace unload jobs enqueued.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "description": "Returned when configuration is not found, pinned configuration version no longer exists, a table referenced in pinned version no longer exists, or the workspace is deactivated (`workspace.workspaceDeactivated`)." }, "403": { "description": "Returned when the token lacks write access to a direct grant output mapping bucket, or when the user has the read-only role in the project." }, "404": { "description": "Returned when the workspace is not found." } } } }, "/v2/storage/branch/{branchId}/workspaces/{workspaceId}/load-clone": { "post": { "tags": [ "Workspaces" ], "summary": "Load data using CLONE", "description": "**Deprecated, use the `/load` endpoint with `loadType: CLONE`.**\n\nLoad tables from Storage into a Workspace using zero-copy cloning. Supported on Snowflake and BigQuery backends.\nThis load type does not support any filtering, processing parameters, or incremental loading.\nLinked buckets are not supported on BigQuery.\n\nThe cloned table is an exact copy of the source table, including the `_timestamp` system column\n(unless `dropTimestampColumn` is set). The load runs as an asynchronous `workspaceLoad` job.", "operationId": "post_/v2/storage/branch/{branchId}/workspaces/{workspaceId}/load-clone::WorkspacesLoadCloneAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 78423 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneLoadRequest" }, "example": { "input": [ { "source": "in.c-application-testing.cashier-data", "destination": "my-table" } ] } } } }, "responses": { "202": { "description": "Workspace load job enqueued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 22077337, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/22077337", "tableId": null, "operationName": "workspaceLoad", "operationParams": { "workspaceId": "78423", "preserve": false, "input": [ { "source": "in.c-application-testing.cashier-data", "destination": "my-table" } ], "queue": "main_fast" }, "createdTime": "2017-02-13T16:41:18+0100", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" } } } } }, "400": { "description": "Returned when the input is invalid (`workspace.loadRequestBadInput`), clone is not supported for the workspace backend or source (external bucket, linked bucket on BigQuery), destinations are duplicated, `overwrite` conflicts with `preserve`, the source branch does not exist, or the workspace is deactivated (`workspace.workspaceDeactivated`)." }, "403": { "description": "Returned when the token has no access to a source table (`workspace.tableAccessDenied`)." }, "404": { "description": "Returned when the workspace (`workspace.workspaceNotFound`) or a source table (`workspace.sourceNotFound`) is not found." } } } }, "/v2/storage/workspaces/{workspaceId}/load-clone": { "post": { "tags": [ "Workspaces" ], "summary": "Load data using CLONE", "description": "**Deprecated, use the `/load` endpoint with `loadType: CLONE`.**\n\nLoad tables from Storage into a Workspace using zero-copy cloning. Supported on Snowflake and BigQuery backends.\nThis load type does not support any filtering, processing parameters, or incremental loading.\nLinked buckets are not supported on BigQuery.\n\nThe cloned table is an exact copy of the source table, including the `_timestamp` system column\n(unless `dropTimestampColumn` is set). The load runs as an asynchronous `workspaceLoad` job.", "operationId": "post_/v2/storage/workspaces/{workspaceId}/load-clone::WorkspacesLoadCloneAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace.", "required": true, "schema": { "type": "integer", "pattern": "[0-9]+" }, "example": 78423 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneLoadRequest" }, "example": { "input": [ { "source": "in.c-application-testing.cashier-data", "destination": "my-table" } ] } } } }, "responses": { "202": { "description": "Workspace load job enqueued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "id": 22077337, "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/22077337", "tableId": null, "operationName": "workspaceLoad", "operationParams": { "workspaceId": "78423", "preserve": false, "input": [ { "source": "in.c-application-testing.cashier-data", "destination": "my-table" } ], "queue": "main_fast" }, "createdTime": "2017-02-13T16:41:18+0100", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "dev@keboola.com" } } } } }, "400": { "description": "Returned when the input is invalid (`workspace.loadRequestBadInput`), clone is not supported for the workspace backend or source (external bucket, linked bucket on BigQuery), destinations are duplicated, `overwrite` conflicts with `preserve`, the source branch does not exist, or the workspace is deactivated (`workspace.workspaceDeactivated`)." }, "403": { "description": "Returned when the token has no access to a source table (`workspace.tableAccessDenied`)." }, "404": { "description": "Returned when the workspace (`workspace.workspaceNotFound`) or a source table (`workspace.sourceNotFound`) is not found." } } } }, "/v2/storage/branch/{branchId}/workspaces/{workspaceId}/query": { "post": { "tags": [ "Workspaces" ], "summary": "Execute query", "description": "**DEPRECATED.** This endpoint is deprecated and scheduled for removal on 2026-09-01. There is no direct replacement.\n\nExecutes a native Snowflake/BigQuery SQL query in the given workspace directly without any validation or checks.\nThe query can contain only one SQL statement per request. Every request is a new session. The response has a\ndifferent format for a SELECT query (`status: ok` + `data`), a non-SELECT statement (`status: ok` + `message`)\nand a failed query (`status: error` + `message`).", "operationId": "post_/v2/storage/branch/{branchId}/workspaces/{workspaceId}/query::WorkspacesQueryAction", "parameters": [ { "name": "workspaceId", "in": "path", "description": "ID of the workspace to run the query against.", "required": true, "schema": { "type": "integer", "pattern": "[1-9][0-9]*" }, "example": 234 }, { "name": "branchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteQueryRequest" }, "example": { "query": "SELECT * FROM table_name" } } } }, "responses": { "200": { "description": "Query execution response. A failed query also returns 200 with `status: error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteQueryResponse" }, "example": { "status": "ok", "data": { "columns": [ "ID", "NAME" ], "rows": [ { "ID": "8", "NAME": "Lisa Simpson" }, { "ID": "10", "NAME": "Bart Simpson" } ] } } } } }, "400": { "description": "Returned when query execution is not supported for the workspace backend, login type or reader workspace, or the workspace is deactivated (`workspace.workspaceDeactivated`)." }, "403": { "description": "Returned when the workspace is governed (login type `governed`): it can be read only through Query Service (`storage.workspace.governedOperationNotAllowed`)." }, "404": { "description": "Returned when the workspace is not found (`workspace.workspaceNotFound`)." }, "422": { "description": "Returned when the workspace backend or login type cannot provide credentials for the query (`workspace.backendNotSupported`)." } }, "deprecated": true } } }, "components": { "schemas": { "BucketRegisterGuideRequest": { "required": [ "path" ], "properties": { "path": { "description": "Path to the schema. Snowflake: `[\"database-name\", \"schema-name\"]`; BigQuery: `[\"dataset-name\"]`.", "type": "array", "items": { "type": "string", "minLength": 1 }, "example": [ "my-database-name", "my-schema-name" ] }, "backend": { "description": "Bucket backend type; the default value is determined by the project settings.", "type": "string", "example": "snowflake", "nullable": true, "enum": [ "snowflake", "bigquery" ] }, "isSnowflakeSharedDatabase": { "description": "Render the guide for a Snowflake shared database.", "type": "boolean", "example": false, "nullable": true } }, "type": "object" }, "StorageName": { "description": "The name of a bucket or a table.\n\n- Allowed characters: `A-Z`, `a-z`, `0-9`, dash `-` and underscore `_`. Anything else \u2014 a\n space, a dot, an accented letter \u2014 is rejected, not transliterated.\n- 1 to 96 characters.\n- Cannot start with an underscore. A dash or a digit as the first character is fine.\n- Registered (external) buckets follow this same rule, dashes included.\n- Uniqueness is case-insensitive within a stage: creating `MyBucket` next to `mybucket`\n fails with `storage.buckets.alreadyExists`, and for tables with\n `storage.buckets.tableAlreadyExists` or `storage.validation.tableAlreadyExists`.\n- To turn arbitrary user input into a name that satisfies this rule, call\n `POST /v2/storage/webalize/display-name` instead of reimplementing the transformation. It\n unaccents the input, replaces every run of disallowed characters with a single `-`, trims\n `-` from both ends, strips leading underscores, and truncates to 96 characters.", "type": "string", "pattern": "^(?!_)[-_A-Za-z0-9]+$", "example": "my-bucket", "maxLength": 96, "minLength": 1 }, "CreateBucketRequest": { "description": "Creates a new bucket in the project.", "required": [ "name" ], "properties": { "name": { "description": "Name of the new bucket.", "type": "string", "example": "my-new-bucket", "allOf": [ { "$ref": "#/components/schemas/StorageName" } ] }, "stage": { "description": "Assigns the bucket to one of the stages.", "type": "string", "example": "in", "default": "in", "enum": [ "in", "out", "sys" ] }, "description": { "description": "Bucket description. **Deprecated**.", "type": "string", "example": "Some Description", "deprecated": true }, "backend": { "description": "Bucket backend type; the default value is determined by the project settings.", "type": "string", "example": "snowflake", "enum": [ "snowflake", "bigquery" ] }, "displayName": { "description": "Display name shown in the UI; can be changed anytime. Defaults to `name`.", "type": "string", "example": "my-new-bucket", "allOf": [ { "$ref": "#/components/schemas/StorageName" } ] }, "color": { "description": "Bucket color. Accepts valid CSS color values (max 20 characters).", "type": "string", "example": "#FF5733", "maxLength": 20 } }, "type": "object" }, "LinkBucketRequest": { "description": "Links a shared bucket from another project. Recognized by the presence of `sourceProjectId`.", "required": [ "name", "sourceProjectId", "sourceBucketId" ], "properties": { "name": { "description": "Name of the linked bucket in this project.", "type": "string", "example": "organizationData", "allOf": [ { "$ref": "#/components/schemas/StorageName" } ] }, "displayName": { "description": "Display name shown in the UI. Defaults to `name`.", "type": "string", "example": "organizationData", "allOf": [ { "$ref": "#/components/schemas/StorageName" } ] }, "sourceProjectId": { "description": "ID of the source project from which the bucket is being shared.", "type": "integer", "example": 123 }, "sourceBucketId": { "description": "ID of the bucket being shared.", "type": "string", "example": "in.c-shared-bucket" }, "stage": { "description": "Assigns the bucket to one of the stages.", "type": "string", "example": "in", "default": "in", "enum": [ "in", "out", "sys" ] } }, "type": "object" }, "BackendConfiguration": { "properties": { "context": { "type": "string", "nullable": true, "minLength": 1 } }, "type": "object" }, "CreateMetadataWithProviderRequest": { "required": [ "provider", "metadata" ], "properties": { "provider": { "description": "Id of the creating component", "type": "string", "example": "test-component" }, "metadata": { "description": "List of metadata items", "type": "array", "items": { "required": [ "key", "value" ], "properties": { "key": { "description": "Metadata key (`a-zA-Z0-9_.-`, max 255 chars)", "type": "string", "example": "some-key" }, "value": { "description": "Metadata value", "type": "string", "example": "Some value", "nullable": true } }, "type": "object" } } }, "type": "object" }, "ActorResponse": { "description": "Who performed the action and through which credential.", "required": [ "type", "id", "name", "adminId" ], "properties": { "type": { "description": "Credential the action came through: a Storage token, a programmatic session, a personal access token, or system work.", "type": "string", "enum": [ "token", "session", "pat", "system" ] }, "id": { "description": "Token id as a string, session or personal access token UUID, or the system subject.", "type": "string" }, "name": { "description": "Token description, the admin email for a session or personal access token, or the system label, as it was when the action happened.", "type": "string" }, "adminId": { "description": "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).", "type": "integer", "format": "int64", "nullable": true } }, "type": "object" }, "BucketForceUnlinkJobResult": { "description": "The bucketForceUnlink job produces no results - the value is always null.", "type": "object", "nullable": true }, "BigQueryBucketListingUpdateJobResponse": { "required": [ "bucketId", "exposureName", "exposureDescription", "bigquery" ], "properties": { "bucketId": { "type": "string" }, "exposureName": { "type": "string" }, "exposureDescription": { "type": "string", "nullable": true }, "bigquery": { "required": [ "listingId", "subscribers" ], "properties": { "listingId": { "type": "string" }, "subscribers": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object" }, "SnowflakeBucketListingUpdateJobResponse": { "required": [ "idBucket", "backend", "snowflake" ], "properties": { "idBucket": { "description": "Identifier of the exposed bucket.", "type": "integer" }, "backend": { "type": "string", "enum": [ "snowflake" ] }, "snowflake": { "required": [ "mode", "added", "removed" ], "properties": { "mode": { "type": "string", "enum": [ "grant", "share" ] }, "grantees": { "description": "The stored grantee roles after the update. Present only in `grant` mode.", "type": "array", "items": { "type": "string" } }, "accounts": { "description": "The stored consumer accounts after the update. Present only in `share` mode.", "type": "array", "items": { "type": "string" } }, "added": { "description": "All members granted by this job: the full new list is re-granted, so this is not a difference against the previous list. Empty when the request sent no member list.", "type": "array", "items": { "type": "string" } }, "removed": { "description": "Members the job revoked access from: every member that may still have held access and is no longer listed, including members left by a failed earlier job.", "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object" }, "BucketListingUpdateJobResponse": { "description": "The result shape depends on the bucket backend.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BigQueryBucketListingUpdateJobResponse" }, { "$ref": "#/components/schemas/SnowflakeBucketListingUpdateJobResponse" } ] }, "BucketUpdateJobResult": { "description": "The bucketUpdate job produces no results - the value is always null.", "type": "object", "nullable": true }, "BigQueryBucketListingCreateJobResult": { "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" }, "SnowflakeBucketListingCreateJobResult": { "required": [ "idBucket", "backend", "mode", "objectName" ], "properties": { "idBucket": { "description": "Identifier of the exposed bucket.", "type": "integer" }, "backend": { "type": "string", "enum": [ "snowflake" ] }, "mode": { "type": "string", "enum": [ "grant", "share" ] }, "objectName": { "description": "Quoted name of the exposed object: `\"\".\"\"` in `grant` mode, the share name in `share` mode.", "type": "string" } }, "type": "object" }, "BucketListingCreateJobResult": { "description": "The result shape depends on the bucket backend.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BigQueryBucketListingCreateJobResult" }, { "$ref": "#/components/schemas/SnowflakeBucketListingCreateJobResult" } ] }, "BucketListingDeleteResponse": { "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", "nullable": true }, "BucketDeleteResponse": { "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", "nullable": true }, "MetadataItemResponse": { "description": "Single metadata record.", "required": [ "id", "key", "value", "provider", "timestamp" ], "properties": { "id": { "description": "Metadata record identifier", "type": "string", "example": "19509" }, "key": { "description": "Metadata key", "type": "string", "example": "some-key" }, "value": { "description": "Metadata value", "type": "string", "example": "Some value", "nullable": true }, "provider": { "description": "Id of the component that created the metadata", "type": "string", "example": "test-component" }, "timestamp": { "description": "When the metadata was created or last updated, ISO 8601 with a `+hhmm` offset", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T23:36:10+0100" } }, "type": "object" }, "SharedBucketResponse": { "description": "Shared bucket as seen from another project (also used as `sourceBucket` of a linked bucket).", "required": [ "id", "name", "displayName", "stage", "description", "sharing", "created", "lastChangeDate", "dataSizeBytes", "rowsCount", "backend", "hasExternalSchema", "databaseName", "path", "project", "color", "owner", "sharedByActor" ], "properties": { "id": { "description": "Bucket identifier in the source project.", "type": "string", "example": "in.c-main" }, "name": { "description": "Bucket name.", "type": "string", "example": "c-main" }, "displayName": { "description": "Bucket display name.", "type": "string", "example": "main" }, "stage": { "description": "Bucket stage.", "type": "string", "example": "in", "enum": [ "in", "out", "sys" ] }, "description": { "description": "Bucket description.", "type": "string", "example": "Organization shared data" }, "sharing": { "description": "Sharing type.", "type": "string", "example": "organization-project", "nullable": true, "enum": [ "organization", "organization-project", "specific-projects", "specific-users", null ] }, "created": { "description": "Creation timestamp, ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2020-01-12T18:28:31+0100" }, "lastChangeDate": { "description": "Timestamp of the last data change, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2020-01-12T18:31:49+0100", "nullable": true }, "dataSizeBytes": { "type": "integer", "example": 1536 }, "rowsCount": { "type": "integer", "example": 32 }, "backend": { "description": "Storage backend of the bucket: `snowflake`, `bigquery` or `postgres` (external buckets); older buckets may carry another backend name.", "type": "string", "example": "snowflake" }, "hasExternalSchema": { "description": "Whether the bucket is an external (registered) bucket.", "type": "boolean", "example": false }, "databaseName": { "description": "Database of a Snowflake external bucket or of a linked bucket's source; `\"\"` otherwise.", "type": "string", "example": "" }, "path": { "description": "Dot-separated path of the bucket on the backend.", "type": "string", "example": "database_name.c-main" }, "project": { "description": "Project owning the bucket.", "required": [ "id", "name" ], "properties": { "id": { "type": "integer", "example": 123 }, "name": { "type": "string", "example": "Project name" } }, "type": "object" }, "color": { "type": "string", "example": null, "nullable": true }, "tables": { "description": "Tables in the shared bucket (filtered aliases are omitted). Absent from a `sourceBucket` inside a table list or search with `include=bucketsWithoutSourceTables`.", "type": "array", "items": { "required": [ "id", "name", "displayName", "path" ], "properties": { "id": { "type": "string", "example": "in.c-main.languages" }, "name": { "type": "string", "example": "languages" }, "displayName": { "type": "string", "example": "languages-display-name" }, "path": { "description": "Internal Storage path of the table (`/{bucket numeric id}-{table name}`); may be `\"\"`.", "type": "string", "example": "/1234-languages" } }, "type": "object" } }, "sharingParameters": { "description": "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.", "oneOf": [ { "properties": { "projects": { "description": "Present when `sharing` is `specific-projects`.", "type": "array", "items": { "required": [ "id", "name" ], "properties": { "id": { "type": "integer", "example": 321 }, "name": { "type": "string", "example": "Some Project" } }, "type": "object" } }, "users": { "description": "Present when `sharing` is `specific-users`.", "type": "array", "items": { "required": [ "id", "name", "email" ], "properties": { "id": { "type": "integer", "example": 5 }, "name": { "type": "string", "example": "Jan Developer" }, "email": { "type": "string", "example": "jan.dev@keboola.com" } }, "type": "object" } } }, "type": "object" }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "sharedBy": { "description": "Token that shared the bucket. Present only when the bucket is shared.", "required": [ "id", "name", "date" ], "properties": { "id": { "type": "integer", "format": "int64", "example": 5, "nullable": true }, "name": { "type": "string", "example": "dev@keboola.com", "nullable": true }, "date": { "description": "ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2020-02-03T14:58:29+0100" } }, "type": "object" }, "sharedByActor": { "description": "Who shared the bucket and through which credential; null when the bucket is not shared or no sharer is recorded.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "owner": { "description": "Bucket owner; `null` when no owner is set.", "required": [ "id", "name", "email" ], "properties": { "id": { "type": "integer", "example": 123 }, "name": { "type": "string", "example": "Jan Developer" }, "email": { "type": "string", "example": "jan.dev@keboola.com" } }, "type": "object", "nullable": true }, "metadata": { "description": "Bucket metadata. Present only on the shared-buckets list with `include` containing `metadata`.", "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } } }, "type": "object" }, "RefreshJobResponse": { "required": [ "uri", "id", "name", "displayName", "idBranch", "stage", "description", "tables", "created", "lastChangeDate", "updated", "isReadOnly", "dataSizeBytes", "rowsCount", "isMaintenance", "backend", "sharing", "hasExternalSchema", "databaseName", "path", "isSnowflakeSharedDatabase", "color", "owner", "sharedByActor", "warnings" ], "properties": { "uri": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "displayName": { "type": "string" }, "idBranch": { "type": "integer" }, "stage": { "type": "string" }, "description": { "type": "string" }, "tables": { "type": "string" }, "created": { "type": "string" }, "lastChangeDate": { "type": "string", "nullable": true }, "updated": { "type": "string", "nullable": true }, "isReadOnly": { "type": "boolean" }, "dataSizeBytes": { "type": "integer" }, "rowsCount": { "type": "integer" }, "isMaintenance": { "type": "boolean" }, "backend": { "type": "string" }, "sharing": { "type": "string", "nullable": true }, "hasExternalSchema": { "type": "boolean" }, "databaseName": { "type": "string" }, "path": { "type": "string" }, "isSnowflakeSharedDatabase": { "type": "boolean" }, "color": { "type": "string", "nullable": true }, "sharingParameters": { "description": "Sharing parameters. Present only when the bucket is shared; `[]` when it is shared with the organization or its projects.", "properties": { "projects": { "description": "Present only when the sharing type is `specific-projects`.", "type": "array", "items": { "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "users": { "description": "Present only when the sharing type is `specific-users`.", "type": "array", "items": { "required": [ "id", "name", "email" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }, "type": "object" } } }, "type": "object" }, "sharedBy": { "description": "Token that shared the bucket. Present only when the bucket is shared.", "required": [ "id", "name", "date" ], "properties": { "id": { "type": "integer", "format": "int64", "nullable": true }, "name": { "type": "string", "nullable": true }, "date": { "type": "string" } }, "type": "object" }, "sharedByActor": { "description": "Who shared the bucket and through which credential; null when the bucket is not shared or no sharer is recorded.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "owner": { "description": "Bucket owner; `null` when no owner is set.", "required": [ "id", "name", "email" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }, "type": "object", "nullable": true }, "sourceBucket": { "$ref": "#/components/schemas/SharedBucketResponse" }, "warnings": { "description": "List of warnings related to the refresh operation.", "type": "array", "items": { "required": [ "message", "context" ], "properties": { "message": { "type": "string" }, "context": { "type": "string", "nullable": true } }, "type": "object" } } }, "type": "object" }, "BatchPurgeJobResult": { "description": "Per-item outcome of a `componentConfigurationsBatchPurge` job. Present on both a successful job and a failed one \u2014 a failed job is one where at least one item is in `failed`, and the items in `purged` are permanently gone.", "required": [ "purged", "failed" ], "properties": { "purged": { "description": "Configurations that were permanently removed. This cannot be undone.", "type": "array", "items": { "required": [ "componentId", "configurationId" ], "properties": { "componentId": { "type": "string", "example": "keboola.ex-db-mysql" }, "configurationId": { "type": "string", "example": "main-1" } }, "type": "object" } }, "failed": { "description": "Configurations that were not purged, each with the reason. The one exception is `storage.components.configurations.batchPurgeItemFailed`, which says the purge did not finish and the configuration may or may not be gone \u2014 re-read the trash to find out.", "type": "array", "items": { "required": [ "componentId", "configurationId", "error" ], "properties": { "componentId": { "type": "string", "example": "keboola.ex-db-mysql" }, "configurationId": { "type": "string", "example": "main-2" }, "error": { "required": [ "code", "message" ], "properties": { "code": { "description": "The string code the single-configuration purge would have returned, e.g. `storage.components.configurations.versionMismatch` when the item's `version` no longer matches. `storage.components.configurations.batchPurgeItemFailed` is the batch's own code for an item that failed outside the purge itself.", "type": "string", "example": "storage.components.configurations.versionMismatch" }, "message": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "type": "object" }, "BatchRestoreJobResult": { "description": "Per-item outcome of a `componentConfigurationsBatchRestore` job. Present on both a successful job and a failed one \u2014 a failed job is one where at least one item is in `failed`.", "required": [ "restored", "failed" ], "properties": { "restored": { "description": "Configurations that are live again.", "type": "array", "items": { "required": [ "componentId", "configurationId", "version" ], "properties": { "componentId": { "type": "string", "example": "keboola.ex-db-mysql" }, "configurationId": { "type": "string", "example": "main-1" }, "version": { "description": "Version the restore made. Restoring is a change, so this is one higher than the version the configuration had in the trash.", "type": "integer", "example": 5 } }, "type": "object" } }, "failed": { "description": "Configurations that were not restored, each with the reason. The one exception is `storage.components.configurations.batchRestoreItemFailed`, which says the restore did not finish and the configuration may or may not be back \u2014 re-read the trash to find out.", "type": "array", "items": { "required": [ "componentId", "configurationId", "error" ], "properties": { "componentId": { "type": "string", "example": "keboola.ex-db-mysql" }, "configurationId": { "type": "string", "example": "main-2" }, "error": { "required": [ "code", "message" ], "properties": { "code": { "description": "The string code the single-configuration restore would have returned, e.g. `storage.configuration.notFound`. `storage.components.configurations.batchRestoreItemFailed` is the batch's own code for an item that failed outside the restore itself.", "type": "string", "example": "storage.configuration.notFound" }, "message": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "type": "object" }, "FileDeleteJobResult": { "description": "The fileDelete job produces no results - the value is always null.", "type": "object", "nullable": true }, "TableSnapshotCreateJobResult": { "required": [ "id", "description", "createdTime", "type", "creatorToken", "uri", "dataFileId" ], "properties": { "id": { "type": "string" }, "description": { "type": "string", "nullable": true }, "createdTime": { "type": "string", "format": "date-time" }, "type": { "type": "string" }, "creatorToken": { "required": [ "id", "description" ], "properties": { "id": { "type": "integer" }, "description": { "type": "string" } }, "type": "object" }, "actor": { "description": "Who created the snapshot. Null only for a snapshot that records no creator; missing in the stored result of a job that finished before the field existed.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "uri": { "type": "string" }, "dataFileId": { "type": "integer" } }, "type": "object" }, "TableDeleteJobResult": { "description": "The deleteTable job produces no results - the value is always an empty array `[]`.", "type": "object" }, "DeleteRowsJobResult": { "description": "Result of the tableRowsDelete job.", "type": "object" }, "TableExportAsyncJobResponse": { "description": "Result of a finished table export job.", "required": [ "file", "cacheHit" ], "properties": { "file": { "description": "Reference to the exported file in File Storage.", "required": [ "id" ], "properties": { "id": { "type": "integer" } }, "type": "object" }, "cacheHit": { "description": "Whether the export was served from a previously exported (cached) file.", "type": "boolean" } }, "type": "object" }, "PrimaryKeyCreateJobResult": { "description": "The tablePrimaryKeyAdd job produces no results - the value is always null.", "type": "object", "nullable": true }, "PrimaryKeyDeleteJobResult": { "description": "The tablePrimaryKeyDelete job produces no results - the value is always null.", "type": "object", "nullable": true }, "TableRestoreResult": { "required": [ "tableId", "mode", "warnings" ], "properties": { "tableId": { "description": "ID of the restored table.", "type": "string", "example": "in.c-sales.orders_restored" }, "mode": { "type": "string", "example": "undropAs", "enum": [ "undrop", "undropAs", "pointInTime" ] }, "warnings": { "description": "What the restore could not bring back, e.g. aliases removed together with the table.", "type": "array", "items": { "type": "string" } } }, "type": "object" }, "TableSwapResult": { "required": [ "tableAStringId", "tableBStringId" ], "properties": { "tableAStringId": { "description": "String id of the source table.", "type": "string", "example": "in.c-main.orders" }, "tableBStringId": { "description": "String id of the target table.", "type": "string", "example": "in.c-main.orders_new" } }, "type": "object" }, "SourceTableResponse": { "required": [ "id", "uri", "project" ], "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" }, "AliasFilterResponse": { "description": "Row filter of a filtered simple alias, as returned by Model_Row_MetadataTable::getAliasFilter().", "required": [ "column", "operator", "values" ], "properties": { "column": { "description": "Filtered column name.", "type": "string" }, "operator": { "description": "Filter operator: `eq` (can be used with multiple values) or `ne`.", "type": "string", "enum": [ "eq", "ne" ] }, "values": { "description": "Values compared against the filtered column.", "type": "array", "items": { "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", "isDescriptionSystemManaged", "timestampType", "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, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "lastImportDate": { "description": "Last import date, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "lastChangeDate": { "description": "Last change date, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "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" }, "isDescriptionSystemManaged": { "description": "Whether the description is managed by the system", "type": "boolean" }, "timestampType": { "description": "How the `_timestamp` column is managed", "type": "string", "enum": [ "MANAGED", "SELFMANAGED", "NONE" ] }, "tableType": { "description": "Table type", "type": "string" }, "path": { "description": "Table path", "type": "string" }, "columns": { "description": "List of column names.", "type": "array", "items": { "type": "string" } }, "sourceTable": { "$ref": "#/components/schemas/SourceTableResponse" }, "aliasColumnsAutoSync": { "description": "Alias columns auto sync. Present only for simple aliases.", "type": "boolean" }, "aliasFilter": { "$ref": "#/components/schemas/AliasFilterResponse" }, "selectSql": { "description": "Custom SQL of the alias. Present only for custom SQL aliases.", "type": "string" }, "isPersisted": { "description": "Whether the alias is persisted as a table in the backend. Present only for aliases.", "type": "boolean" } }, "type": "object" }, "TableUpdateJobResult": { "description": "The tableUpdate job produces no results - the value is always null.", "type": "object", "nullable": true }, "ColumnCreateJobResult": { "description": "The tableColumnAdd job produces no results - the value is always null.", "type": "object", "nullable": true }, "ColumnDeleteJobResult": { "description": "The tableColumnDelete job produces no results - the value is always null.", "type": "object", "nullable": true }, "TableExportJobResponse": { "required": [ "file" ], "properties": { "file": { "required": [ "id" ], "properties": { "id": { "type": "integer" } }, "type": "object" } }, "type": "object" }, "JobResponse": { "description": "Response object for an asynchronous storage job.", "required": [ "id", "status", "url", "tableId", "operationName", "operationParams", "createdTime", "startTime", "endTime", "runId", "results", "creatorToken", "actor", "metrics" ], "properties": { "id": { "description": "Job ID.", "type": "string" }, "status": { "description": "Current status of the job.", "type": "string" }, "url": { "description": "API detail URL for the job.", "type": "string" }, "tableId": { "description": "ID of the table affected by the job.", "type": "string", "nullable": true }, "operationName": { "description": "Type of operation performed.", "type": "string" }, "operationParams": { "description": "Parameters for the operation.", "type": "object" }, "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 end timestamp.", "type": "string", "format": "date-time", "nullable": true }, "runId": { "description": "Run ID for the job.", "type": "string", "nullable": true }, "results": { "description": "Job results for the operation once it completes.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/BucketForceUnlinkJobResult" }, { "$ref": "#/components/schemas/BucketListingUpdateJobResponse" }, { "$ref": "#/components/schemas/BucketUpdateJobResult" }, { "$ref": "#/components/schemas/BucketListingCreateJobResult" }, { "$ref": "#/components/schemas/BucketListingDeleteResponse" }, { "$ref": "#/components/schemas/BucketDeleteResponse" }, { "$ref": "#/components/schemas/RefreshJobResponse" }, { "$ref": "#/components/schemas/BatchPurgeJobResult" }, { "$ref": "#/components/schemas/BatchRestoreJobResult" }, { "$ref": "#/components/schemas/FileDeleteJobResult" }, { "$ref": "#/components/schemas/TableSnapshotCreateJobResult" }, { "$ref": "#/components/schemas/TableDeleteJobResult" }, { "$ref": "#/components/schemas/DeleteRowsJobResult" }, { "$ref": "#/components/schemas/TableExportAsyncJobResponse" }, { "$ref": "#/components/schemas/PrimaryKeyCreateJobResult" }, { "$ref": "#/components/schemas/PrimaryKeyDeleteJobResult" }, { "$ref": "#/components/schemas/TableRestoreResult" }, { "$ref": "#/components/schemas/TableSwapResult" }, { "$ref": "#/components/schemas/TableCreateResponse" }, { "$ref": "#/components/schemas/TableUpdateJobResult" }, { "$ref": "#/components/schemas/ColumnCreateJobResult" }, { "$ref": "#/components/schemas/ColumnDeleteJobResult" }, { "$ref": "#/components/schemas/TableExportJobResponse" } ] }, "creatorToken": { "description": "Storage token the job runs as. Use `actor` to learn who created the job.", "required": [ "id", "description" ], "properties": { "id": { "description": "Access token ID as a string, kept for compatibility. Null for a job that runs without a token row.", "type": "string", "nullable": true }, "description": { "description": "Access token description.", "type": "string", "nullable": true } }, "type": "object" }, "actor": { "description": "Who created the job. Null only for a job that records no creator.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "metrics": { "description": "Job metrics.", "required": [ "inCompressed", "inBytes", "inBytesUncompressed", "outCompressed", "outBytes", "outBytesUncompressed" ], "properties": { "inCompressed": { "description": "Input is compressed.", "type": "boolean" }, "inBytes": { "description": "Input bytes.", "type": "integer" }, "inBytesUncompressed": { "description": "Input bytes uncompressed.", "type": "integer" }, "outCompressed": { "description": "Output is compressed.", "type": "boolean" }, "outBytes": { "description": "Output bytes.", "type": "integer" }, "outBytesUncompressed": { "description": "Output bytes uncompressed.", "type": "integer" } }, "type": "object" }, "error": { "description": "Error details. Present only when the job failed.", "required": [ "code", "message", "exceptionId", "contextParams", "uuid" ], "properties": { "code": { "description": "Error code.", "type": "string" }, "message": { "description": "Error message.", "type": "string" }, "exceptionId": { "description": "Exception identifier.", "type": "string" }, "contextParams": { "description": "Context parameters for the error.", "type": "object", "nullable": true }, "uuid": { "description": "Error UUID.", "type": "string", "nullable": true } }, "type": "object" } }, "type": "object", "example": { "id": "22077337", "status": "waiting", "url": "https://connection.keboola.com/v2/storage/jobs/22077337", "tableId": null, "operationName": "workspaceLoad", "operationParams": { "workspaceId": "78423", "preserve": false, "input": [ { "source": "in.c-application-testing.cashier-data", "destination": "my-table" } ], "queue": "main_fast" }, "createdTime": "2017-02-13T16:41:18+0100", "startTime": null, "endTime": null, "runId": null, "results": null, "creatorToken": { "id": "27978", "description": "john.doe@keboola.com" }, "actor": { "type": "token", "id": "27978", "name": "john.doe@keboola.com", "adminId": 1234 }, "metrics": { "inCompressed": false, "inBytes": 0, "inBytesUncompressed": 0, "outCompressed": false, "outBytes": 0, "outBytesUncompressed": 0 } } }, "BackendConfigurationJobParams": { "properties": { "context": { "description": "Present only when the `X-KBC-Backend` header sets a context.", "type": "string", "default": null } }, "type": "object" }, "BucketDeleteJobParams": { "required": [ "idBucket", "force", "backendConfiguration" ], "properties": { "idBucket": { "type": "integer" }, "force": { "type": "boolean" }, "backendConfiguration": { "oneOf": [ { "$ref": "#/components/schemas/BackendConfigurationJobParams" } ], "default": null } }, "type": "object" }, "BackendConfigurationRequest": { "properties": { "context": { "type": "string", "nullable": true, "minLength": 1 } }, "type": "object" }, "BucketDetailRequest": { "properties": { "include": { "description": "Comma-separated list of resources to include for each table: `metadata` (table metadata), `columns` (table columns), `columnMetadata` (column metadata), `sourceMetadata` (for alias tables, source table metadata in `sourceTable.metadata`; works across projects for linked buckets), `sourceColumnMetadata` (for alias tables, source column metadata in `sourceTable.columnMetadata`).", "type": "string", "example": "columns,metadata", "nullable": true } }, "type": "object" }, "BucketEventsListRequest": { "description": "Query parameters for listing bucket events.", "properties": { "limit": { "description": "Maximum number of events to return.", "type": "integer", "nullable": true }, "offset": { "description": "Number of events to skip.", "type": "integer", "nullable": true }, "maxId": { "description": "Only include events with ID less than or equal to this value.", "type": "string", "nullable": true }, "sinceId": { "description": "Only include events with ID greater than this value.", "type": "string", "nullable": true }, "component": { "description": "Filter events by component.", "type": "string", "nullable": true }, "configurationId": { "description": "Filter events by configuration ID.", "type": "string", "nullable": true }, "runId": { "description": "Filter events by run ID.", "type": "string", "nullable": true }, "q": { "description": "Full-text search query to filter event data.", "type": "string", "nullable": true }, "query": { "description": "Deprecated alias of the q parameter.", "type": "string", "nullable": true, "deprecated": true }, "sortOrder": { "description": "Sort order of events. Use \"asc\" for oldest first or \"desc\" for newest first.", "type": "string", "nullable": true, "enum": [ "asc", "desc" ] } }, "type": "object" }, "BucketForceUnlinkJobParams": { "required": [ "linkedIdProject", "linkedIdBucket" ], "properties": { "linkedIdProject": { "type": "integer" }, "linkedIdBucket": { "type": "integer" } }, "type": "object" }, "BucketGetTablesRequest": { "properties": { "include": { "description": "Comma-separated list of data to include. Allowed values: attributes, buckets, bucketsWithoutSourceTables, columns, metadata, columnMetadata, sourceMetadata, sourceColumnMetadata.", "type": "string", "nullable": true } }, "type": "object" }, "BucketOwnerUpdateRequest": { "description": "Exactly one of `id` or `email` must be provided.", "properties": { "id": { "description": "Project admin ID of the new owner. Mutually exclusive with `email`.", "type": "integer", "example": 123, "nullable": true }, "email": { "description": "Project admin email of the new owner. Mutually exclusive with `id`.", "type": "string", "format": "email", "example": "dev@keboola.com", "nullable": true } }, "type": "object", "oneOf": [ { "required": [ "id" ] }, { "required": [ "email" ] } ] }, "BucketUpdateJobParamsValues": { "description": "Bucket properties to update, as stored in the job operation params.", "required": [ "displayName", "color", "deleteColor" ], "properties": { "displayName": { "description": "New display name; null when not changed.", "type": "string", "nullable": true }, "color": { "description": "New CSS color code; null when not changed or when `deleteColor` is true.", "type": "string", "nullable": true }, "deleteColor": { "description": "Whether the color should be removed (an explicit `null` color was sent).", "type": "boolean" } }, "type": "object" }, "BucketUpdateJobParams": { "required": [ "values" ], "properties": { "values": { "$ref": "#/components/schemas/BucketUpdateJobParamsValues" }, "idBucket": { "type": "integer", "nullable": true, "default": null } }, "type": "object" }, "BucketResponse": { "description": "Bucket object.", "required": [ "uri", "id", "name", "displayName", "idBranch", "stage", "description", "tables", "created", "lastChangeDate", "updated", "isReadOnly", "dataSizeBytes", "rowsCount", "isMaintenance", "backend", "sharing", "hasExternalSchema", "databaseName", "path", "isSnowflakeSharedDatabase", "isLinkedBucket", "color", "bucketSharingAllowed", "owner", "sharedByActor", "backendPath" ], "properties": { "uri": { "description": "API URI of the bucket.", "type": "string", "example": "https://connection.keboola.com/v2/storage/buckets/in.c-my-new-bucket" }, "id": { "description": "Bucket identifier (`{stage}.{name}`).", "type": "string", "example": "in.c-my-new-bucket" }, "name": { "description": "Bucket name (prefixed with `c-`).", "type": "string", "example": "c-my-new-bucket" }, "displayName": { "description": "Human-readable display name shown in the UI.", "type": "string", "example": "my-new-bucket" }, "idBranch": { "description": "ID of the branch the bucket belongs to.", "type": "integer", "example": 1234 }, "stage": { "description": "Bucket stage.", "type": "string", "example": "in", "enum": [ "in", "out", "sys" ] }, "description": { "description": "Bucket description.", "type": "string", "example": "Some Description" }, "tables": { "description": "The same URI as `uri`, kept for backward compatibility.", "type": "string", "example": "https://connection.keboola.com/v2/storage/buckets/in.c-my-new-bucket" }, "created": { "description": "Creation timestamp, ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2017-02-13T12:01:05+0100" }, "lastChangeDate": { "description": "Timestamp of the last data change in the bucket, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": null, "nullable": true }, "updated": { "description": "Timestamp of the last bucket update, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2024-11-28T13:03:13+0100", "nullable": true }, "isReadOnly": { "description": "Whether the bucket is read-only (linked or external buckets).", "type": "boolean", "example": false }, "dataSizeBytes": { "description": "Total data size in bytes.", "type": "integer", "example": 0 }, "rowsCount": { "description": "Total number of rows.", "type": "integer", "example": 0 }, "isMaintenance": { "description": "Whether the bucket is in maintenance mode.", "type": "boolean", "example": false }, "backend": { "description": "Storage backend of the bucket: `snowflake`, `bigquery` or `postgres` (external buckets); older buckets may carry another backend name.", "type": "string", "example": "snowflake" }, "sharing": { "description": "Sharing type of the bucket; `null` when the bucket is not shared.", "type": "string", "example": null, "nullable": true, "enum": [ "organization", "organization-project", "specific-projects", "specific-users", null ] }, "hasExternalSchema": { "description": "Whether the bucket is an external (registered) bucket.", "type": "boolean", "example": false }, "databaseName": { "description": "Database of a Snowflake external bucket or of a linked bucket's source; `\"\"` otherwise.", "type": "string", "example": "" }, "path": { "description": "Dot-separated path of the bucket on the backend.", "type": "string", "example": "database_name.c-my-new-bucket" }, "isSnowflakeSharedDatabase": { "description": "Whether the external bucket uses a Snowflake Secure Data Share.", "type": "boolean", "example": false }, "isLinkedBucket": { "description": "Whether this bucket is linked from another project.", "type": "boolean", "example": false }, "color": { "description": "CSS color of the bucket.", "type": "string", "example": null, "nullable": true }, "bucketSharingAllowed": { "description": "Whether the bucket can be shared.", "type": "boolean", "example": true }, "sharingParameters": { "description": "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.", "oneOf": [ { "properties": { "projects": { "description": "Present when `sharing` is `specific-projects`.", "type": "array", "items": { "required": [ "id", "name" ], "properties": { "id": { "type": "integer", "example": 321 }, "name": { "type": "string", "example": "Some Project" } }, "type": "object" } }, "users": { "description": "Present when `sharing` is `specific-users`.", "type": "array", "items": { "required": [ "id", "name", "email" ], "properties": { "id": { "type": "integer", "example": 5 }, "name": { "type": "string", "example": "Jan Developer" }, "email": { "type": "string", "example": "jan.dev@keboola.com" } }, "type": "object" } } }, "type": "object" }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "sharedBy": { "description": "Token that shared the bucket. Present only when the bucket is shared.", "required": [ "id", "name", "date" ], "properties": { "id": { "type": "integer", "format": "int64", "example": 5, "nullable": true }, "name": { "type": "string", "example": "dev@keboola.com", "nullable": true }, "date": { "description": "ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2020-02-03T14:58:29+0100" } }, "type": "object" }, "sharedByActor": { "description": "Who shared the bucket and through which credential; null when the bucket is not shared or no sharer is recorded.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "owner": { "description": "Bucket owner; `null` when no owner is set.", "required": [ "id", "name", "email" ], "properties": { "id": { "type": "integer", "example": 123 }, "name": { "type": "string", "example": "Jan Developer" }, "email": { "type": "string", "example": "jan.dev@keboola.com" } }, "type": "object", "nullable": true }, "sourceBucket": { "$ref": "#/components/schemas/SharedBucketResponse" }, "backendPath": { "description": "Full path of the bucket on the backend (e.g. database and schema); `[]` on backends without one.", "type": "array", "items": { "type": "string" }, "example": [ "KBC_PRJ_123", "in.c-my-new-bucket" ] } }, "type": "object" }, "BucketUpdateResponse": { "description": "The bucket as it looks after the synchronous update.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BucketResponse" } ] }, "UpdateBucketRequest": { "properties": { "displayName": { "description": "New human-readable display name.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/StorageName" } ] }, "color": { "description": "New CSS color code of the bucket (e.g. `#FF5733`, `red`, `rgb(255, 0, 0)`). Pass null to remove the color.", "type": "string", "nullable": true, "maxLength": 20 } }, "type": "object" }, "ListBucketsRequest": { "type": "object" }, "AliasCreateJobResult": { "description": "Detail of the created alias table, including a flat list of its column names.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TableCreateResponse" }, { "required": [ "columns" ], "properties": { "columns": { "description": "Names of the columns exposed by the alias.", "type": "array", "items": { "type": "string" } } } } ] }, "WhereFilterJobParams": { "required": [ "column" ], "properties": { "column": { "type": "string", "default": null }, "operator": { "description": "Present only when `values` is.", "type": "string", "default": null }, "values": { "description": "Present only when the request sent filter values.", "type": "array", "items": { "type": "string" }, "default": null } }, "type": "object" }, "AliasCreateJobParams": { "required": [ "sourceTable", "name" ], "properties": { "sourceTable": { "type": "string" }, "name": { "type": "string" }, "idBucket": { "type": "integer", "nullable": true, "default": null }, "aliasFilter": { "description": "Present only when the request sent a non-empty filter.", "oneOf": [ { "$ref": "#/components/schemas/WhereFilterJobParams" } ], "default": null }, "aliasColumns": { "description": "Present only when the request sent `aliasColumns`.", "type": "array", "items": { "type": "string" }, "default": null } }, "type": "object" }, "CreateTableAliasResponse": { "description": "Detail of the created alias table together with the bucket it was created in.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AliasCreateJobResult" }, { "properties": { "bucket": { "$ref": "#/components/schemas/BucketResponse" } } } ] }, "CreateTableAliasRequest": { "description": "Request body of POST /buckets/{bucket_id}/table-aliases.", "required": [ "sourceTable" ], "properties": { "sourceTable": { "description": "Id of the table the alias reads from (e.g. `in.c-main.users`).", "type": "string" }, "name": { "description": "Name of the new alias table. Defaults to the source table name.", "type": "string", "nullable": true }, "aliasColumns": { "description": "Columns exposed by the alias. When omitted the alias mirrors all source columns and keeps them in sync.", "type": "array", "items": { "type": "string" }, "nullable": true }, "aliasColumnsAutosync": { "description": "Deprecated and ignored - auto-sync is derived from whether aliasColumns is given.", "type": "boolean", "nullable": true, "deprecated": true }, "aliasFilter": { "description": "Restricts the alias to rows matching a single column filter.", "properties": { "column": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } }, "operator": { "type": "string", "default": "eq", "enum": [ "eq", "ne" ] } }, "type": "object", "nullable": true } }, "type": "object" }, "TableCreateJobParamsSource": { "description": "Source of the created table, as stored in the job operation params.", "required": [ "type" ], "properties": { "type": { "description": "Kind of source the table is created from.", "type": "string", "enum": [ "file", "snapshot", "workspace", "timeTravel" ] }, "fileId": { "description": "Source file ID. Present when `type` is `file`.", "type": "string" }, "snapshotId": { "description": "Source snapshot ID. Present when `type` is `snapshot`.", "type": "string" }, "tableName": { "description": "Source workspace table/object name; duplicates `dataObject` for backward compatibility. Present when `type` is `workspace`.", "type": "string" }, "dataObject": { "description": "Source workspace table/object name. Present when `type` is `workspace`.", "type": "string" }, "workspaceId": { "description": "Source workspace ID. Present when `type` is `workspace`.", "type": "integer" }, "timestamp": { "description": "Point in time to travel to. Present when `type` is `timeTravel`.", "type": "string" }, "destinationTableName": { "description": "Name of the table being created. Present when `type` is `timeTravel`.", "type": "string" }, "sourceTableId": { "description": "Source table ID the time travel is taken from. Present when `type` is `timeTravel`.", "type": "string" } }, "type": "object" }, "TableCreateJobParams": { "required": [ "source", "params", "backendConfiguration" ], "properties": { "source": { "$ref": "#/components/schemas/TableCreateJobParamsSource" }, "params": { "type": "object", "additionalProperties": {} }, "backendConfiguration": { "oneOf": [ { "$ref": "#/components/schemas/BackendConfigurationJobParams" } ], "default": null }, "idBucket": { "type": "integer", "nullable": true, "default": null } }, "type": "object" }, "CreateTableAsyncFromFileRequest": { "description": "Request body for creating a table from a file. Some parameters are optional or only used for specific backends.", "required": [ "dataFileId", "name" ], "properties": { "dataFileId": { "description": "ID of the source data file.", "type": "integer" }, "name": { "description": "Name of the new table.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/StorageName" } ] }, "delimiter": { "description": "CSV delimiter character.", "type": "string", "nullable": true }, "enclosure": { "description": "CSV enclosure character.", "type": "string", "nullable": true }, "escapedBy": { "description": "CSV escape character.", "type": "string", "nullable": true }, "primaryKey": { "description": "Comma-separated primary key column names.", "type": "string", "example": "id,name" }, "columns": { "description": "List of table columns (optional, only for file workspace).", "type": "array", "items": { "type": "string" }, "nullable": true }, "distributionKey": { "description": "Comma-separated distribution key column names (for Synapse).", "type": "string", "example": "id" }, "timestampType": { "description": "Type of internal timestamp column only MANAGED value now supported, meaning that _timestamp column managed by storage is created.", "type": "string", "nullable": true, "default": "MANAGED" } }, "type": "object" }, "CreateTableAsyncFromSnapshotRequest": { "description": "Request body for creating a table from a snapshot. Some parameters are optional or only used for specific backends.", "required": [ "snapshotId", "name" ], "properties": { "snapshotId": { "description": "ID of the source snapshot.", "type": "integer" }, "name": { "description": "Name of the new table.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/StorageName" } ] }, "delimiter": { "description": "CSV delimiter character.", "type": "string", "nullable": true }, "enclosure": { "description": "CSV enclosure character.", "type": "string", "nullable": true }, "escapedBy": { "description": "CSV escape character.", "type": "string", "nullable": true }, "primaryKey": { "description": "Comma-separated primary key column names.", "type": "string", "example": "id,name" }, "columns": { "description": "List of table columns (optional, only for file workspace).", "type": "array", "items": { "type": "string" }, "nullable": true }, "distributionKey": { "description": "Comma-separated distribution key column names (for Synapse).", "type": "string", "example": "id" }, "timestampType": { "description": "Type of internal timestamp column only MANAGED value now supported, meaning that _timestamp column managed by storage is created.", "type": "string", "nullable": true, "default": "MANAGED" } }, "type": "object" }, "CreateTableAsyncFromTimeTravelRequest": { "description": "Request body for creating a table from a time travel source. Some parameters are optional or only used for specific backends.", "required": [ "sourceTableId", "name", "timestamp" ], "properties": { "sourceTableId": { "description": "ID of the source table for time travel.", "type": "string" }, "name": { "description": "Name of the new table.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/StorageName" } ] }, "timestamp": { "description": "Timestamp for time travel (ISO8601 or unix timestamp).", "type": "string" }, "delimiter": { "description": "CSV delimiter character.", "type": "string", "nullable": true }, "enclosure": { "description": "CSV enclosure character.", "type": "string", "nullable": true }, "escapedBy": { "description": "CSV escape character.", "type": "string", "nullable": true }, "primaryKey": { "description": "Comma-separated primary key column names.", "type": "string", "example": "id,name" }, "columns": { "description": "List of table columns (optional, only for file workspace).", "type": "array", "items": { "type": "string" }, "nullable": true }, "distributionKey": { "description": "Comma-separated distribution key column names (for Synapse).", "type": "string", "example": "id" }, "timestampType": { "description": "Type of internal timestamp column only MANAGED value now supported, meaning that _timestamp column managed by storage is created.", "type": "string", "nullable": true, "default": "MANAGED" } }, "type": "object" }, "CreateTableAsyncFromWorkspaceRequest": { "description": "Request body for creating a table from a workspace. Some parameters are optional or only used for specific backends.", "required": [ "dataWorkspaceId", "name" ], "properties": { "dataWorkspaceId": { "description": "ID of the source workspace.", "type": "integer" }, "dataObject": { "description": "Name of the object in the workspace (table, file, etc).", "type": "string", "nullable": true }, "dataTableName": { "description": "Deprecated: use dataObject. Name of the table in the workspace.", "type": "string", "nullable": true }, "name": { "description": "Name of the new table.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/StorageName" } ] }, "delimiter": { "description": "CSV delimiter character.", "type": "string", "nullable": true }, "enclosure": { "description": "CSV enclosure character.", "type": "string", "nullable": true }, "escapedBy": { "description": "CSV escape character.", "type": "string", "nullable": true }, "primaryKey": { "description": "Comma-separated primary key column names.", "type": "string", "example": "id,name" }, "columns": { "description": "List of table columns (optional, only for file workspace).", "type": "array", "items": { "type": "string" }, "nullable": true }, "distributionKey": { "description": "Comma-separated distribution key column names (for Synapse).", "type": "string", "example": "id" }, "timestampType": { "description": "Type of internal timestamp column only MANAGED value now supported, meaning that _timestamp column managed by storage is created.", "type": "string", "nullable": true, "default": "MANAGED" } }, "type": "object" }, "TableDefinitionCreateColumnObject": { "description": "A single column definition, as stored in the job operation params.", "required": [ "name", "definition" ], "properties": { "name": { "description": "Name of the column.", "type": "string" }, "definition": { "description": "Native column definition; always carries `nullable`. Its `type` is mutually exclusive with `basetype`.", "required": [ "nullable" ], "properties": { "type": { "description": "Backend-native column type. Present only when the column has a native type.", "type": "string" }, "length": { "description": "Length of the column type, e.g. `38,9` for a numeric type. Present only when sent.", "type": "string", "nullable": true }, "nullable": { "description": "Whether the column is nullable.", "type": "boolean", "default": true }, "default": { "description": "Default value of the column. Present only when sent.", "type": "string", "nullable": true }, "description": { "description": "Column description, stored as column metadata. Present only when sent.", "type": "string", "nullable": true } }, "type": "object" }, "basetype": { "description": "Keboola base type of the column. Mutually exclusive with `definition.type`. Present only when sent.", "type": "string" } }, "type": "object" }, "TableDefinitionTimePartitioningObject": { "description": "Time based partitioning configuration, as stored in the job operation params.", "required": [ "type" ], "properties": { "type": { "description": "Type of the time partitioning, e.g. `DAY`.", "type": "string" }, "field": { "description": "Column used for the time partitioning. Present only when sent; absent when the table is partitioned by ingestion time.", "type": "string" }, "expirationMs": { "description": "Number of milliseconds for which to keep the storage for a partition. Present only when sent.", "type": "string" } }, "type": "object" }, "TableDefinitionRangePartitioningObject": { "description": "Integer range partitioning configuration, as stored in the job operation params.", "required": [ "field", "range" ], "properties": { "field": { "description": "Column used for the range partitioning.", "type": "string" }, "range": { "description": "Definition of the ranges.", "required": [ "start", "end", "interval" ], "properties": { "start": { "description": "Start of the range, inclusive.", "type": "string" }, "end": { "description": "End of the range, exclusive.", "type": "string" }, "interval": { "description": "Width of each interval.", "type": "string" } }, "type": "object" } }, "type": "object" }, "TableDefinitionClusteringObject": { "description": "Clustering configuration, as stored in the job operation params.", "required": [ "fields" ], "properties": { "fields": { "description": "Columns used for the clustering.", "type": "array", "items": { "type": "string" } } }, "type": "object" }, "TableDefinitionCreateSourceObject": { "description": "Source table the new table definition is created from.", "required": [ "tableId" ], "properties": { "tableId": { "description": "Identifier of the source table.", "type": "string", "example": "in.c-main.users" }, "branchId": { "description": "Branch the source table is read from. Present only when the request named a branch; absent means the current branch.", "type": "integer" } }, "type": "object" }, "TableDefinitionCreateJobParams": { "required": [ "name", "primaryKeysNames", "columns", "isDescriptionSystemManaged", "timestampType", "backendConfiguration" ], "properties": { "name": { "type": "string" }, "primaryKeysNames": { "type": "array", "items": { "type": "string" } }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/TableDefinitionCreateColumnObject" } }, "idBucket": { "type": "integer", "nullable": true, "default": null }, "description": { "description": "Present only when the request sent a description.", "type": "string", "default": null }, "isDescriptionSystemManaged": { "type": "boolean", "default": null }, "timestampType": { "type": "string", "default": null }, "timePartitioning": { "$ref": "#/components/schemas/TableDefinitionTimePartitioningObject" }, "rangePartitioning": { "$ref": "#/components/schemas/TableDefinitionRangePartitioningObject" }, "clustering": { "$ref": "#/components/schemas/TableDefinitionClusteringObject" }, "requirePartitionFilter": { "description": "Present only for a BigQuery table.", "type": "boolean", "default": null }, "source": { "$ref": "#/components/schemas/TableDefinitionCreateSourceObject" }, "backendConfiguration": { "oneOf": [ { "$ref": "#/components/schemas/BackendConfigurationJobParams" } ], "default": null } }, "type": "object" }, "StorageColumnName": { "description": "The name of a table column.\n\n- Allowed characters: `A-Z`, `a-z`, `0-9` and underscore `_`. Unlike a bucket or table name,\n a column name may **not** contain a dash.\n- 1 to 64 characters.\n- Must start with a letter or a digit.\n- To turn arbitrary user input into a name that satisfies this rule, call\n `POST /v2/storage/webalize/column-names` instead of reimplementing the transformation. In\n order, it strips emoji, transliterates the rest to ASCII, replaces every run of disallowed\n characters with a single `_`, trims `_` from both ends, truncates to 64 characters, and\n strips any leading `_` the truncation left behind. Input with no usable character left\n webalizes to an empty string, which is *not* a valid column name.\n- `POST /v2/storage/validate/column-names` applies one rule the creation endpoints do not:\n it also rejects the backend system columns `oid`, `tableoid`, `xmin`, `cmin`, `xmax`,\n `cmax` and `ctid`.", "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_]*$", "example": "created_at", "maxLength": 64, "minLength": 1 }, "SnowflakeCreateTableDefinitionRequest": { "required": [ "name", "columns" ], "properties": { "name": { "description": "Name of the new table. Required.", "type": "string" }, "description": { "description": "Optional description of the table stored as table metadata.", "type": "string", "nullable": true }, "isDescriptionSystemManaged": { "description": "Whether the table description is managed by the system (true, default) or the user (false).", "type": "boolean", "default": true }, "source": { "description": "Not supported on Snowflake. Creating a table from a source is BigQuery only; supplying it on Snowflake is rejected.", "required": [ "tableId" ], "properties": { "tableId": { "description": "Storage table ID. Required when source is supplied.", "type": "string" }, "branchId": { "description": "Optional branch ID.", "type": "integer", "nullable": true } }, "type": "object", "nullable": true }, "primaryKeysNames": { "description": "Optional list of column names forming the primary key. Each column must be included in the table definition and must not be nullable.", "type": "array", "items": { "type": "string" } }, "timestampType": { "description": "Optional type of the _timestamp column handling. MANAGED adds a platform managed _timestamp column, NONE creates the table without it.", "type": "string", "default": "MANAGED", "enum": [ "MANAGED", "NONE" ] }, "columns": { "description": "List of table columns. At least one column is required.", "type": "array", "items": { "required": [ "name" ], "properties": { "name": { "description": "Name of the column. Required.", "allOf": [ { "$ref": "#/components/schemas/StorageColumnName" } ] }, "definition": { "description": "Optional native column definition. Mutually exclusive with basetype.", "properties": { "type": { "description": "Snowflake native column type. Optional, defaults to VARCHAR.", "type": "string" }, "length": { "description": "Optional length of the column type, for example \"38,0\" for NUMBER.", "type": "string", "nullable": true }, "nullable": { "description": "Optional flag whether the column is nullable. Primary key columns must not be nullable.", "type": "boolean", "default": true }, "default": { "description": "Optional default value of the column.", "type": "string", "nullable": true }, "description": { "description": "Optional description of the column stored as column metadata.", "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "basetype": { "description": "Optional Keboola base type of the column. Mutually exclusive with definition type.", "type": "string", "nullable": true } }, "type": "object" } } }, "type": "object" }, "BigqueryCreateTableDefinitionRequest": { "required": [ "name" ], "properties": { "name": { "description": "Name of the new table. Required.", "type": "string" }, "description": { "description": "Optional description of the table stored as table metadata.", "type": "string", "nullable": true }, "isDescriptionSystemManaged": { "description": "Whether the table description is managed by the system (true, default) or the user (false).", "type": "boolean", "default": true }, "source": { "description": "Optional source object to create the new table from by copying the source data into the requested partition/clustering layout. BigQuery only. The column definition is derived from the source table, so `columns` must not be supplied together with `source`. Aliases and linked-bucket source tables are supported.", "required": [ "tableId" ], "properties": { "tableId": { "description": "Storage table ID (e.g. \"in.c-main.events\") to copy the new table from. Required.", "type": "string" }, "branchId": { "description": "Optional ID of the branch the source table is resolved in. Defaults to the current branch. The caller must be allowed to read the source table in that branch.", "type": "integer", "nullable": true } }, "type": "object", "nullable": true }, "primaryKeysNames": { "description": "Optional list of column names forming the primary key. Each column must be included in the table definition and must not be nullable.", "type": "array", "items": { "type": "string" } }, "timestampType": { "description": "Optional type of the _timestamp column handling. MANAGED adds a platform managed _timestamp column, NONE creates the table without it. Ignored when `source` is set: the new table inherits the source table's _timestamp handling so the copied data lines up.", "type": "string", "default": "MANAGED", "enum": [ "MANAGED", "NONE" ] }, "columns": { "description": "List of table columns. Required unless `source` is set; must not be supplied together with `source` (the column definition is then derived from the source table).", "type": "array", "items": { "required": [ "name" ], "properties": { "name": { "description": "Name of the column. Required.", "allOf": [ { "$ref": "#/components/schemas/StorageColumnName" } ] }, "definition": { "description": "Optional native column definition. Mutually exclusive with basetype.", "properties": { "type": { "description": "BigQuery native column type. Optional, defaults to STRING.", "type": "string" }, "length": { "description": "Optional length of the column type, for example \"38,9\" for NUMERIC.", "type": "string", "nullable": true }, "nullable": { "description": "Optional flag whether the column is nullable. Primary key columns must not be nullable.", "type": "boolean", "default": true }, "default": { "description": "Optional default value of the column.", "type": "string", "nullable": true }, "description": { "description": "Optional description of the column stored as column metadata.", "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "basetype": { "description": "Optional Keboola base type of the column. Mutually exclusive with definition type.", "type": "string", "nullable": true } }, "type": "object" } }, "timePartitioning": { "description": "Optional time based partitioning configuration. Mutually exclusive with rangePartitioning.", "required": [ "type" ], "properties": { "type": { "description": "Type of the time partitioning, for example DAY. Required.", "type": "string" }, "field": { "description": "Optional column used for the time partitioning. The column must be included in the table definition. If not set, the table is partitioned by ingestion time.", "type": "string", "nullable": true }, "expirationMs": { "description": "Optional number of milliseconds for which to keep the storage for a partition.", "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "rangePartitioning": { "description": "Optional integer range partitioning configuration. Mutually exclusive with timePartitioning.", "required": [ "field", "range" ], "properties": { "field": { "description": "Column used for the range partitioning. The column must be included in the table definition. Required.", "type": "string" }, "range": { "description": "Definition of the ranges. Required.", "required": [ "start", "end", "interval" ], "properties": { "start": { "description": "Start of the range partitioning, inclusive. Required.", "type": "string" }, "end": { "description": "End of the range partitioning, exclusive. Required.", "type": "string" }, "interval": { "description": "Width of each interval. Required.", "type": "string" } }, "type": "object" } }, "type": "object", "nullable": true }, "clustering": { "description": "Optional clustering configuration.", "required": [ "fields" ], "properties": { "fields": { "description": "One or more columns used for the clustering. Required.", "type": "array", "items": { "type": "string" } } }, "type": "object", "nullable": true } }, "type": "object" }, "BigQueryListingSection": { "required": [ "listingId", "subscribers" ], "properties": { "listingId": { "description": "GCP listing ID (letters, digits and underscores; unique within the exchange).", "type": "string" }, "subscribers": { "description": "IAM principals, each prefixed with \"user:\" or \"group:\" (e.g. \"user:a@b.com\").", "type": "array", "items": { "type": "string" } } }, "type": "object" }, "SnowflakeListingSection": { "required": [ "mode" ], "properties": { "mode": { "description": "`grant` grants read access on the bucket schema to roles in the backend's own Snowflake account. `share` is not supported yet and is rejected.", "type": "string", "enum": [ "grant", "share" ] }, "grantees": { "description": "Required when `mode` is `grant`, forbidden otherwise. Unquoted Snowflake role names (`^[A-Za-z_][A-Za-z0-9_$]{0,254}$`), stored in upper case; quoted names are not supported. Keboola-managed roles, the backend root role, `PUBLIC` and the Snowflake system roles are rejected with `storage.bucketListing.snowflakeGranteeNotAllowed`.", "type": "array", "items": { "type": "string" }, "maxItems": 100, "uniqueItems": true }, "accounts": { "description": "Consumer accounts for `share` mode, in `.` form. Not supported yet.", "type": "array", "items": { "type": "string" }, "maxItems": 100, "uniqueItems": true } }, "type": "object" }, "BucketListingCreateJobParams": { "required": [ "listingName" ], "properties": { "idBucket": { "description": "Internal numeric identifier of the bucket being exposed.", "type": "integer" }, "listingName": { "description": "Human-readable listing name carried over from the request.", "type": "string" }, "listingDescription": { "description": "Listing description carried over from the request. Present only when the request set one.", "type": "string", "default": null }, "bigquery": { "oneOf": [ { "$ref": "#/components/schemas/BigQueryListingSection" } ], "nullable": true, "description": "BigQuery-specific section carried over from the request. Present only for BigQuery buckets.", "default": null }, "snowflake": { "oneOf": [ { "$ref": "#/components/schemas/SnowflakeListingSection" } ], "nullable": true, "description": "Snowflake-specific section carried over from the request, with grantees in upper case. Present only for Snowflake buckets.", "default": null } }, "type": "object", "oneOf": [ { "required": [ "bigquery" ] }, { "required": [ "snowflake" ] } ] }, "CreateBucketListingRequest": { "description": "Exactly one backend section, `bigquery` or `snowflake`, is required and must match the bucket's backend.", "required": [ "listingName" ], "properties": { "listingName": { "description": "Human-readable listing name (maps to the backend listing displayName).", "type": "string", "maxLength": 63 }, "listingDescription": { "description": "Optional listing description. Send `null` or omit to leave it empty.", "type": "string", "nullable": true, "maxLength": 2000 }, "bigquery": { "$ref": "#/components/schemas/BigQueryListingSection" }, "snowflake": { "$ref": "#/components/schemas/SnowflakeListingSection" } }, "type": "object", "oneOf": [ { "required": [ "bigquery" ] }, { "required": [ "snowflake" ] } ] }, "BucketListingDeleteJobParams": { "properties": { "idBucket": { "type": "integer" } }, "type": "object" }, "SnowflakeExposureMode": { "type": "string", "enum": [ "grant", "share" ] }, "BucketListingUpdateJobParams": { "properties": { "idBucket": { "type": "integer" }, "exposureName": { "description": "Present only when the request sent a name.", "type": "string", "default": null }, "exposureDescription": { "description": "Absent when not provided; `null` clears the stored value.", "type": "string", "nullable": true, "default": null }, "bigquerySubscribers": { "description": "Present only when the request sent `bigquery.subscribers`.", "type": "array", "items": { "type": "string" }, "default": null }, "snowflakeMode": { "description": "Present only when the request sent `snowflake.mode`.", "oneOf": [ { "$ref": "#/components/schemas/SnowflakeExposureMode" } ], "default": null }, "snowflakeGrantees": { "description": "Present only when the request sent `snowflake.grantees`; upper case.", "type": "array", "items": { "type": "string" }, "default": null }, "snowflakeAccounts": { "description": "Present only when the request sent `snowflake.accounts`; upper case.", "type": "array", "items": { "type": "string" }, "default": null } }, "type": "object" }, "UpdateBucketListingRequest": { "description": "At least one of `exposureName`, `exposureDescription`, `bigquery.subscribers`, `snowflake.grantees` or `snowflake.accounts` must be provided. At most one backend section may be sent, and it must match the bucket's backend.", "properties": { "exposureName": { "description": "New human-readable exposure name (max 63 bytes).", "type": "string" }, "exposureDescription": { "description": "New exposure description (max 2000 bytes). Pass null to clear.", "type": "string", "nullable": true }, "bigquery": { "description": "BigQuery-specific exposure fields. The listingId is immutable and cannot be changed.", "properties": { "subscribers": { "description": "IAM principals; each value must be prefixed with \"user:\" or \"group:\".", "type": "array", "items": { "type": "string" } } }, "type": "object" }, "snowflake": { "description": "Snowflake-specific exposure fields. A sent list replaces the stored one.", "properties": { "mode": { "description": "Optional. The mode is immutable: a value other than the stored one is rejected with `storage.bucketListing.validationError`. `share` is not supported yet.", "type": "string", "enum": [ "grant", "share" ] }, "grantees": { "description": "Grant mode: the new list of grantee roles, with the same rules as on create.", "type": "array", "items": { "type": "string" }, "maxItems": 100, "uniqueItems": true }, "accounts": { "description": "Share mode: the new list of consumer accounts. Not supported yet.", "type": "array", "items": { "type": "string" }, "maxItems": 100, "uniqueItems": true } }, "type": "object" } }, "type": "object", "anyOf": [ { "required": [ "exposureName" ] }, { "required": [ "exposureDescription" ] }, { "required": [ "bigquery" ], "properties": { "bigquery": { "required": [ "subscribers" ] } } }, { "required": [ "snowflake" ], "properties": { "snowflake": { "required": [ "grantees" ] } } }, { "required": [ "snowflake" ], "properties": { "snowflake": { "required": [ "accounts" ] } } } ] }, "RefreshJobParams": { "required": [ "force" ], "properties": { "idBucket": { "type": "integer" }, "force": { "type": "boolean", "default": false }, "lastChangeDate": { "description": "Present only when the request set one and `force` is false.", "type": "string", "default": null } }, "type": "object" }, "RegisterExistingBucketRequest": { "required": [ "name", "path" ], "properties": { "name": { "description": "Name of the registered bucket in this project.", "type": "string", "example": "organizationData", "allOf": [ { "$ref": "#/components/schemas/StorageName" } ] }, "displayName": { "description": "Display name shown in the UI; can be changed anytime. Defaults to `name`.", "type": "string", "example": "organization-members", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/StorageName" } ] }, "stage": { "description": "Assigns the bucket to one of the stages.", "type": "string", "example": "in", "default": "in", "enum": [ "in", "out", "sys" ] }, "backend": { "description": "Bucket backend type; the default value is determined by the project settings.", "type": "string", "example": "snowflake", "nullable": true, "enum": [ "bigquery", "snowflake" ] }, "description": { "description": "Bucket description.", "type": "string", "example": "my bucket", "nullable": true }, "path": { "description": "Path to the schema. Snowflake: `[\"database-name\", \"schema-name\"]`; BigQuery: `[\"projectId\", \"location\", \"exchangerName\", \"listingName\"]`.", "type": "array", "items": { "type": "string" }, "example": [ "DATABASE", "SCHEMA" ], "minItems": 1 }, "isSnowflakeSharedDatabase": { "description": "Whether the external bucket uses the Snowflake Secure Data Share feature. Valid for the Snowflake backend only.", "type": "boolean", "example": false, "default": false } }, "type": "object" }, "ScheduleRefreshRequest": { "required": [ "cronExpression" ], "properties": { "cronExpression": { "description": "Cron expression defining when the scheduled refresh runs.", "type": "string", "example": "42 13 * * *" } }, "type": "object" }, "CreateBucketSharingToProjectsRequest": { "required": [ "targetProjectIds" ], "properties": { "targetProjectIds": { "description": "IDs of projects in the organization the bucket is shared to. Numeric strings are accepted.", "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ], "minItems": 1 } }, "type": "object" }, "CreateBucketSharingToUsersRequest": { "required": [ "targetUsers" ], "properties": { "targetUsers": { "description": "User IDs or user emails the bucket is shared to. Users must be members of at least one project in the organization.", "type": "array", "items": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "integer" } ] }, "example": [ "dev@keboola.com", "dev2@keboola.com", "dev3@keboola.com" ], "minItems": 1 } }, "type": "object" }, "UpdateBucketSharingRequest": { "required": [ "sharing" ], "properties": { "sharing": { "description": "Sharing type. `organization`: any organization member can link the bucket from any project within the organization. `organization-project`: any member of a project within the organization can link the bucket from their project.", "type": "string", "example": "organization-project", "enum": [ "organization", "organization-project" ] } }, "type": "object" }, "ListComponentsRequest": { "properties": { "componentType": { "description": "Filter components by type.", "type": "string", "nullable": true }, "include": { "description": "Comma-separated list of data to include. Allowed values: state, configuration, rows.", "type": "string", "nullable": true }, "isDeleted": { "description": "Whether to list deleted components instead of active ones. Accepts booleanish values.", "type": "string", "nullable": true } }, "type": "object" }, "BatchPurgeJobParams": { "required": [ "configurations" ], "properties": { "configurations": { "type": "string" } }, "type": "object" }, "BatchPurgeRequest": { "required": [ "configurations" ], "properties": { "configurations": { "description": "Configurations to purge from the trash.", "type": "array", "items": { "required": [ "componentId", "configurationId", "version" ], "properties": { "componentId": { "description": "Id of the component.", "type": "string", "example": "keboola.ex-db-mysql" }, "configurationId": { "description": "Id of the configuration.", "type": "string", "example": "main-1" }, "version": { "description": "Version the configuration was read at. The per-item equivalent of the `If-Match` header of the single-configuration purge: the item is purged only if the configuration is still at this version, otherwise it is reported as failed and the rest of the batch still runs.", "type": "integer", "example": 5 } }, "type": "object" }, "default": [], "maxItems": 1000 } }, "type": "object" }, "BatchRestoreJobParams": { "required": [ "configurations" ], "properties": { "configurations": { "type": "string" } }, "type": "object" }, "BatchRestoreRequest": { "required": [ "configurations" ], "properties": { "configurations": { "description": "Configurations to restore from the trash.", "type": "array", "items": { "required": [ "componentId", "configurationId" ], "properties": { "componentId": { "description": "Id of the component.", "type": "string", "example": "keboola.ex-db-mysql" }, "configurationId": { "description": "Id of the configuration.", "type": "string", "example": "main-1" } }, "type": "object" }, "default": [], "maxItems": 1000 } }, "type": "object" }, "CreateConfigurationRequest": { "required": [ "name" ], "properties": { "name": { "description": "Configuration name.", "type": "string", "example": "My new configuration" }, "configurationId": { "description": "Configuration id, must be unique within the component (max 100 characters). Auto-generated when omitted.", "type": "string", "example": "main-1", "nullable": true }, "description": { "description": "Configuration description.", "type": "string", "example": "", "nullable": true }, "configuration": { "description": "Configuration data; the maximum allowed size is 4MB.", "type": "object", "example": { "key": "value" }, "nullable": true, "additionalProperties": true }, "state": { "description": "State data; the maximum allowed size is 4MB.", "type": "object", "example": [], "nullable": true, "additionalProperties": true }, "changeDescription": { "description": "Description of the configuration modification.", "type": "string", "example": "Initial configuration", "nullable": true }, "isDisabled": { "description": "Disabled flag. Accepts booleanish values.", "type": "boolean", "nullable": true, "default": false }, "folder": { "description": "Folder to put the configuration in, at most 400 characters after trimming. Surrounding whitespace is trimmed; omitted, `null` or an empty string means no folder.", "type": "string", "example": "Marketing", "nullable": true, "maxLength": 400 } }, "type": "object" }, "RebaseRowData": { "description": "A single resolved configuration row in the rebase request \u2014 the same editable-content shape the diff returns in `diff.rows`. The `id` drives the reconciliation against the re-anchored base: an id present in the base updates that row, an id not in the base (or a missing id) creates a new row, and a base row whose id is absent from the request is deleted.", "properties": { "id": { "description": "Row id. Optional \u2014 a row without an id is created with a generated id.", "type": "string", "nullable": true }, "name": { "description": "Missing or `null` means `\"\"`.", "type": "string", "nullable": true }, "description": { "description": "Missing or `null` means `\"\"`.", "type": "string", "nullable": true }, "isDisabled": { "description": "Missing or `null` means `false`.", "type": "boolean", "nullable": true }, "configuration": { "description": "Missing or `null` means `{}`.", "type": "object", "nullable": true } }, "type": "object" }, "RebaseRequest": { "required": [ "version", "diff" ], "properties": { "version": { "description": "Default branch configuration version to rebase the dev branch onto. Always required, even when deleting \u2014 the base is always re-anchored.", "type": "integer" }, "diff": { "description": "Resolved configuration content (head, the 3-way diff result) \u2014 the \"diff\" object of a /diff response side posted back after resolution. Send an empty \"diff\" ({} or an empty/whitespace-only string) to resolve the conflict by deleting the configuration.", "oneOf": [ { "properties": { "name": { "description": "Resolved configuration name. Required for a keep rebase.", "type": "string" }, "description": { "description": "Resolved configuration description.", "type": "string" }, "changeDescription": { "description": "Change description for the resolved head version. If omitted, a default rebase message is used.", "type": "string" }, "isDisabled": { "description": "Resolved disabled flag. Defaults to false if omitted.", "type": "boolean" }, "configuration": { "description": "Resolved configuration body.", "type": "object" }, "rows": { "description": "Complete resolved row set. Required for a keep rebase \u2014 omitting it is an error; [] deletes all rows. The array order becomes the row sort order.", "type": "array", "items": { "$ref": "#/components/schemas/RebaseRowData" } } }, "type": "object" }, { "description": "An empty or whitespace-only string resolves the conflict by deleting the configuration; the same as sending an empty object.", "type": "string" } ] } }, "type": "object" }, "UpdateConfigurationStateRequest": { "required": [ "state" ], "properties": { "state": { "description": "Configuration state data; the maximum allowed size is 4MB. No other properties are accepted.", "type": "object", "example": { "lastId": 123 }, "additionalProperties": true } }, "type": "object" }, "UpdateConfigurationRequest": { "properties": { "name": { "description": "Configuration name.", "type": "string", "example": "My new configuration", "nullable": true }, "description": { "description": "Configuration description.", "type": "string", "example": "", "nullable": true }, "configuration": { "description": "Configuration data; the maximum allowed size is 4MB.", "type": "object", "example": { "key": "value", "key3": "value3" }, "nullable": true, "additionalProperties": true }, "state": { "description": "State data; the maximum allowed size is 4MB.", "type": "object", "nullable": true, "additionalProperties": true }, "changeDescription": { "description": "Description of the configuration modification.", "type": "string", "example": "Added new key", "nullable": true }, "isDisabled": { "description": "Disabled flag. Accepts booleanish values.", "type": "boolean", "nullable": true }, "rowsSortOrder": { "description": "Row ids in the desired order; all row ids must be specified.", "type": "array", "items": { "type": "string" }, "example": [ "row1", "row2" ], "nullable": true }, "folder": { "description": "Folder the configuration is grouped under, at most 400 characters after trimming. Surrounding whitespace is trimmed; an empty string removes the configuration from its folder. Omitted or `null` leaves the folder unchanged. Setting it does not create a new configuration version.", "type": "string", "example": "Marketing", "nullable": true, "maxLength": 400 } }, "type": "object" }, "CreateMetadataRequest": { "required": [ "metadata" ], "properties": { "metadata": { "description": "Array of metadata objects", "type": "array", "items": { "required": [ "key", "value" ], "properties": { "key": { "description": "Metadata key (`a-zA-Z0-9_.-`, max 255 chars)", "type": "string", "example": "some-key" }, "value": { "description": "Metadata value", "type": "string", "example": "Some value", "nullable": true } }, "type": "object" } } }, "type": "object" }, "CreateConfigurationRowRequest": { "properties": { "rowId": { "description": "Row id (must be unique for each configuration); if not set, it will be generated.", "type": "string", "example": "orders" }, "configuration": { "description": "Configuration data; the maximum allowed size is 4MB.", "type": "object", "example": { "host": "localhost", "port": 4406 }, "additionalProperties": true }, "state": { "description": "Configuration state data; the maximum allowed size is 4MB.", "type": "object", "example": { "lastId": 123 }, "additionalProperties": true }, "name": { "description": "Row name.", "type": "string", "example": "My row" }, "description": { "description": "Row description.", "type": "string", "example": "Extracts the orders table" }, "isDisabled": { "description": "Disabled flag.", "type": "boolean", "example": false }, "changeDescription": { "description": "Version change description.", "type": "string", "example": "Added new row" } }, "type": "object" }, "DeleteConfigurationRowRequest": { "properties": { "changeDescription": { "description": "Version change description.", "type": "string", "example": "change description" } }, "type": "object" }, "UpdateConfigurationRowStateRequest": { "required": [ "state" ], "properties": { "state": { "description": "Configuration state data; the maximum allowed size is 4MB.", "type": "object", "example": { "lastId": 123 }, "additionalProperties": true } }, "type": "object" }, "UpdateConfigurationRowRequest": { "properties": { "configuration": { "description": "Configuration data; the maximum allowed size is 4MB.", "type": "object", "example": { "host": "localhost", "port": 4406 }, "additionalProperties": true }, "state": { "description": "Configuration state data. Rejected with 400 `validation.invalidConfigurationRowParameter` \u2014 use the row state endpoint instead.", "type": "object", "additionalProperties": true }, "name": { "description": "Row name.", "type": "string", "example": "My row" }, "description": { "description": "Row description.", "type": "string", "example": "Extracts the orders table" }, "isDisabled": { "description": "Disabled flag.", "type": "boolean", "example": false }, "changeDescription": { "description": "Version change description.", "type": "string", "example": "change description" } }, "type": "object" }, "CreateConfigurationRowVersionRequest": { "properties": { "targetConfigId": { "description": "Copy the row to another existing configuration. If not provided, the row will be copied to the original configuration.", "type": "string", "example": "236606822" }, "changeDescription": { "description": "Version change description.", "type": "string", "example": "Copy to another row" } }, "type": "object" }, "ListRowVersionsRequest": { "type": "object" }, "RollbackConfigurationRowRequest": { "properties": { "changeDescription": { "description": "Version change description.", "type": "string", "example": "Rollback to previous version" } }, "type": "object" }, "CreateConfigurationVersionRequest": { "required": [ "name" ], "properties": { "name": { "description": "Name of the new configuration.", "type": "string", "example": "Configuration copy" }, "description": { "description": "Description of the new configuration.", "type": "string", "nullable": true }, "changeDescription": { "description": "Version change description.", "type": "string", "example": "Testing Copying", "nullable": true } }, "type": "object" }, "ListVersionsRequest": { "properties": { "include": { "description": "Comma-separated list of information to be retrieved; possible fields are `name`, `description` and `configuration`.", "type": "string", "example": "name,description,configuration", "nullable": true, "default": "name,description" }, "limit": { "description": "Pagination limit.", "type": "integer", "example": 100, "nullable": true, "default": 100 }, "offset": { "description": "Pagination offset.", "type": "integer", "example": 0, "nullable": true, "default": 0 } }, "type": "object" }, "RollbackConfigurationVersionRequest": { "properties": { "changeDescription": { "description": "Description of the version change.", "type": "string", "example": "change description", "nullable": true } }, "type": "object" }, "UpdateDevBranchRequest": { "description": "At least one of name or description must be provided.", "properties": { "name": { "description": "New name of the branch. Must not be blank; the default branch cannot be renamed.", "type": "string", "example": "My branch" }, "description": { "description": "New description of the branch.", "type": "string", "example": "Some description" } }, "type": "object" }, "CreateDevBranchRequest": { "required": [ "name" ], "properties": { "name": { "description": "Name of the branch. Must not be blank and must not equal the default branch name.", "type": "string", "example": "Refactor DB extractors" }, "description": { "description": "Description of the branch. Defaults to an empty string.", "type": "string", "example": "Rework of the DB extractor configurations" } }, "type": "object" }, "MetadataCreateRequest": { "required": [ "metadata" ], "properties": { "metadata": { "description": "List of metadata items to create or update", "type": "array", "items": { "required": [ "key", "value" ], "properties": { "key": { "description": "Metadata key (`a-zA-Z0-9_.-`, max 255 chars)", "type": "string", "example": "some-key" }, "value": { "description": "Metadata value", "type": "string", "example": "Some value", "nullable": true } }, "type": "object" } } }, "type": "object" }, "CreateEventRequest": { "required": [ "component", "message" ], "properties": { "component": { "description": "Name of a registered component the event belongs to.", "type": "string", "example": "keboola.test-component" }, "message": { "description": "Event message.", "type": "string", "example": "This is a word of warning" }, "description": { "description": "Event description.", "type": "string", "example": "Detailed description of what happened.", "nullable": true }, "type": { "description": "Type of the event. Unknown values fall back to `info`.", "type": "string", "example": "warn", "nullable": true, "default": "info", "enum": [ "info", "success", "warn", "error" ] }, "configurationId": { "description": "Id of a configuration executed by the component.", "type": "string", "example": "123456", "nullable": true }, "params": { "description": "Custom data.", "type": "object", "example": { "command": "sync-test" }, "nullable": true, "additionalProperties": true }, "results": { "description": "Custom data.", "type": "object", "example": { "projectId": "123", "otherId": "456" }, "nullable": true, "additionalProperties": true }, "duration": { "description": "Duration of the associated task in seconds. Stored as an integer.", "type": "number", "example": 12, "nullable": true }, "runId": { "description": "Id of the associated component job.", "type": "string", "example": "987654321", "nullable": true } }, "type": "object" }, "CreateTagRequest": { "required": [ "tag" ], "properties": { "tag": { "description": "Tag name. Trimmed of surrounding whitespace.", "type": "string", "example": "image" } }, "type": "object" }, "FileDeleteJobParams": { "required": [ "branchId", "fileId" ], "properties": { "branchId": { "type": "integer" }, "fileId": { "type": "integer" } }, "type": "object" }, "ListFilesRequest": { "properties": { "tags": { "description": "Shows only files with one or more of the specified tags.", "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ] }, "limit": { "description": "Pagination limit.", "type": "integer", "example": 100, "default": 100 }, "offset": { "description": "Pagination offset.", "type": "integer", "example": 0, "default": 0 }, "q": { "description": "Searches files using advanced Elasticsearch query string syntax.", "type": "string", "example": "name:*.csv", "nullable": true }, "sinceId": { "description": "Shows only files after the specified Id.", "type": "string", "example": "236504000", "nullable": true }, "maxId": { "description": "Shows only files before the passed Id.", "type": "string", "example": "236504177", "nullable": true }, "runId": { "description": "Shows only files with the given run Id.", "type": "string", "example": "12345.67890", "nullable": true }, "showExpired": { "description": "Include expired files in response.", "type": "boolean", "example": false, "default": false } }, "type": "object" }, "GlobalSearchRequest": { "required": [ "query" ], "properties": { "query": { "description": "Search query string.", "type": "string" }, "limit": { "description": "Maximum number of results to return.", "type": "integer", "default": 10, "minimum": 1 }, "offset": { "description": "Number of results to skip (pagination).", "type": "integer", "default": 0, "minimum": 0 }, "types": { "description": "Filter by object type. Repeatable.", "type": "array", "items": { "type": "string", "enum": [ "flow", "bucket", "table", "transformation", "configuration", "configuration-row", "workspace", "shared-code" ] }, "nullable": true }, "projectIds": { "description": "Narrow the search to specific project ids. Repeatable.", "type": "array", "items": { "type": "integer" }, "nullable": true }, "branchTypes": { "description": "Filter by branch type. Repeatable.", "type": "array", "items": { "type": "string", "enum": [ "production", "development" ] }, "nullable": true }, "branchIds": { "description": "Filter by branch ids. Repeatable.", "type": "array", "items": { "type": "integer" }, "nullable": true }, "mode": { "description": "Search mode. Allowed values: standard, regex. Default: standard.\n\nstandard: full-text search with normalisation (accent folding, lower-casing, word splitting).\nregex: Lucene regexp matched against the original (un-normalised) storage id and object name.\n - Matches if the pattern matches the id OR the name.\n - Whole-term semantics: \"report\" does NOT match \"monthly_report\"; use \".*report.*\" to match a substring.\n - Case-insensitive.\n - Object names longer than 256 characters are not searchable in regex mode (ids are not length-limited).\n - An invalid or overly long pattern returns HTTP 400.", "type": "string", "default": "standard", "enum": [ "standard", "regex" ] } }, "type": "object" }, "StorageJobsListQueryRequest": { "description": "Query parameters for listing storage jobs.", "properties": { "limit": { "description": "Maximum number of jobs to return (pagination).", "type": "integer", "nullable": true }, "offset": { "description": "Offset for pagination.", "type": "integer", "nullable": true }, "storage_job_status": { "description": "Filter by job status.", "type": "array", "items": { "type": "string" }, "nullable": true }, "excluded_storage_job_status": { "description": "Exclude jobs with these statuses.", "type": "array", "items": { "type": "string" }, "nullable": true }, "created_time": { "description": "Filter by exact created time.", "type": "string", "format": "date-time", "nullable": true }, "created_time_from": { "description": "Filter jobs created after this time.", "type": "string", "format": "date-time", "nullable": true }, "created_time_to": { "description": "Filter jobs created before this time.", "type": "string", "format": "date-time", "nullable": true }, "start_time": { "description": "Filter by exact start time.", "type": "string", "format": "date-time", "nullable": true }, "start_time_from": { "description": "Filter jobs started after this time.", "type": "string", "format": "date-time", "nullable": true }, "start_time_to": { "description": "Filter jobs started before this time.", "type": "string", "format": "date-time", "nullable": true }, "end_time": { "description": "Filter by exact end time.", "type": "string", "format": "date-time", "nullable": true }, "end_time_from": { "description": "Filter jobs ended after this time.", "type": "string", "format": "date-time", "nullable": true }, "end_time_to": { "description": "Filter jobs ended before this time.", "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "MergeRequestCreateRequest": { "required": [ "title", "branchFromId", "branchIntoId" ], "properties": { "branchFromId": { "type": "integer" }, "branchIntoId": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "externalId": { "type": "string", "nullable": true, "default": null }, "autoMergeStrategy": { "type": "string", "nullable": true, "default": null, "enum": [ "immediately", "scheduled", "none" ] }, "autoMergeAt": { "description": "Required when autoMergeStrategy is \"scheduled\"", "type": "string", "format": "date-time", "nullable": true, "default": null }, "reviewerIds": { "type": "array", "items": { "type": "integer" }, "default": [] } }, "type": "object" }, "MergeRequestDetailRequest": { "properties": { "include": { "description": "Comma-separated list of data to include. Allowed values: activityLog.", "type": "string", "nullable": true } }, "type": "object" }, "MergeRequestRejectRequest": { "properties": { "reason": { "description": "Optional explanation why the merge request is being rejected. Stored in the activity log.", "type": "string", "maxLength": 1000 } }, "type": "object" }, "MergeRequestUpdateRequest": { "properties": { "title": { "description": "Omit to keep unchanged. Empty string is not allowed.", "type": "string", "nullable": true, "default": null }, "description": { "description": "Omit to keep unchanged. Send empty string to clear.", "type": "string", "nullable": true, "default": null }, "externalId": { "description": "Omit to keep unchanged. Send empty string to clear.", "type": "string", "nullable": true, "default": null }, "autoMergeStrategy": { "description": "Omit to keep unchanged. Send \"none\" to disable.", "type": "string", "nullable": true, "default": null, "enum": [ "immediately", "scheduled", "none" ] }, "autoMergeAt": { "description": "Required when autoMergeStrategy is \"scheduled\"", "type": "string", "format": "date-time", "nullable": true, "default": null }, "reviewerIds": { "description": "Omit to keep unchanged. Send empty array to clear.", "type": "array", "items": { "type": "integer" }, "nullable": true, "default": null } }, "type": "object" }, "SearchComponentConfigurationsRequest": { "type": "object" }, "SearchTablesRequest": { "description": "At least one of metadataKey, metadataValue, metadataProvider must be provided.", "properties": { "metadataKey": { "description": "Metadata key to search for.", "type": "string", "nullable": true }, "metadataValue": { "description": "Metadata value to search for.", "type": "string", "nullable": true }, "metadataProvider": { "description": "Metadata provider to search for.", "type": "string", "nullable": true }, "include": { "description": "Resources to include for each table: buckets, columns, metadata, columnMetadata, sourceMetadata, sourceColumnMetadata. Accepts a comma-separated string or a repeated array. Default: attributes,buckets.", "example": "buckets,metadata", "nullable": true, "oneOf": [ { "description": "Comma-separated list of resources.", "type": "string" }, { "description": "Repeated array of resources.", "type": "array", "items": { "type": "string" } } ] } }, "type": "object" }, "ListSharedBucketsRequest": { "properties": { "include": { "description": "Comma-separated list of resources to include for each bucket. Available resources: `metadata`.", "type": "string", "example": "metadata", "nullable": true } }, "type": "object" }, "StatsListRequest": { "required": [ "runId" ], "properties": { "runId": { "description": "Id of the run to list stats for.", "type": "string" } }, "type": "object" }, "IndexRequest": { "type": "object" }, "SetAliasFilterRequest": { "description": "Sets or updates a filter on a simple alias table. All fields are optional\n and an empty body is a valid request that keeps the table's current filter unchanged.", "properties": { "column": { "description": "Name of the column to filter on. Requires \"values\" to be set as well.", "type": "string", "example": "campaign_id", "nullable": true }, "values": { "description": "Values to filter by. Requires \"column\" to be set as well.", "type": "array", "items": { "type": "string" }, "example": [ "68abf5473f" ], "nullable": true }, "operator": { "description": "Comparison operator used for the filter: `eq` (equal to) or `ne` (not equal to).", "type": "string", "example": "eq", "nullable": true, "default": "eq", "enum": [ "eq", "ne" ] } }, "type": "object" }, "TableColumnAddJobParamsDefinition": { "description": "Column definition, as stored in the job operation params.", "properties": { "type": { "description": "Backend-specific column data type. Present only for typed-table columns.", "type": "string" }, "length": { "description": "Column length. Present only when a typed-table request sent it.", "type": "string", "nullable": true }, "nullable": { "description": "Whether the column allows NULL values. Present only when a typed-table request sent it.", "type": "boolean", "nullable": true }, "default": { "description": "Default value of the column. Present only when a typed-table request sent it.", "type": "string", "nullable": true }, "description": { "description": "Column description. Present only when sent.", "type": "string", "nullable": true } }, "type": "object" }, "TableColumnAddJobParams": { "required": [ "name", "backendConfiguration" ], "properties": { "name": { "type": "string" }, "definition": { "$ref": "#/components/schemas/TableColumnAddJobParamsDefinition" }, "basetype": { "description": "Present only when a typed-table request sent it.", "type": "string", "default": null }, "backendConfiguration": { "oneOf": [ { "$ref": "#/components/schemas/BackendConfigurationJobParams" } ], "default": null }, "tableStringId": { "type": "string", "nullable": true, "default": null }, "idBucket": { "type": "integer", "nullable": true, "default": null } }, "type": "object" }, "BigqueryAddColumnToTableRequest": { "description": "Request for adding a column to a BigQuery table.", "required": [ "name" ], "properties": { "name": { "description": "Name of the column to add.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/StorageColumnName" } ] }, "definition": { "description": "Column definition for BigQuery.", "required": [ "type" ], "properties": { "type": { "description": "BigQuery column type. Must be one of allowed types.", "type": "string" }, "length": { "description": "Optional length for the column, e.g. `\"38,0\"`.", "type": "string", "nullable": true }, "nullable": { "description": "Whether the column is nullable. Must be `true`: BigQuery cannot add required columns.", "type": "boolean", "nullable": true }, "description": { "description": "Optional column description stored as table metadata.", "type": "string", "nullable": true } }, "type": "object" }, "basetype": { "description": "Keboola base type of the column, case-insensitive: `BOOLEAN`, `DATE`, `FLOAT`, `INTEGER`, `NUMERIC`, `STRING` or `TIMESTAMP`. Required when `definition` is not sent.", "type": "string", "example": "STRING" } }, "type": "object" }, "SnowflakeAddColumnToTableRequest": { "description": "Request for adding a column to a Snowflake table.", "required": [ "name" ], "properties": { "name": { "description": "Name of the column to add.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/StorageColumnName" } ] }, "definition": { "description": "Column definition for Snowflake.", "required": [ "type" ], "properties": { "type": { "description": "Snowflake column type. Must be one of allowed types.", "type": "string" }, "length": { "description": "Optional length for the column, e.g. `\"38,0\"`.", "type": "string", "nullable": true }, "nullable": { "description": "Whether the column is nullable.", "type": "boolean", "nullable": true }, "default": { "description": "Default value for the column.", "type": "string", "nullable": true }, "description": { "description": "Optional column description stored as table metadata.", "type": "string", "nullable": true } }, "type": "object" }, "basetype": { "description": "Keboola base type of the column, case-insensitive: `BOOLEAN`, `DATE`, `FLOAT`, `INTEGER`, `NUMERIC`, `STRING` or `TIMESTAMP`. Required when `definition` is not sent.", "type": "string", "example": "STRING" } }, "type": "object" }, "ColumnCreateRequest": { "description": "Request for adding a column to a table.", "required": [ "name" ], "properties": { "name": { "description": "Name of the column to add.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/StorageColumnName" } ] }, "definition": { "description": "Column definition. For untyped tables only \"description\" is allowed.", "properties": { "description": { "description": "Column description.", "type": "string", "nullable": true } }, "type": "object", "nullable": true } }, "type": "object" }, "TableColumnDeleteJobParams": { "required": [ "name", "force", "backendConfiguration" ], "properties": { "name": { "type": "string" }, "tableStringId": { "type": "string", "nullable": true, "default": null }, "idBucket": { "type": "integer", "nullable": true, "default": null }, "force": { "type": "boolean", "default": false }, "backendConfiguration": { "oneOf": [ { "$ref": "#/components/schemas/BackendConfigurationJobParams" } ], "default": null } }, "type": "object" }, "TableColumnsDefinitionUpdateColumnDefinition": { "description": "Column definition patch carried by the tableColumnDefinitionUpdate job.", "required": [ "removeDefault" ], "properties": { "length": { "description": "New column length. Present only when sent.", "type": "string", "example": "10" }, "nullable": { "description": "Whether the column becomes nullable. Present only when sent.", "type": "boolean" }, "default": { "description": "New column default. Present only when a non-null default was sent.", "type": "string" }, "description": { "description": "New column description. Present only when sent.", "type": "string", "nullable": true }, "removeDefault": { "description": "True when the request sent `default: null`, asking for the existing default to be dropped.", "type": "boolean" } }, "type": "object" }, "TableColumnsDefinitionUpdateJobParams": { "required": [ "branchId", "columnName", "columnDefinition" ], "properties": { "branchId": { "type": "integer" }, "idBucket": { "type": "integer" }, "tableStringId": { "type": "string" }, "columnName": { "type": "string" }, "columnDefinition": { "$ref": "#/components/schemas/TableColumnsDefinitionUpdateColumnDefinition" } }, "type": "object" }, "SnowflakeColumnsDefinitionUpdateRequest": { "description": "Request for updating the definition of a Snowflake table column.", "properties": { "length": { "description": "New column length. Validated against the column data type.", "type": "string", "nullable": true }, "nullable": { "description": "Whether the column should allow NULL values.", "type": "boolean", "nullable": true }, "default": { "description": "New default value for the column. Set explicitly to JSON null to remove the existing default.", "type": "string", "nullable": true }, "description": { "description": "New column description, stored as table metadata.", "type": "string", "nullable": true } }, "type": "object" }, "BigQueryColumnsDefinitionUpdateRequest": { "description": "Request for updating the definition of a BigQuery table column.", "properties": { "length": { "description": "New column length. Validated against the column data type.", "type": "string", "nullable": true }, "nullable": { "description": "Whether the column should allow NULL values. BigQuery does not allow changing a nullable column back to required.", "type": "boolean", "nullable": true }, "default": { "description": "New default value for the column. Set explicitly to JSON null to remove the existing default.", "type": "string", "nullable": true }, "description": { "description": "New column description, stored as table metadata.", "type": "string", "nullable": true } }, "type": "object" }, "WhereFiltersDeleteRowsObject": { "description": "A single row filter for row deletion, joined with other filters by AND.", "required": [ "column", "operator" ], "properties": { "column": { "description": "Column to filter by.", "type": "string" }, "operator": { "description": "`eq`/`ne` support multiple `values` (IN/NOT IN semantics); `gt`/`ge`/`lt`/`le` accept a single value only.", "type": "string", "default": "eq", "enum": [ "eq", "ne", "gt", "ge", "lt", "le" ] }, "values": { "description": "Values to compare against. Present only when `valuesByTableInWorkspace` is not used. A `null` item matches SQL NULL (`eq` adds `OR column IS NULL`, `ne` adds `AND column IS NOT NULL`) and is allowed only with `eq` and `ne`; an empty string is a different value than NULL.", "type": "array", "items": { "type": "string", "nullable": true } }, "dataType": { "description": "Cast the column to this data type before comparing (e.g. `INTEGER`, `DOUBLE`, `BIGINT`, `REAL`, `DECIMAL` on Snowflake; backend-specific choices on BigQuery). Present only when set.", "type": "string", "nullable": true }, "type": { "description": "How `values` are interpreted. `SCALAR` compares raw values; `TIME_STRING` interprets them as date/time strings or unix timestamps. Present only when set.", "type": "string", "default": "SCALAR", "enum": [ "SCALAR", "TIME_STRING" ] }, "valuesByTableInWorkspace": { "description": "Filter by the current values of a column in a workspace table instead of a literal list. Present only when used instead of `values`.", "required": [ "workspaceId", "table", "column" ], "properties": { "workspaceId": { "description": "Workspace ID holding the comparison table.", "type": "integer" }, "table": { "description": "Name of the comparison table inside the workspace.", "type": "string" }, "column": { "description": "Column in the comparison table whose values are used.", "type": "string" } }, "type": "object" } }, "type": "object" }, "TableRowsDeleteJobParamsRequest": { "description": "The delete-rows request, as stored in the job operation params.", "required": [ "changedSince", "changedUntil", "whereFilters", "allowTruncate" ], "properties": { "changedSince": { "description": "Never populated by the current request mapping; always null on the wire.", "type": "string", "nullable": true }, "changedUntil": { "description": "Never populated by the current request mapping; always null on the wire.", "type": "string", "nullable": true }, "whereFilters": { "description": "Row filters, joined by AND; null when no filters were given.", "type": "array", "items": { "$ref": "#/components/schemas/WhereFiltersDeleteRowsObject" }, "nullable": true }, "allowTruncate": { "description": "Whether the table may be truncated when no filters narrow the deletion.", "type": "boolean" } }, "type": "object" }, "TableRowsDeleteJobParams": { "required": [ "request", "backendConfiguration" ], "properties": { "request": { "$ref": "#/components/schemas/TableRowsDeleteJobParamsRequest" }, "backendConfiguration": { "oneOf": [ { "$ref": "#/components/schemas/BackendConfigurationJobParams" } ], "default": null }, "tableStringId": { "type": "string", "nullable": true, "default": null }, "idBucket": { "type": "integer", "nullable": true, "default": null } }, "type": "object" }, "WhereFiltersObject": { "description": "A single row filter; multiple filters are joined by AND.", "required": [ "column", "values" ], "properties": { "column": { "description": "Column to filter by.", "type": "string" }, "operator": { "description": "`eq`/`ne` support multiple `values` (IN/NOT IN semantics); `gt`/`ge`/`lt`/`le` accept a single value only.", "type": "string", "default": "eq", "enum": [ "eq", "ne", "gt", "ge", "lt", "le" ] }, "values": { "description": "Values to compare against.", "type": "array", "items": { "type": "string" } }, "dataType": { "description": "Cast the column to this data type before comparing (`INTEGER` or `DOUBLE` on Snowflake; `STRING`, `INTEGER`, `DOUBLE`, `BIGINT`, `REAL`, `DECIMAL` or `TIMESTAMP` on BigQuery). Required for `gt`/`ge`/`lt`/`le` on numeric values; must be empty or `TIMESTAMP` when `type` is `TIME_STRING`.", "type": "string", "nullable": true }, "type": { "description": "How `values` are interpreted. `SCALAR` compares raw values; `TIME_STRING` interprets them as date/time strings or unix timestamps.", "type": "string", "default": "SCALAR", "enum": [ "SCALAR", "TIME_STRING" ] } }, "type": "object" }, "OrderByObject": { "description": "A single sort condition.", "required": [ "column" ], "properties": { "column": { "description": "Column to sort by.", "type": "string" }, "order": { "description": "Sort direction.", "type": "string", "default": "ASC", "enum": [ "ASC", "DESC" ] }, "dataType": { "description": "Cast the column to this data type before sorting (`INTEGER` or `DOUBLE` on Snowflake; `STRING`, `INTEGER`, `DOUBLE`, `BIGINT`, `REAL`, `DECIMAL` or `TIMESTAMP` on BigQuery). Required when sorting a numeric column; disallowed for typed tables.", "type": "string", "nullable": true } }, "type": "object" }, "TableExportJobParamsExport": { "description": "Resolved export options, as stored in the job operation params.", "required": [ "tableName", "columns", "limit", "changedSince", "changedUntil", "gzipOutput", "format", "whereFilters", "orderBy", "fulltextSearch", "includeInternalTimestamp", "fileType" ], "properties": { "tableName": { "description": "Name of the exported table.", "type": "string" }, "columns": { "description": "Columns to export; empty when all columns are exported.", "type": "array", "items": { "type": "string" } }, "limit": { "description": "Row limit.", "type": "integer", "nullable": true }, "changedSince": { "description": "Unix timestamp; export only rows imported since this time.", "type": "integer", "nullable": true }, "changedUntil": { "description": "Unix timestamp; export only rows imported until this time.", "type": "integer", "nullable": true }, "gzipOutput": { "description": "Whether the exported file is gzipped.", "type": "boolean" }, "format": { "description": "Output format.", "type": "string", "enum": [ "rfc", "json" ] }, "whereFilters": { "description": "Resolved row filters.", "type": "array", "items": { "$ref": "#/components/schemas/WhereFiltersObject" } }, "orderBy": { "description": "Resolved sort conditions.", "type": "array", "items": { "$ref": "#/components/schemas/OrderByObject" } }, "fulltextSearch": { "description": "Fulltext search key.", "type": "string", "nullable": true }, "includeInternalTimestamp": { "description": "Whether the internal `_timestamp` column is included in the export.", "type": "boolean" }, "fileType": { "description": "File type created in File Storage.", "type": "string", "enum": [ "csv", "parquet" ] }, "timezone": { "description": "IANA timezone the Snowflake session was set to for the export. Present only when set.", "type": "string" } }, "type": "object" }, "TableExportJobParams": { "required": [ "destinationBranchId", "export" ], "properties": { "destinationBranchId": { "type": "integer" }, "export": { "$ref": "#/components/schemas/TableExportJobParamsExport" }, "tableStringId": { "type": "string", "nullable": true, "default": null }, "idBucket": { "type": "integer", "nullable": true, "default": null }, "backendConfiguration": { "description": "Present only when the `X-KBC-Backend` header sets a context.", "oneOf": [ { "$ref": "#/components/schemas/BackendConfigurationJobParams" } ], "default": null } }, "type": "object" }, "ExportTableRequest": { "description": "Parameters for an asynchronous table export.", "properties": { "changedSince": { "description": "Export only rows imported since this time. Timestamp of import is stored within each row. Accepts a unix timestamp or a strtotime() compatible string (e.g. `-2 days`).", "type": "string", "example": "-2 days", "nullable": true }, "changedUntil": { "description": "Export only rows imported until this time. Accepts a unix timestamp or a strtotime() compatible string.", "type": "string", "example": "-1 day", "nullable": true }, "days": { "description": "Deprecated (use changedSince instead). Accepted for backward compatibility and ignored.", "type": "integer", "nullable": true, "deprecated": true }, "whereColumn": { "description": "Deprecated (use whereFilters instead). Column for exporting only matching rows.", "type": "string", "nullable": true, "deprecated": true }, "whereValues": { "description": "Deprecated (use whereFilters instead). Values for exporting only matching rows.", "type": "array", "items": { "type": "string" }, "nullable": true, "deprecated": true }, "whereOperator": { "description": "Deprecated (use whereFilters instead). Operator for value comparison.", "type": "string", "nullable": true, "deprecated": true, "default": "eq", "enum": [ "eq", "ne" ] } }, "type": "object" }, "ImportDataAsyncFromFileRequest": { "description": "Import data from a file stored in File Uploads. Specify either `enclosure` or `escapedBy`, not both.", "required": [ "dataFileId" ], "properties": { "dataFileId": { "description": "ID of the file stored in File Uploads; gzipped and sliced files are supported.", "type": "integer", "example": 12345 }, "incremental": { "description": "If true, the import adds data to the existing data in the table. If false, the target table is truncated before the import.", "type": "boolean", "default": false }, "withoutHeaders": { "description": "The CSV file has no header row. Columns must be in the same order as in the storage table; use `columns` to specify the order.", "type": "boolean", "default": false }, "treatValuesAsNull": { "description": "Snowflake and BigQuery only. String values imported as NULL. Default `[\"\"]`. Currently only a single value is allowed, but it must be sent as an array. On BigQuery an empty array means no value is converted to NULL.", "type": "array", "items": { "type": "string" }, "example": [ "" ], "nullable": true, "maxItems": 1 }, "columns": { "description": "List of columns present in the CSV file; the first line of the file is then not treated as a header.", "type": "array", "items": { "type": "string" }, "example": [ "id", "name" ], "nullable": true }, "ignoredLinesCount": { "description": "Number of lines to skip at the beginning of the file. When set, `withoutHeaders` is ignored.", "type": "integer", "default": 0 }, "enclosure": { "description": "Field enclosure used in the CSV file. Default `\"`.", "type": "string", "example": "\"", "nullable": true }, "delimiter": { "description": "Field delimiter used in the CSV file. Default `,`. Use `\\t` or the tab char for tabulator.", "type": "string", "example": ",", "nullable": true }, "escapedBy": { "description": "Escape character used in the CSV file. Default empty - no escape character is used.", "type": "string", "nullable": true }, "useTimestampFromDataFile": { "description": "Snowflake only. If true, the CSV file must contain a `_timestamp` column with valid datetime values.", "type": "boolean", "default": false }, "partitionAwareImport": { "description": "BigQuery only, ignored on other backends. For an incremental import into a table with a primary key, restrict the deduplication join to the destination partitions of the imported rows, which reduces the bytes the import reads. Applies only when the table is partitioned by a column (time-unit column or integer range) that is part of the primary key; otherwise the import runs unchanged.", "type": "boolean", "default": false } }, "type": "object" }, "ImportDataAsyncFromWorkspaceRequest": { "description": "Import data from a table or file workspace. For a table workspace set `dataObject` to the source table name; for a file workspace `dataObject` can be a single file (`file.csv`), a folder (`folder/`, mind the trailing slash) or a manifest (`file.csvmanifest`) and `columns` must be set. Either `dataObject` or the deprecated `dataTableName` is required.", "required": [ "dataWorkspaceId" ], "properties": { "dataWorkspaceId": { "description": "ID of the source workspace. Use with `dataObject`.", "type": "integer", "example": 12345 }, "dataObject": { "description": "Name of the table/file in the workspace to load from.", "type": "string", "example": "myTable", "nullable": true }, "dataTableName": { "description": "Deprecated (use dataObject instead). Name of the table in the workspace.", "type": "string", "nullable": true, "deprecated": true }, "incremental": { "description": "If true, the import adds data to the existing data in the table. If false, the target table is truncated before the import.", "type": "boolean", "default": false }, "withoutHeaders": { "description": "The CSV file has no header row; columns are matched by their order. When used, `columns` is ignored.", "type": "boolean", "default": false }, "columns": { "description": "List of columns present in the source; required for file workspaces.", "type": "array", "items": { "type": "string" }, "example": [ "id", "name" ], "nullable": true }, "enclosure": { "description": "Field enclosure used in the CSV file. Default `\"`.", "type": "string", "example": "\"", "nullable": true }, "delimiter": { "description": "Field delimiter used in the CSV file. Default `,`.", "type": "string", "example": ",", "nullable": true }, "escapedBy": { "description": "Escape character used in the CSV file. Default empty - no escape character is used.", "type": "string", "nullable": true }, "deduplicationStrategy": { "description": "Snowflake only. How duplicate rows in the imported data are handled: `upsert` updates existing rows and adds new ones, `insert` only adds new rows.", "type": "string", "nullable": true, "default": "upsert", "enum": [ "insert", "upsert" ] }, "partitionAwareImport": { "description": "BigQuery only, ignored on other backends. For an incremental import into a table with a primary key, restrict the deduplication join to the destination partitions of the imported rows, which reduces the bytes the import reads. Applies only when the table is partitioned by a column (time-unit column or integer range) that is part of the primary key; otherwise the import runs unchanged.", "type": "boolean", "default": false } }, "type": "object" }, "TablePrimaryKeyAddJobParams": { "required": [ "columns", "skipDuplicatesCheck", "backendConfiguration" ], "properties": { "columns": { "type": "array", "items": { "type": "string" } }, "tableStringId": { "type": "string", "nullable": true, "default": null }, "idBucket": { "type": "integer", "nullable": true, "default": null }, "skipDuplicatesCheck": { "type": "boolean", "default": null }, "backendConfiguration": { "oneOf": [ { "$ref": "#/components/schemas/BackendConfigurationJobParams" } ], "default": null } }, "type": "object" }, "CreatePrimaryKeyRequest": { "description": "Request for creating a table primary key.", "required": [ "columns" ], "properties": { "columns": { "description": "Names of the columns that make up the primary key.", "type": "array", "items": { "type": "string" } }, "skipDuplicatesCheck": { "description": "When true, skip the validation that the primary key columns contain no duplicate values.", "type": "boolean", "default": false } }, "type": "object" }, "DevBranchTablePullJobParams": { "required": [ "sourceBranchId", "targetBranchId", "pullData", "apiVersion" ], "properties": { "sourceBranchId": { "type": "integer" }, "targetBranchId": { "type": "integer" }, "pullData": { "type": "boolean", "default": null }, "apiVersion": { "type": "string", "default": null }, "tableStringId": { "type": "string", "nullable": true, "default": null }, "idBucket": { "type": "integer", "nullable": true, "default": null } }, "type": "object" }, "TableSnapshotCreateJobParams": { "required": [ "backendConfiguration" ], "properties": { "description": { "description": "Present only when the request sent a description.", "type": "string", "default": null }, "backendConfiguration": { "oneOf": [ { "$ref": "#/components/schemas/BackendConfigurationJobParams" } ], "default": null }, "tableStringId": { "type": "string", "nullable": true, "default": null }, "idBucket": { "type": "integer", "nullable": true, "default": null } }, "type": "object" }, "CreateSnapshotRequest": { "properties": { "description": { "description": "Snapshot description.", "type": "string", "example": "My first snapshot", "nullable": true } }, "type": "object" }, "GetSnapshotsRequest": { "properties": { "limit": { "description": "Pagination limit. Omit (or pass a value <= 0) to return all snapshots.", "type": "integer", "example": 20, "nullable": true }, "offset": { "description": "Pagination offset.", "type": "integer", "example": 0, "nullable": true } }, "type": "object" }, "CreateTableMetadataRequest": { "description": "At least one of `metadata` or `columnsMetadata` is required.", "required": [ "provider" ], "properties": { "provider": { "description": "Id of the creating component", "type": "string", "example": "test-component" }, "metadata": { "description": "Array of table metadata objects", "type": "array", "items": { "required": [ "key", "value" ], "properties": { "key": { "description": "Metadata key (`a-zA-Z0-9_.-`, max 255 chars)", "type": "string", "example": "some-key" }, "value": { "description": "Metadata value", "type": "string", "example": "Some value", "nullable": true } }, "type": "object" } }, "columnsMetadata": { "description": "Object of column metadata grouped by column, indexed by int (indexing by columnName is deprecated). Each metadata object should carry `columnName`.", "type": "object", "example": [ [ { "columnName": "id", "key": "some-key", "value": "Some value" } ] ], "additionalProperties": { "type": "array", "items": { "required": [ "key", "value" ], "properties": { "columnName": { "description": "Name of the column; required unless the (deprecated) columnName index is used", "type": "string", "example": "id" }, "key": { "description": "Metadata key", "type": "string", "example": "some-key" }, "value": { "description": "Metadata value", "type": "string", "example": "Some value", "nullable": true } }, "type": "object" } } } }, "type": "object" }, "DataPreviewRequest": { "description": "Parameters for table data preview.", "properties": { "limit": { "description": "Limit the number of returned rows. Maximum allowed value is `1000`.", "type": "integer", "example": 100, "default": 100, "maximum": 1000, "minimum": 0 }, "changedSince": { "description": "Filtering by import date - the import timestamp is stored within each row. Accepts a unix timestamp or any date accepted by strtotime.", "type": "string", "example": "-2 days", "nullable": true }, "changedUntil": { "description": "Filtering by import date - the import timestamp is stored within each row. Accepts a unix timestamp or any date accepted by strtotime.", "type": "string", "example": "2013-02-12T15:19:21+00:00", "nullable": true }, "columns": { "description": "Comma separated list of columns to export; by default all columns are exported.", "type": "string", "example": "id,name", "nullable": true }, "whereColumn": { "description": "Deprecated (use `whereFilters` instead). Column for exporting only matching rows.", "type": "string", "example": "id", "nullable": true, "deprecated": true }, "whereValues": { "description": "Deprecated (use `whereFilters` instead). Values for exporting only matching rows.", "type": "array", "items": { "type": "string" }, "example": [ "26" ], "nullable": true, "deprecated": true }, "whereOperator": { "description": "Deprecated (use `whereFilters` instead). Operator for value comparison: `eq` (can be used with multiple values) or `ne`.", "type": "string", "nullable": true, "deprecated": true, "default": "eq", "enum": [ "eq", "ne" ] }, "format": { "description": "Output format of the preview: `rfc` returns CSV, `json` returns JSON.", "type": "string", "example": "json", "nullable": true, "default": "rfc", "enum": [ "rfc", "json" ] }, "whereFilters": { "description": "Row filters (see the asynchronous export for the filter description). Sent as `whereFilters[0][column]=...`.", "type": "array", "items": { "$ref": "#/components/schemas/WhereFiltersObject" }, "nullable": true }, "orderBy": { "description": "Sort specification. Sent as `orderBy[0][column]=...`.", "type": "array", "items": { "$ref": "#/components/schemas/OrderByObject" }, "nullable": true }, "fulltextSearch": { "description": "Fulltext search over all data in the table. Cannot be combined with `whereFilters`. Snowflake/BigQuery only.", "type": "string", "example": "czech", "nullable": true }, "cache": { "description": "A JSON preview requested without any other parameter is served from a cache that is refreshed whenever the table changes. Set to `0` to always read the data from the backend.", "type": "boolean", "example": false, "default": true } }, "type": "object" }, "TableDefinitionUpdateColumnObject": { "description": "A single column patch, as stored in the job operation params.", "required": [ "name", "nullableSet", "defaultSet", "descriptionSet" ], "properties": { "name": { "description": "Name of the column being patched.", "type": "string" }, "length": { "description": "New length of the column type. Present only when supplied.", "type": "string" }, "nullable": { "description": "New nullable flag. Present only when `nullableSet` is true.", "type": "boolean", "nullable": true }, "nullableSet": { "description": "Whether `nullable` was explicitly supplied (including an explicit null).", "type": "boolean" }, "default": { "description": "New default value. Present only when `defaultSet` is true.", "type": "string", "nullable": true }, "defaultSet": { "description": "Whether `default` was explicitly supplied (including an explicit null).", "type": "boolean" }, "description": { "description": "New column description. Present only when `descriptionSet` is true.", "type": "string", "nullable": true }, "descriptionSet": { "description": "Whether `description` was explicitly supplied (including an explicit null).", "type": "boolean" } }, "type": "object" }, "TableDefinitionUpdateJobParams": { "required": [ "branchId", "columns", "backendConfiguration" ], "properties": { "branchId": { "type": "integer" }, "idBucket": { "type": "integer" }, "tableStringId": { "type": "string" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/TableDefinitionUpdateColumnObject" } }, "displayName": { "description": "Absent when not provided; `null` clears the stored value.", "type": "string", "nullable": true, "default": null }, "description": { "description": "Absent when not provided; `null` clears the stored value.", "type": "string", "nullable": true, "default": null }, "isDescriptionSystemManaged": { "description": "Absent when not provided; `null` clears the stored value.", "type": "boolean", "nullable": true, "default": null }, "backendConfiguration": { "oneOf": [ { "$ref": "#/components/schemas/BackendConfigurationJobParams" } ], "default": null } }, "type": "object" }, "TableDefinitionUpdateRequest": { "description": "At least one table or column patch must be provided.", "properties": { "displayName": { "description": "New table display name. Omit to keep unchanged; must not be blank.", "type": "string", "example": "Orders", "allOf": [ { "$ref": "#/components/schemas/StorageName" } ] }, "description": { "description": "Table description; null or an empty string clears the description.", "type": "string", "example": "Orders fact table", "nullable": true }, "isDescriptionSystemManaged": { "description": "Whether the table description is managed by the system (true) or the user (false). Output Mapping may overwrite a system-managed description but never a user-managed one.", "type": "boolean", "nullable": true }, "columns": { "description": "List of column definition patches (1-1000 items, each column at most once, each with at least one patch).", "type": "array", "items": { "required": [ "name" ], "properties": { "name": { "description": "Column name.", "type": "string", "example": "amount" }, "length": { "description": "Supports a numeric value for all columns (e.g. `12`) and complex length for numeric columns (e.g. `12,2`).", "type": "string", "example": "12,2" }, "nullable": { "description": "On BigQuery the operation \"set as required\" (nullable=true -> nullable=false) is not allowed.", "type": "boolean" }, "default": { "description": "Default value for the column; null unsets the default value.", "type": "string", "nullable": true }, "description": { "description": "Column description; null or an empty string clears the description.", "type": "string", "example": "Order amount", "nullable": true } }, "type": "object" } } }, "type": "object" }, "DeleteTableJobParams": { "required": [ "forceDelete", "branchId", "apiVersion" ], "properties": { "forceDelete": { "type": "boolean", "default": false }, "tableStringId": { "type": "string", "nullable": true, "default": null }, "branchId": { "type": "integer", "default": null }, "apiVersion": { "type": "string", "default": null } }, "type": "object" }, "TableEventsListRequest": { "description": "Query parameters for listing table events.", "properties": { "limit": { "description": "Maximum number of events to return.", "type": "integer", "nullable": true }, "offset": { "description": "Number of events to skip.", "type": "integer", "nullable": true }, "maxId": { "description": "Only include events with ID less than or equal to this value.", "type": "string", "nullable": true }, "sinceId": { "description": "Only include events with ID greater than this value.", "type": "string", "nullable": true }, "component": { "description": "Filter events by component.", "type": "string", "nullable": true }, "configurationId": { "description": "Filter events by configuration ID.", "type": "string", "nullable": true }, "runId": { "description": "Filter events by run ID.", "type": "string", "nullable": true }, "q": { "description": "Full-text search query to filter event data.", "type": "string", "nullable": true }, "query": { "description": "Deprecated alias of the q parameter.", "type": "string", "nullable": true, "deprecated": true }, "sortOrder": { "description": "Sort order of events. Use \"asc\" for oldest first or \"desc\" for newest first.", "type": "string", "nullable": true, "enum": [ "asc", "desc" ] } }, "type": "object" }, "SwapJobParams": { "required": [ "targetTableStringId", "branchId", "apiVersion" ], "properties": { "targetTableStringId": { "type": "string" }, "tableStringId": { "type": "string", "nullable": true, "default": null }, "branchId": { "type": "integer", "default": null }, "apiVersion": { "type": "string", "default": null } }, "type": "object" }, "TableSwapRequest": { "required": [ "targetTableId" ], "properties": { "targetTableId": { "description": "String id of the target table to swap with. Must be in the same bucket as the source table.", "type": "string", "example": "in.c-main.orders_new" } }, "type": "object" }, "TableUpdateJobParamsValues": { "description": "Table properties to update, as stored in the job operation params.", "required": [ "displayName" ], "properties": { "displayName": { "description": "New display name of the table.", "type": "string" } }, "type": "object" }, "TableUpdateJobParams": { "required": [ "values" ], "properties": { "values": { "$ref": "#/components/schemas/TableUpdateJobParamsValues" }, "tableStringId": { "type": "string", "nullable": true, "default": null }, "idBucket": { "type": "integer", "nullable": true, "default": null } }, "type": "object" }, "TableBucketResponse": { "description": "The bucket a table lives in, as embedded in table responses. Built by Model_Row_Bucket::toApiResponse() and extended with `metadata` by the table response provider. Unlike the standalone bucket detail response, `tables` here is the bucket URI, not a list of table objects, and there is no `scheduledTasks`, `listing` or `linkedBy`.", "required": [ "uri", "id", "name", "displayName", "idBranch", "stage", "description", "tables", "created", "lastChangeDate", "updated", "isReadOnly", "dataSizeBytes", "rowsCount", "isMaintenance", "backend", "sharing", "hasExternalSchema", "databaseName", "path", "isSnowflakeSharedDatabase", "isLinkedBucket", "color", "bucketSharingAllowed", "owner", "sharedByActor", "backendPath" ], "properties": { "uri": { "description": "API URI of the bucket.", "type": "string", "example": "https://connection.keboola.com/v2/storage/buckets/in.c-my-new-bucket" }, "id": { "description": "Bucket identifier (`{stage}.{name}`).", "type": "string", "example": "in.c-my-new-bucket" }, "name": { "description": "Bucket name (prefixed with `c-`).", "type": "string", "example": "c-my-new-bucket" }, "displayName": { "description": "Human-readable display name shown in the UI.", "type": "string", "example": "my-new-bucket" }, "idBranch": { "description": "ID of the branch the bucket belongs to.", "type": "integer", "example": 1234 }, "stage": { "description": "Bucket stage.", "type": "string", "example": "in", "enum": [ "in", "out", "sys" ] }, "description": { "description": "Bucket description.", "type": "string", "example": "Some Description" }, "tables": { "description": "The same URI as `uri`, kept for backward compatibility.", "type": "string", "example": "https://connection.keboola.com/v2/storage/buckets/in.c-my-new-bucket" }, "created": { "description": "Creation timestamp, ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2017-02-13T12:01:05+0100" }, "lastChangeDate": { "description": "Timestamp of the last data change in the bucket, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": null, "nullable": true }, "updated": { "description": "Timestamp of the last bucket update, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2024-11-28T13:03:13+0100", "nullable": true }, "isReadOnly": { "description": "Whether the bucket is read-only (linked or external buckets).", "type": "boolean", "example": false }, "dataSizeBytes": { "description": "Total data size in bytes.", "type": "integer", "example": 0 }, "rowsCount": { "description": "Total number of rows.", "type": "integer", "example": 0 }, "isMaintenance": { "description": "Whether the bucket is in maintenance mode.", "type": "boolean", "example": false }, "backend": { "description": "Storage backend of the bucket: `snowflake`, `bigquery` or `postgres` (external buckets); older buckets may carry another backend name.", "type": "string", "example": "snowflake" }, "sharing": { "description": "Sharing type of the bucket; `null` when the bucket is not shared.", "type": "string", "example": null, "nullable": true, "enum": [ "organization", "organization-project", "specific-projects", "specific-users", null ] }, "hasExternalSchema": { "description": "Whether the bucket is an external (registered) bucket.", "type": "boolean", "example": false }, "databaseName": { "description": "Database of a Snowflake external bucket or of a linked bucket's source; `\"\"` otherwise.", "type": "string", "example": "" }, "path": { "description": "Dot-separated path of the bucket on the backend.", "type": "string", "example": "database_name.c-my-new-bucket" }, "isSnowflakeSharedDatabase": { "description": "Whether the external bucket uses a Snowflake Secure Data Share.", "type": "boolean", "example": false }, "isLinkedBucket": { "description": "Whether this bucket is linked from another project.", "type": "boolean", "example": false }, "color": { "description": "CSS color of the bucket.", "type": "string", "example": null, "nullable": true }, "bucketSharingAllowed": { "description": "Whether the bucket can be shared.", "type": "boolean", "example": true }, "sharingParameters": { "description": "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.", "oneOf": [ { "properties": { "projects": { "description": "Present when `sharing` is `specific-projects`.", "type": "array", "items": { "required": [ "id", "name" ], "properties": { "id": { "type": "integer", "example": 321 }, "name": { "type": "string", "example": "Some Project" } }, "type": "object" } }, "users": { "description": "Present when `sharing` is `specific-users`.", "type": "array", "items": { "required": [ "id", "name", "email" ], "properties": { "id": { "type": "integer", "example": 5 }, "name": { "type": "string", "example": "Jan Developer" }, "email": { "type": "string", "example": "jan.dev@keboola.com" } }, "type": "object" } } }, "type": "object" }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "sharedBy": { "description": "Token that shared the bucket. Present only when the bucket is shared.", "required": [ "id", "name", "date" ], "properties": { "id": { "type": "integer", "format": "int64", "example": 5, "nullable": true }, "name": { "type": "string", "example": "dev@keboola.com", "nullable": true }, "date": { "description": "ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2020-02-03T14:58:29+0100" } }, "type": "object" }, "sharedByActor": { "description": "Who shared the bucket and through which credential; null when the bucket is not shared or no sharer is recorded.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "owner": { "description": "Bucket owner; `null` when no owner is set.", "required": [ "id", "name", "email" ], "properties": { "id": { "type": "integer", "example": 123 }, "name": { "type": "string", "example": "Jan Developer" }, "email": { "type": "string", "example": "jan.dev@keboola.com" } }, "type": "object", "nullable": true }, "sourceBucket": { "$ref": "#/components/schemas/SharedBucketResponse" }, "backendPath": { "description": "Full path of the bucket on the backend (e.g. database and schema).", "type": "array", "items": { "type": "string" }, "example": [ "KBC_PRJ_123", "in.c-my-new-bucket" ] }, "metadata": { "description": "Bucket metadata records. Present only in the table detail and the synchronous table update.", "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } } }, "type": "object" }, "TableUpdateResponse": { "description": "The updated table with its columns, metadata and bucket payload. Returned only by the deprecated synchronous variant of the endpoint.", "required": [ "uri", "id", "name", "displayName", "transactional", "primaryKey", "indexType", "indexKey", "distributionType", "distributionKey", "syntheticPrimaryKeyEnabled", "created", "lastImportDate", "lastChangeDate", "rowsCount", "dataSizeBytes", "isAlias", "isAliasable", "isTyped", "isDescriptionSystemManaged", "timestampType", "tableType", "path", "columns", "columnMetadata", "attributes", "metadata", "bucket" ], "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, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "lastImportDate": { "description": "Last import date, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "lastChangeDate": { "description": "Last change date, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "rowsCount": { "description": "Rows count (null for a filtered alias)", "type": "integer", "nullable": true }, "dataSizeBytes": { "description": "Data size in bytes (null for a filtered alias)", "type": "integer", "nullable": true }, "isAlias": { "description": "Is alias", "type": "boolean" }, "isAliasable": { "description": "Is aliasable", "type": "boolean" }, "isTyped": { "description": "Is typed table", "type": "boolean" }, "isDescriptionSystemManaged": { "description": "Whether the description is managed by the system", "type": "boolean" }, "timestampType": { "description": "Timestamp column type", "type": "string" }, "tableType": { "description": "Table type", "type": "string" }, "path": { "description": "Table path", "type": "string" }, "columns": { "description": "Column names", "type": "array", "items": { "type": "string" } }, "columnMetadata": { "description": "Metadata entries per column, keyed by column name", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object" } } }, "attributes": { "description": "Always an empty array, kept for backward compatibility", "type": "array", "items": { "type": "object" } }, "metadata": { "description": "Table metadata entries", "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } }, "bucket": { "$ref": "#/components/schemas/TableBucketResponse" }, "sourceTable": { "description": "Source table info. Present only for aliases with a resolved source table. Carries the source table `columnMetadata` when the alias propagates metadata.", "required": [ "id", "uri", "project" ], "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" }, "columnMetadata": { "description": "Metadata entries of the root source table, keyed by column name. Present only for an alias with column auto-sync.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object" } } } }, "type": "object" }, "aliasColumnsAutoSync": { "description": "Alias columns auto sync. Present only for simple aliases.", "type": "boolean" }, "aliasFilter": { "description": "The filter applied to the alias. Present only for filtered simple aliases.", "required": [ "column", "operator", "values" ], "properties": { "column": { "description": "Filtered column name", "type": "string" }, "operator": { "description": "Filter operator (eq or ne)", "type": "string" }, "values": { "description": "Filter values", "type": "array", "items": { "type": "string" } } }, "type": "object" }, "selectSql": { "description": "The alias SQL. Present only for custom SQL aliases.", "type": "string" }, "isPersisted": { "description": "Whether the alias is persisted. Present only for aliases.", "type": "boolean" } }, "type": "object" }, "TableUpdateRequest": { "description": "Table properties to update. The display name is the only updatable property.", "required": [ "displayName" ], "properties": { "displayName": { "description": "New display name of the table. No other table in the same bucket may already use it.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/StorageName" } ] } }, "type": "object" }, "TablesListRequest": { "properties": { "include": { "description": "Comma-separated list of data to include. Allowed values: attributes, buckets, bucketsWithoutSourceTables, columns, metadata, columnMetadata, sourceMetadata, sourceColumnMetadata. Default: attributes,buckets.", "type": "string", "nullable": true } }, "type": "object" }, "TokenCreateRequest": { "description": "Full token create request, used when the authorizing token has `canManageTokens`.", "properties": { "description": { "description": "Token description.", "type": "string", "example": "my-new-token", "nullable": true }, "bucketPermissions": { "description": "Permissions per bucket, keyed by bucket ID. Available permissions: `read`, `write`.", "type": "object", "example": { "in.c-main": "read" }, "additionalProperties": { "type": "string", "enum": [ "read", "write" ] } }, "componentAccess": { "description": "Grants access for component configurations. Allowed values are valid component IDs.", "type": "array", "items": { "type": "string" }, "example": [ "keboola.ex-db-mysql" ] }, "canManageBuckets": { "description": "Allows full access to all buckets including newly created buckets. Overrides `bucketPermissions` settings.", "type": "boolean", "default": false }, "canReadAllFileUploads": { "description": "Allows access to all file uploads. When set to false, only files uploaded by the current token are accessible.", "type": "boolean", "default": false }, "canPurgeTrash": { "description": "Allows permanently removing deleted configurations.", "type": "boolean", "default": false }, "expiresIn": { "description": "Number of seconds until the token expires. If not provided, the token never expires.", "type": "integer", "example": 60, "nullable": true, "minimum": 1 }, "canManageProtectedDefaultBranch": { "description": "[EXPERIMENTAL] If set to true, the token will have privileged access to the default branch of the project. Implicitly `false` for the read-only role. Requests using this parameter must also be authenticated with an application token with scope `storage:tokens:create-protected-default-branch-privileged`.", "type": "boolean", "default": false }, "canCreateJobs": { "description": "Token permission to create jobs. Also grants access to component configurations and development branches needed to run them. In projects with the protected default branch only the productionManager role can create such tokens. Mutually exclusive with all other permission attributes.", "type": "boolean", "default": false }, "canReadAllProjectEvents": { "description": "Allows reading all project events, not only the events of the token itself.", "type": "boolean", "default": false }, "canManageDevBranches": { "description": "Allows creating and deleting development branches.", "type": "boolean", "default": false } }, "type": "object" }, "TokenCreateLimitedRequest": { "description": "Limited token create request, used when the authorizing token does not have `canManageTokens`. Only a temporary token with minimal privileges can be created; all other attributes are ignored.", "properties": { "description": { "description": "Token description.", "type": "string", "example": "my-new-token", "nullable": true }, "expiresIn": { "description": "Number of seconds until the token expires. If not provided, the token never expires.", "type": "integer", "example": 60, "nullable": true, "minimum": 1 } }, "type": "object" }, "ShareTokenRequest": { "required": [ "recipientEmail" ], "properties": { "recipientEmail": { "description": "Recipient's email address.", "type": "string", "format": "email", "example": "martin@keboola.com" }, "message": { "description": "Message for the token recipient. Must not contain links or web addresses.", "type": "string", "example": "Hi", "nullable": true } }, "type": "object" }, "UpdateTokenRequest": { "properties": { "description": { "description": "Token description.", "type": "string", "example": "New Description", "nullable": true }, "bucketPermissions": { "description": "Permissions per bucket, keyed by bucket ID. Available permissions: `read`, `write`. All current bucket permissions are replaced.", "type": "object", "example": { "in.c-main": "write" }, "additionalProperties": { "type": "string", "enum": [ "read", "write" ] } }, "componentAccess": { "description": "Grants access for component configurations. Allowed values are valid component IDs.", "type": "array", "items": { "type": "string" }, "example": [ "keboola.ex-db-mysql" ], "nullable": true }, "canReadAllFileUploads": { "description": "Allows access to all file uploads. When set to false, only files uploaded by the current token are accessible.", "type": "boolean", "nullable": true }, "canPurgeTrash": { "description": "Allows permanently removing deleted configurations.", "type": "boolean", "nullable": true } }, "type": "object" }, "CreateTriggerRequest": { "required": [ "component", "configurationId", "coolDownPeriodMinutes", "tableIds" ], "properties": { "runWithTokenId": { "description": "ID of the token that runs the configured component. When omitted or `null`, the trigger creates a non-expiring token `[_internal] Token for triggering ` and owns it: deleting the trigger, or giving it another token, revokes that token.", "type": "integer", "example": 123, "nullable": true }, "component": { "description": "Component ID of the triggered configuration (typically `orchestration`).", "type": "string", "example": "orchestration" }, "configurationId": { "description": "ID of component configuration.", "type": "string", "example": "123" }, "coolDownPeriodMinutes": { "description": "Minimal cool down period before firing action again in minutes (min is 1 minute).", "type": "integer", "example": 20, "minimum": 1 }, "tableIds": { "description": "IDs of tables to watch (like `in.c-test.watched`).", "type": "array", "items": { "type": "string" }, "example": [ "in.c-test.watched-1", "in.c-prod.watched-5" ] } }, "type": "object" }, "FilterTriggerRequest": { "properties": { "component": { "description": "Type of component (typically `orchestration`).", "type": "string", "example": "orchestration", "nullable": true }, "configurationId": { "description": "ID of component configuration.", "type": "string", "example": "config-100", "nullable": true } }, "type": "object" }, "UpdateTriggerRequest": { "properties": { "runWithTokenId": { "description": "ID of the token that runs the configured component. Replacing the token the trigger created for itself revokes that token.", "type": "integer", "example": 100 }, "component": { "description": "Component ID of the triggered configuration (typically `orchestration`).", "type": "string", "example": "orchestration" }, "configurationId": { "description": "ID of component configuration.", "type": "string", "example": "123" }, "coolDownPeriodMinutes": { "description": "Minimal cool down period before firing action again in minutes (min is 1 minute).", "type": "integer", "example": 20, "minimum": 1 }, "tableIds": { "description": "IDs of tables to watch (like `in.c-test.watched`). Replaces the current set.", "type": "array", "items": { "type": "string" }, "example": [ "in.c-test.watched-1" ] } }, "type": "object" }, "ValidateColumnNamesRequest": { "required": [ "columnNames" ], "properties": { "columnNames": { "description": "Candidate column names to check against the `StorageColumnName` rule. The items are deliberately plain strings \u2014 an invalid candidate is the point of the call.", "type": "array", "items": { "type": "string" }, "example": [ "First$$Column-Name", "Second Column-Name" ] } }, "type": "object" }, "WebalizeColumnNameRequest": { "required": [ "columnNames" ], "properties": { "columnNames": { "description": "List of column names to webalize.", "type": "array", "items": { "type": "string" }, "example": [ "First$$Column-Name", "Second Column-Name" ] } }, "type": "object" }, "WebalizeDisplayNameRequest": { "required": [ "displayName" ], "properties": { "displayName": { "description": "Display name to webalize.", "type": "string", "example": "My$$Display-Name" } }, "type": "object" }, "InputMappingLoadRequest": { "required": [ "input" ], "properties": { "input": { "type": "array", "items": { "description": "An input-mapping table item. `source` and `destination` are required. When `where_column` is set, `where_values` must be non-empty (and vice versa). `load_type` explicitly selects the load type (COPY/CLONE/VIEW); omit it or use AUTO to let the server pick. The legacy boolean `use_view` is still accepted as an alias for `load_type: VIEW` (cannot be combined with a conflicting `load_type`).", "required": [ "source", "destination" ], "properties": { "source": { "type": "string" }, "source_branch_id": { "type": "integer" }, "destination": { "type": "string" }, "description": { "description": "Description of the workspace table; overrides the Storage description. Empty or null inherits it. Ignored for VIEW loads.", "type": "string", "nullable": true, "maxLength": 65535 }, "days": { "type": "integer", "nullable": true }, "changed_since": { "type": "string", "nullable": true }, "columns": { "type": "array", "items": { "type": "string" } }, "column_types": { "type": "array", "items": { "required": [ "source" ], "properties": { "source": { "type": "string" }, "description": { "description": "Description of the workspace column; overrides the Storage description. Empty or null inherits it. Ignored for VIEW loads.", "type": "string", "nullable": true, "maxLength": 65535 }, "type": { "type": "string" }, "destination": { "type": "string" }, "length": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "nullable": { "type": "boolean" }, "convert_empty_values_to_null": { "type": "boolean" } }, "type": "object" } }, "where_column": { "type": "string" }, "where_values": { "type": "array", "items": { "type": "string" } }, "where_operator": { "type": "string", "enum": [ "eq", "ne" ] }, "limit": { "type": "integer" }, "overwrite": { "type": "boolean" }, "load_type": { "type": "string", "enum": [ "COPY", "CLONE", "VIEW", "AUTO" ] }, "use_view": { "description": "Legacy alias for `load_type: VIEW`. Kept for backward compatibility.", "type": "boolean" }, "keep_internal_timestamp_column": { "type": "boolean" }, "incremental": { "type": "boolean" }, "file_type": { "type": "string" }, "backend": { "description": "Storage backend to evaluate this item against on the workspace-less preview endpoint (e.g. `snowflake`, `bigquery`). Takes precedence over the `backend` query parameter and the project default. Must be one of the project's assigned backends. Ignored by the workspace load endpoint, which derives the backend from the workspace.", "type": "string" } }, "type": "object" } }, "preserve": { "type": "boolean", "default": false } }, "type": "object" }, "SetWorkspacePublicKeyRequest": { "required": [ "publicKey" ], "properties": { "publicKey": { "description": "Public key in RSA format.", "type": "string" } }, "type": "object" }, "BatchDeleteRequest": { "required": [ "objects" ], "properties": { "objects": { "description": "List of workspace object names to delete.", "type": "array", "items": { "type": "string" }, "default": [] } }, "type": "object" }, "CreateWorkspaceRequest": { "properties": { "backend": { "description": "Workspace backend type.", "type": "string", "nullable": true, "enum": [ "snowflake", "bigquery", "abs" ] }, "backendSize": { "description": "Requested backend size (Snowflake only).", "type": "string", "nullable": true }, "readOnlyStorageAccess": { "description": "Enable read-only storage access.", "type": "boolean", "nullable": true }, "networkPolicy": { "description": "Network policy for the workspace.", "type": "string", "nullable": true, "enum": [ "system", "user", "not-defined" ] }, "loginType": { "description": "Preferred login type. Use \"none\" to create a workspace without credentials for QueryService. Create direct connection credentials later using the workspace credentials endpoint. Use \"governed\" (Snowflake and BigQuery, no \"publicKey\") to create a workspace that only QueryService can read: it has no login, nobody else can obtain its credentials, and password reset, public key, SSO and native query are refused. For the \"snowflake\" backend, \"default\" and \"snowflake-legacy-service\" are rejected because they resolve to password authentication, which Snowflake no longer supports; use \"snowflake-service-keypair\" or \"snowflake-person-keypair\" with \"publicKey\", or \"none\".", "type": "string", "nullable": true, "enum": [ null, "default", "snowflake-legacy-service", "snowflake-person-sso", "snowflake-person-keypair", "snowflake-service-keypair", "none", "governed" ] }, "publicKey": { "description": "RSA public key for key pair login.", "type": "string", "nullable": true }, "useCase": { "description": "Workspace use case.", "type": "string", "nullable": true, "enum": [ "normal", "reader" ] }, "configurationVersion": { "description": "Pin workspace to a specific configuration version.", "type": "integer", "nullable": true } }, "type": "object" }, "WorkspaceStorageCredentialsCreateRequest": { "properties": { "certificateLifetimeSeconds": { "description": "Lifetime of the certificate in seconds.", "type": "integer", "nullable": true } }, "type": "object" }, "WorkspaceTableExportRequest": { "description": "Request object for exporting a table from a workspace.", "required": [ "tableName", "fileName" ], "properties": { "tableName": { "description": "Name of the table to export.", "type": "string" }, "fileName": { "description": "Name of the output file.", "type": "string" }, "fileType": { "description": "Export file type (csv or parquet). Parquet writes `TIMESTAMP_LTZ` and `TIMESTAMP_TZ` columns as UTC wall-clock `TIMESTAMP_NTZ`; the original offset is not kept.", "type": "string", "nullable": true, "default": null, "enum": [ "csv", "parquet" ] }, "gzip": { "description": "Whether to gzip the exported file.", "type": "boolean", "nullable": true, "default": false } }, "type": "object" }, "CloneLoadRequest": { "required": [ "input" ], "properties": { "input": { "description": "Mappings of source tables with destinations to be cloned into the workspace.", "type": "array", "items": { "required": [ "source", "destination" ], "properties": { "source": { "description": "Full table identifier of the source table.", "type": "string", "example": "in.c-bucket.mytable" }, "sourceBranchId": { "description": "Branch ID where to load the `source` from. Defaults to the default branch.", "type": "integer", "example": 1234, "nullable": true }, "destination": { "description": "Destination table name.", "type": "string", "example": "my-table" }, "overwrite": { "description": "When `preserve` is true, duplicate tables will be overwritten.", "type": "boolean", "default": false }, "dropTimestampColumn": { "description": "When true the `_timestamp` column is removed after the table is cloned.", "type": "boolean", "default": false } }, "type": "object" } }, "preserve": { "description": "Keep existing tables in the workspace, otherwise the workspace is purged before loading.", "type": "boolean", "default": false } }, "type": "object" }, "ExecuteQueryRequest": { "required": [ "query" ], "properties": { "query": { "description": "SQL query to execute", "type": "string" } }, "type": "object" }, "TokenVerifyResponse": { "required": [ "id", "created", "refreshed", "description", "uri", "isMasterToken", "canManageBuckets", "canManageTokens", "canReadAllFileUploads", "canPurgeTrash", "canManageProtectedDefaultBranch", "canCreateJobs", "canReadAllProjectEvents", "canManageDevBranches", "expires", "isExpired", "isDisabled", "dailyCapacity", "actor", "bucketPermissions", "owner", "isBYODB", "organization" ], "properties": { "id": { "description": "Unique identifier of the token.", "type": "string", "example": "484" }, "created": { "description": "Token creation timestamp, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "refreshed": { "description": "Token last refresh timestamp, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "description": { "description": "User-provided description of the token.", "type": "string", "example": "my-new-token" }, "uri": { "description": "URI of the token detail.", "type": "string", "example": "https://connection.keboola.com/v2/storage/tokens/484" }, "isMasterToken": { "description": "Whether this is a master (admin) token.", "type": "boolean" }, "canManageBuckets": { "description": "Token permission to manage all buckets.", "type": "boolean" }, "canManageTokens": { "description": "Token permission to manage tokens.", "type": "boolean" }, "canReadAllFileUploads": { "description": "Token permission to read all file uploads.", "type": "boolean" }, "canPurgeTrash": { "description": "Token permission to permanently remove deleted configurations.", "type": "boolean" }, "canManageProtectedDefaultBranch": { "description": "Token permission to manage the protected default branch.", "type": "boolean" }, "canCreateJobs": { "description": "Token permission to create jobs.", "type": "boolean" }, "canReadAllProjectEvents": { "description": "Token permission to read all project events.", "type": "boolean" }, "canManageDevBranches": { "description": "Token permission to manage development branches.", "type": "boolean" }, "expires": { "description": "Expiration timestamp of the token, ISO 8601 with a `+hhmm` offset; null when the token never expires.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "nullable": true }, "isExpired": { "description": "Whether the token is expired.", "type": "boolean" }, "isDisabled": { "description": "Whether the token is disabled.", "type": "boolean" }, "dailyCapacity": { "description": "Daily capacity of the token.", "type": "integer", "example": 5 }, "token": { "description": "Decrypted token value. Present only when the project has a dedicated project feature enabled, the default branch is not protected and the token cannot manage the protected default branch.", "type": "string", "example": "75-12d4bfa4995694a1c956e7bb1eea0df5cc53acdb" }, "creatorToken": { "description": "Token that created this token. Present only when the token was created by another token.", "required": [ "id", "description" ], "properties": { "id": { "description": "ID of the creator token.", "type": "integer", "format": "int64", "example": 1 }, "description": { "description": "Description of the creator token.", "type": "string", "example": "dev@keboola.com" } }, "type": "object" }, "actor": { "description": "Who created this token and through which credential, not the identity of this token; null when no creator is recorded.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "componentAccess": { "description": "Component IDs the token may access. Present only when at least one component is granted.", "type": "array", "items": { "type": "string" }, "example": [ "keboola.ex-db-mysql" ] }, "bucketPermissions": { "description": "Bucket permissions keyed by bucket ID (`read`, `write` or `manage`).", "type": "object", "example": { "in.c-main": "read" }, "additionalProperties": { "type": "string" } }, "owner": { "description": "Project the token belongs to.", "required": [ "id", "name", "type", "region", "created", "expires", "features", "dataSizeBytes", "rowsCount", "hasMysql", "hasSynapse", "hasSnowflake", "hasExasol", "hasTeradata", "hasBigquery", "defaultBackend", "hasTryModeOn", "limits", "metrics", "isDisabled", "billedMonthlyPrice", "dataRetentionTimeInDays", "assignedBackends", "timezone", "isBYODB", "usersCount" ], "properties": { "id": { "type": "integer", "example": 58 }, "name": { "type": "string", "example": "Buckets 5" }, "type": { "type": "string", "example": "production" }, "region": { "type": "string", "example": "us-east-1" }, "created": { "description": "ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "expires": { "description": "ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "nullable": true }, "features": { "type": "array", "items": { "type": "string" } }, "dataSizeBytes": { "type": "integer", "example": 112128 }, "rowsCount": { "type": "integer", "example": 1036 }, "hasMysql": { "description": "Always false.", "type": "boolean" }, "hasSynapse": { "type": "boolean" }, "hasSnowflake": { "type": "boolean" }, "hasExasol": { "type": "boolean" }, "hasTeradata": { "type": "boolean" }, "hasBigquery": { "type": "boolean" }, "defaultBackend": { "type": "string", "example": "snowflake" }, "hasTryModeOn": { "type": "string", "example": "0" }, "limits": { "description": "Project limits keyed by limit name.", "type": "object", "additionalProperties": { "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "type": "integer" } }, "type": "object" } }, "metrics": { "description": "Project metrics keyed by metric name.", "type": "object", "additionalProperties": { "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "type": "integer" } }, "type": "object" } }, "isDisabled": { "type": "boolean" }, "billedMonthlyPrice": { "type": "integer", "nullable": true }, "dataRetentionTimeInDays": { "type": "integer", "example": 7 }, "assignedBackends": { "type": "array", "items": { "type": "string" }, "example": [ "snowflake" ] }, "timezone": { "description": "Project timezone; used by BigQuery projects only.", "type": "string", "nullable": true }, "isBYODB": { "type": "boolean" }, "usersCount": { "type": "integer", "example": 2 }, "fileStorageProvider": { "description": "Present only when a file storage is assigned.", "type": "string", "example": "aws" }, "payAsYouGo": { "description": "Present only for projects with the `pay-as-you-go` feature.", "required": [ "purchasedCredits" ], "properties": { "purchasedCredits": { "type": "number", "example": 123 } }, "type": "object" }, "disabled": { "description": "Present only when the project is disabled.", "required": [ "reason", "estimatedEndTime" ], "properties": { "reason": { "type": "string" }, "estimatedEndTime": { "description": "ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "nullable": true } }, "type": "object" } }, "type": "object" }, "isBYODB": { "description": "Whether the project uses a Bring Your Own Database backend. Kept for backward compatibility, same as `owner.isBYODB`.", "type": "boolean" }, "organization": { "required": [ "id", "created" ], "properties": { "id": { "description": "ID of the organization the project belongs to, as a numeric string.", "type": "string", "example": "123", "nullable": true }, "created": { "description": "Creation time of the organization. Null when the creation time is unavailable.", "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "admin": { "description": "Administrator the token belongs to. Present only when the token belongs to an administrator.", "required": [ "name", "id", "features", "isOrganizationMember", "role", "isActivated" ], "properties": { "name": { "type": "string", "example": "John Doe" }, "id": { "type": "integer", "example": 124 }, "features": { "type": "array", "items": { "type": "string" } }, "isOrganizationMember": { "type": "boolean" }, "role": { "description": "Null when the project membership has no role stored.", "type": "string", "example": "admin", "nullable": true, "enum": [ "admin", "guest", "readOnly", "share", "developer", "reviewer", "productionManager" ] }, "isActivated": { "type": "boolean" }, "samlParameters": { "description": "Raw SAML attribute statement asserted by the IdP on last login, keyed by IdP-defined attribute name (e.g. a role or group claim); attribute names and count vary per IdP configuration. Present only when SAML is enabled on the stack; an empty array `[]` when no attributes are stored.", "oneOf": [ { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, { "type": "array", "items": {}, "maxItems": 0 } ] } }, "type": "object" }, "adminOwner": { "description": "Administrator who owns the token. Present only when an owner can be resolved.", "required": [ "id", "name", "email" ], "properties": { "id": { "type": "integer", "example": 17 }, "name": { "type": "string", "example": "Username" }, "email": { "type": "string", "example": "username@keboola.com" } }, "type": "object" } }, "type": "object" }, "BucketRegisterGuideResponse": { "required": [ "markdown" ], "properties": { "markdown": { "description": "Registration guide in Markdown format.", "type": "string" } }, "type": "object" }, "BucketListItemResponse": { "description": "Bucket object as returned by the bucket list endpoint: the bucket plus the resources `include` asks for.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BucketResponse" }, { "properties": { "attributes": { "description": "Deprecated, always an empty array. Present only when `include` is omitted or contains `attributes`.", "type": "array", "items": { "type": "object" }, "example": [] }, "metadata": { "description": "Bucket metadata. Present only when `include` contains `metadata`.", "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } }, "linkedBy": { "description": "Buckets in other projects linked to this bucket. Present only when `include` contains `linkedBuckets` and the bucket is linked somewhere.", "type": "array", "items": { "properties": { "id": { "description": "ID of the linked bucket in the target project.", "type": "string", "example": "in.c-linked-bucket" }, "created": { "description": "ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2017-02-13T12:01:05+0100" }, "project": { "properties": { "id": { "type": "string", "example": "321" }, "name": { "type": "string", "example": "Some Project" } }, "type": "object" } }, "type": "object" } } } } ] }, "BucketCreateResponse": { "description": "Bucket object as returned by the create and link endpoints.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BucketResponse" }, { "required": [ "attributes" ], "properties": { "attributes": { "description": "Deprecated, always an empty array. Kept for backward compatibility.", "type": "array", "items": { "type": "object" }, "example": [] } } } ] }, "TableColumnMetadataResponse": { "description": "Column metadata of a table, keyed by column name. Built by Model_Row_MetadataTable::getTableColumnMetadataApiResponse().", "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } } }, "TableDefinitionResponse": { "description": "Native table definition, in the same shape as the create-table-from-definition endpoint. Built by Keboola\\Connection\\Storage\\Service\\Metadata\\MetadataConvertor::createTableDefinitionResponseFromMetadata() for a typed table, or ::createUntypedTableDefinitionResponseFromMetadata() for an untyped one - for an untyped table, `basetype`, `canBeFiltered`, `distribution` and `index` are never present, and each column `definition` only ever carries `description`. A storage driver may add further backend-specific keys via its extendTableDefinitionResponse() hook, e.g. BigQuery adds `timePartitioning`, `clustering`, `rangePartitioning` and `requirePartitionFilter`. For an alias with auto-synced columns (including a linked-bucket table), column types come from the root source table and table and column descriptions are resolved along the alias chain, the alias's own value first.", "required": [ "primaryKeysNames", "columns" ], "properties": { "primaryKeysNames": { "description": "Primary key column names.", "type": "array", "items": { "type": "string" } }, "columns": { "type": "array", "items": { "required": [ "name", "definition" ], "properties": { "name": { "description": "Column name.", "type": "string" }, "canBeFiltered": { "description": "Whether the column type can be used in a `where` filter. Absent for an untyped table.", "type": "boolean" }, "definition": { "description": "Column type definition. An empty object (`{}`) for an untyped column without a description.", "properties": { "type": { "description": "Backend-native column type. Absent for an untyped table.", "type": "string" }, "nullable": { "description": "Whether the column accepts NULL. Absent for an untyped table.", "type": "boolean" }, "length": { "description": "Backend-native type length/precision, for example `38,9`. Absent when not applicable.", "type": "string", "nullable": true }, "default": { "description": "Default value of the column. Absent when not set.", "type": "string", "nullable": true }, "description": { "description": "Column description.", "type": "string" } }, "type": "object" }, "basetype": { "description": "Keboola base type. Absent for an untyped table.", "type": "string", "nullable": true }, "policyTagState": { "description": "Whether Keboola knows the column to be covered by a BigQuery policy tag, as of the last time the table was reflected. `protected` - a policy tag was observed on the column; `unprotected` - the table was observed and the column carried none; `unknown` - the table has never been observed, or the column carries protection Keboola cannot state (a tag on a field inside a STRUCT, or more than one tag). Present on BigQuery tables only, typed and untyped alike; absent on every other backend.", "type": "string", "enum": [ "protected", "unprotected", "unknown" ] } }, "type": "object" } }, "description": { "description": "Table description, when set.", "type": "string" }, "distribution": { "description": "Present only when the table has a distribution type set. Absent for an untyped table.", "required": [ "type", "distributionColumnsNames" ], "properties": { "type": { "type": "string" }, "distributionColumnsNames": { "type": "array", "items": { "type": "string" } } }, "type": "object" }, "index": { "description": "Present only when the table has an index type set. Absent for an untyped table.", "required": [ "type", "indexColumnsNames" ], "properties": { "type": { "type": "string" }, "indexColumnsNames": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object", "additionalProperties": { "description": "Backend-specific keys added by the storage driver (e.g. BigQuery partitioning/clustering)." } }, "TableSourceTableResponse": { "description": "Source table of an alias, extended with the metadata that propagates from the root source table for a simple alias with column auto-sync enabled.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/SourceTableResponse" }, { "properties": { "metadata": { "description": "Metadata of the root source table. Present only for an alias with column auto-sync, in the table detail or with `include=sourceMetadata`.", "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } }, "columnMetadata": { "description": "Column metadata of the root source table, keyed by column name. Present only for an alias with column auto-sync, in the table detail or with `include=columnMetadata`/`include=sourceColumnMetadata`. An empty array `[]` in table lists when the source table has no column metadata.", "oneOf": [ { "$ref": "#/components/schemas/TableColumnMetadataResponse" }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "definition": { "$ref": "#/components/schemas/TableDefinitionResponse" } }, "type": "object" } ] }, "TableListItemResponse": { "description": "A table as returned by the table lists (`GET /tables`, `GET /buckets/{id}/tables`), and (identically) as an item of a bucket detail's `tables`. Built by Storage_Service_Metadata::getTablesResponseForApi() from Model_Row_MetadataTable::toApiResponse(); `attributes`, `columns`, `bucket`, `metadata` and `columnMetadata` are added only when requested via the endpoint's `include` parameter (`bucket` is never present inside a bucket detail's `tables`, since the containing bucket is already known there). Unlike the table detail response, there is no `definition`.", "required": [ "uri", "id", "name", "displayName", "transactional", "primaryKey", "indexType", "indexKey", "distributionType", "distributionKey", "syntheticPrimaryKeyEnabled", "created", "lastImportDate", "lastChangeDate", "rowsCount", "dataSizeBytes", "isAlias", "isAliasable", "isTyped", "isDescriptionSystemManaged", "timestampType", "tableType", "path" ], "properties": { "uri": { "description": "Table detail URI", "type": "string" }, "id": { "description": "Table identifier", "type": "string" }, "name": { "description": "Table name", "type": "string" }, "displayName": { "description": "Display name of the table", "type": "string" }, "transactional": { "description": "Transactional flag", "type": "boolean" }, "primaryKey": { "type": "array", "items": { "type": "string" } }, "indexType": { "type": "string", "nullable": true }, "indexKey": { "type": "array", "items": { "type": "string" } }, "distributionType": { "type": "string", "nullable": true }, "distributionKey": { "type": "array", "items": { "type": "string" } }, "syntheticPrimaryKeyEnabled": { "type": "boolean" }, "created": { "description": "Created timestamp, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "lastImportDate": { "description": "Last import date, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "lastChangeDate": { "description": "Last change date, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "rowsCount": { "type": "integer", "nullable": true }, "dataSizeBytes": { "type": "integer", "nullable": true }, "isAlias": { "type": "boolean" }, "isAliasable": { "type": "boolean" }, "isTyped": { "type": "boolean" }, "isDescriptionSystemManaged": { "description": "True when the table description is managed by the system.", "type": "boolean" }, "timestampType": { "description": "How the `_timestamp` column is managed.", "type": "string", "enum": [ "MANAGED", "SELFMANAGED", "NONE" ] }, "tableType": { "type": "string" }, "path": { "type": "string" }, "attributes": { "description": "Always an empty array, kept for backward compatibility. Present with `include=attributes` (the default).", "type": "array", "items": { "type": "object" } }, "columns": { "description": "Column names. Present with `include=columns`.", "type": "array", "items": { "type": "string" } }, "bucket": { "$ref": "#/components/schemas/TableBucketResponse" }, "metadata": { "description": "Table metadata records. Present with `include=metadata`.", "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } }, "columnMetadata": { "$ref": "#/components/schemas/TableColumnMetadataResponse" }, "sourceTable": { "$ref": "#/components/schemas/TableSourceTableResponse" }, "aliasColumnsAutoSync": { "description": "Present only for simple aliases.", "type": "boolean" }, "aliasFilter": { "$ref": "#/components/schemas/AliasFilterResponse" }, "selectSql": { "description": "Present only for custom SQL aliases.", "type": "string" }, "isPersisted": { "description": "Whether the alias is persisted as a table in the backend. Present only for alias tables.", "type": "boolean" } }, "type": "object" }, "ScheduledTaskResponse": { "description": "Scheduled task attached to a bucket.", "required": [ "uuid", "job", "relatedEntity", "relatedId", "cronExpression", "createdAt" ], "properties": { "uuid": { "description": "Identifier of the scheduled task.", "type": "string", "format": "uuid", "example": "0197e22b-379d-7c62-bc6d-88e50c3d0c75" }, "job": { "description": "Job the task runs.", "type": "string", "example": "bucketRefresh", "enum": [ "bucketRefresh" ] }, "relatedEntity": { "description": "Type of the entity the task is attached to.", "type": "string", "example": "bucket", "enum": [ "bucket" ] }, "relatedId": { "description": "Identifier of the related entity (bucket ID).", "type": "string", "example": "in.c-bucket-name" }, "cronExpression": { "description": "Cron expression of the schedule.", "type": "string", "example": "42 13 * * *" }, "createdAt": { "description": "Creation timestamp of the task.", "type": "string", "format": "date-time", "example": "2025-07-01T00:08:00+02:00" } }, "type": "object" }, "BigQueryBucketListingDetailResponse": { "required": [ "listingId", "subscribers" ], "properties": { "listingId": { "description": "User-defined listing ID (unique within the exchange).", "type": "string" }, "listingResourceName": { "description": "GCP listing resource name. Omitted from the response when the listing has not yet been provisioned (the async job is still running or has failed).", "type": "string" }, "subscribers": { "description": "IAM principals with subscriber access (each prefixed with `user:` or `group:`).", "type": "array", "items": { "type": "string" } } }, "type": "object" }, "SnowflakeBucketListingDetailResponse": { "required": [ "mode", "objectName" ], "properties": { "mode": { "description": "`grant`: roles in the backend's account read the bucket schema. `share`: other accounts read it through a Snowflake share.", "type": "string", "enum": [ "grant", "share" ] }, "grantees": { "description": "Grantee roles, upper case. Present only in `grant` mode.", "type": "array", "items": { "type": "string" } }, "accounts": { "description": "Consumer accounts (`.`), upper case. Present only in `share` mode.", "type": "array", "items": { "type": "string" } }, "objectName": { "description": "Quoted name of the exposed object: `\"\".\"\"` in `grant` mode, the share name in `share` mode. Null until the create job has provisioned the exposure.", "type": "string", "nullable": true } }, "type": "object" }, "BucketListingDetailResponse": { "required": [ "name", "backend", "createdAt" ], "properties": { "name": { "description": "Human-readable listing name (used as the backend listing displayName).", "type": "string" }, "description": { "description": "Listing description. Omitted from the response when not set.", "type": "string" }, "backend": { "description": "Backend of the listed bucket.", "type": "string", "enum": [ "bigquery", "snowflake" ] }, "bigquery": { "$ref": "#/components/schemas/BigQueryBucketListingDetailResponse" }, "snowflake": { "$ref": "#/components/schemas/SnowflakeBucketListingDetailResponse" }, "createdAt": { "description": "Listing creation timestamp.", "type": "string", "format": "date-time" } }, "type": "object" }, "BucketDetailResponse": { "description": "Bucket detail: the bucket object extended with metadata, tables, scheduled tasks, listing and links.", "required": [ "uri", "id", "name", "displayName", "idBranch", "stage", "description", "tables", "created", "lastChangeDate", "updated", "isReadOnly", "dataSizeBytes", "rowsCount", "isMaintenance", "backend", "sharing", "hasExternalSchema", "databaseName", "path", "isSnowflakeSharedDatabase", "isLinkedBucket", "color", "bucketSharingAllowed", "owner", "sharedByActor", "backendPath", "attributes", "metadata", "scheduledTasks", "listing" ], "properties": { "uri": { "description": "API URI of the bucket.", "type": "string", "example": "https://connection.keboola.com/v2/storage/buckets/in.c-my-new-bucket" }, "id": { "description": "Bucket identifier (`{stage}.{name}`).", "type": "string", "example": "in.c-my-new-bucket" }, "name": { "description": "Bucket name (prefixed with `c-`).", "type": "string", "example": "c-my-new-bucket" }, "displayName": { "description": "Human-readable display name shown in the UI.", "type": "string", "example": "my-new-bucket" }, "idBranch": { "description": "ID of the branch the bucket belongs to.", "type": "integer", "example": 1234 }, "stage": { "description": "Bucket stage.", "type": "string", "example": "in", "enum": [ "in", "out", "sys" ] }, "description": { "description": "Bucket description.", "type": "string", "example": "Some Description" }, "tables": { "description": "Tables in the bucket. Each item is a table object as returned by the table list; columns, metadata and column metadata are added according to `include`.", "type": "array", "items": { "$ref": "#/components/schemas/TableListItemResponse" } }, "created": { "description": "Creation timestamp, ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2017-02-13T12:01:05+0100" }, "lastChangeDate": { "description": "Timestamp of the last data change in the bucket, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": null, "nullable": true }, "updated": { "description": "Timestamp of the last bucket update, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2024-11-28T13:03:13+0100", "nullable": true }, "isReadOnly": { "description": "Whether the bucket is read-only (linked or external buckets).", "type": "boolean", "example": false }, "dataSizeBytes": { "description": "Total data size in bytes.", "type": "integer", "example": 0 }, "rowsCount": { "description": "Total number of rows.", "type": "integer", "example": 0 }, "isMaintenance": { "description": "Whether the bucket is in maintenance mode.", "type": "boolean", "example": false }, "backend": { "description": "Storage backend of the bucket: `snowflake`, `bigquery` or `postgres` (external buckets); older buckets may carry another backend name.", "type": "string", "example": "snowflake" }, "sharing": { "description": "Sharing type of the bucket; `null` when the bucket is not shared.", "type": "string", "example": null, "nullable": true, "enum": [ "organization", "organization-project", "specific-projects", "specific-users", null ] }, "hasExternalSchema": { "description": "Whether the bucket is an external (registered) bucket.", "type": "boolean", "example": false }, "databaseName": { "description": "Database of a Snowflake external bucket or of a linked bucket's source; `\"\"` otherwise.", "type": "string", "example": "" }, "path": { "description": "Dot-separated path of the bucket on the backend.", "type": "string", "example": "database_name.c-my-new-bucket" }, "isSnowflakeSharedDatabase": { "description": "Whether the external bucket uses a Snowflake Secure Data Share.", "type": "boolean", "example": false }, "isLinkedBucket": { "description": "Whether this bucket is linked from another project.", "type": "boolean", "example": false }, "color": { "description": "CSS color of the bucket.", "type": "string", "example": null, "nullable": true }, "bucketSharingAllowed": { "description": "Whether the bucket can be shared.", "type": "boolean", "example": true }, "sharingParameters": { "description": "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.", "oneOf": [ { "properties": { "projects": { "description": "Present when `sharing` is `specific-projects`.", "type": "array", "items": { "required": [ "id", "name" ], "properties": { "id": { "type": "integer", "example": 321 }, "name": { "type": "string", "example": "Some Project" } }, "type": "object" } }, "users": { "description": "Present when `sharing` is `specific-users`.", "type": "array", "items": { "required": [ "id", "name", "email" ], "properties": { "id": { "type": "integer", "example": 5 }, "name": { "type": "string", "example": "Jan Developer" }, "email": { "type": "string", "example": "jan.dev@keboola.com" } }, "type": "object" } } }, "type": "object" }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "sharedBy": { "description": "Token that shared the bucket. Present only when the bucket is shared.", "required": [ "id", "name", "date" ], "properties": { "id": { "type": "integer", "format": "int64", "example": 5, "nullable": true }, "name": { "type": "string", "example": "dev@keboola.com", "nullable": true }, "date": { "description": "ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2020-02-03T14:58:29+0100" } }, "type": "object" }, "sharedByActor": { "description": "Who shared the bucket and through which credential; null when the bucket is not shared or no sharer is recorded.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "owner": { "description": "Bucket owner; `null` when no owner is set.", "required": [ "id", "name", "email" ], "properties": { "id": { "type": "integer", "example": 123 }, "name": { "type": "string", "example": "Jan Developer" }, "email": { "type": "string", "example": "jan.dev@keboola.com" } }, "type": "object", "nullable": true }, "sourceBucket": { "$ref": "#/components/schemas/SharedBucketResponse" }, "backendPath": { "description": "Full path of the bucket on the backend (e.g. database and schema); `[]` on backends without one.", "type": "array", "items": { "type": "string" }, "example": [ "KBC_PRJ_123", "in.c-my-new-bucket" ] }, "attributes": { "description": "Deprecated, always an empty array. Kept for backward compatibility.", "type": "array", "items": { "type": "object" }, "example": [] }, "metadata": { "description": "Bucket metadata records.", "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } }, "scheduledTasks": { "description": "Scheduled tasks (e.g. scheduled refresh of an external bucket).", "type": "array", "items": { "$ref": "#/components/schemas/ScheduledTaskResponse" } }, "listing": { "oneOf": [ { "$ref": "#/components/schemas/BucketListingDetailResponse" } ], "nullable": true, "description": "Bucket exposure (an Analytics Hub listing on BigQuery, grants or a share on Snowflake). Null when the bucket is not exposed." }, "linkedBy": { "description": "Buckets in other projects linked to this bucket. Present only when the bucket is shared and linked somewhere.", "type": "array", "items": { "required": [ "id", "created", "project" ], "properties": { "id": { "description": "ID of the linked bucket in the target project.", "type": "string", "example": "in.c-linked-bucket" }, "created": { "description": "ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2017-02-13T12:01:05+0100" }, "project": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "321" }, "name": { "type": "string", "example": "Some Project" } }, "type": "object" } }, "type": "object" } } }, "type": "object" }, "BucketEventAttachmentResponse": { "required": [ "id", "isSliced", "uploadType", "isExpired", "created", "name", "url", "sizeBytes" ], "properties": { "id": { "description": "Attachment file ID.", "type": "integer" }, "isSliced": { "description": "Whether the file is sliced.", "type": "boolean" }, "uploadType": { "description": "Upload type of the file.", "type": "string" }, "isExpired": { "description": "Whether the file is expired.", "type": "boolean" }, "created": { "description": "Attachment creation timestamp, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100" }, "name": { "description": "Attachment file name.", "type": "string" }, "url": { "description": "Attachment download URL.", "type": "string" }, "sizeBytes": { "description": "Attachment file size in bytes; `null` for a 0-byte file or when the size is unknown.", "type": "integer", "nullable": true } }, "type": "object" }, "BucketEventResponse": { "required": [ "uuid", "event", "message", "description", "type", "component", "runId", "configurationId", "objectId", "objectName", "objectType", "idBranch", "token", "context", "created", "uri", "params", "results", "performance", "attachments" ], "properties": { "uuid": { "description": "Unique identifier of the event.", "type": "string" }, "event": { "description": "Name of the event.", "type": "string" }, "message": { "description": "Event message.", "type": "string" }, "description": { "description": "Event description.", "type": "string" }, "type": { "description": "Type of the event.", "type": "string", "example": "info", "enum": [ "info", "success", "warn", "error" ] }, "component": { "description": "Component name.", "type": "string" }, "runId": { "description": "Run ID of the event.", "type": "string", "nullable": true }, "configurationId": { "description": "Configuration ID associated with the event.", "type": "string", "nullable": true }, "objectId": { "description": "ID of the object the event relates to.", "type": "string" }, "objectName": { "description": "Name of the object the event relates to.", "type": "string" }, "objectType": { "description": "Type of the object the event relates to.", "type": "string" }, "idBranch": { "description": "ID of the branch the event belongs to.", "type": "integer", "nullable": true }, "token": { "description": "Token that produced the event.", "required": [ "id", "name" ], "properties": { "id": { "description": "Token ID.", "type": "integer" }, "name": { "description": "Token name.", "type": "string", "nullable": true } }, "type": "object" }, "context": { "description": "Context the event was created in. Which keys are present depends on where the event was raised; `[]` when the event carries no context.", "oneOf": [ { "properties": { "httpUserAgent": { "description": "User agent of the request.", "type": "string", "nullable": true }, "authorization": { "description": "Authorization type of the request.", "type": "string" }, "httpUserAgentOriginal": { "description": "Original user agent of the request. Present only when the request sent `X-User-Agent`.", "type": "string", "nullable": true }, "httpReferer": { "description": "Referer of the request.", "type": "string", "nullable": true }, "remoteAddr": { "description": "Remote address of the request.", "type": "string", "nullable": true }, "apiVersion": { "description": "API version of the request or of the job that raised the event.", "type": "string" }, "userAgent": { "description": "User agent of the request that created the job. Present only on events raised by a job.", "type": "string" }, "async": { "description": "Always `true`. Present only on events raised by a job.", "type": "boolean" }, "networkPolicy": { "description": "Network policy of the workspace. Present only on workspace events.", "type": "string", "nullable": true }, "workspaceUsageType": { "description": "Usage type of the workspace. Present only on workspace events.", "type": "string", "nullable": true }, "schemaName": { "description": "Schema of the workspace. Present only on the system event a workspace deletion raises.", "type": "string", "nullable": true } }, "type": "object" }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "created": { "description": "Event creation timestamp, ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2017-02-13T12:01:05+0100" }, "uri": { "description": "Link to the event details.", "type": "string" }, "params": { "description": "Event parameters.", "type": "object" }, "results": { "description": "Event results.", "type": "object" }, "performance": { "description": "Event performance metrics.", "type": "object" }, "attachments": { "description": "Files attached to the event.", "type": "array", "items": { "$ref": "#/components/schemas/BucketEventAttachmentResponse" } } }, "type": "object" }, "BucketEventsListResponse": { "type": "array", "items": { "$ref": "#/components/schemas/BucketEventResponse" } }, "CreateTableSyncResponse": { "description": "Detail of the created table extended with the parent bucket detail.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TableCreateResponse" }, { "required": [ "columns", "bucket" ], "properties": { "bucket": { "$ref": "#/components/schemas/TableBucketResponse" } }, "type": "object" } ] }, "BucketOwnerDetailResponse": { "required": [ "id", "name", "email" ], "properties": { "id": { "description": "Owner identifier.", "type": "integer" }, "name": { "description": "Owner name.", "type": "string" }, "email": { "description": "Owner email address.", "type": "string" } }, "type": "object" }, "BucketListingSubscriptionResponse": { "required": [ "consumerProject", "linkedDataset", "organization", "subscriberContact", "state", "createdAt", "lastModifiedAt" ], "properties": { "consumerProject": { "description": "GCP project the subscriber created the linked dataset in.", "required": [ "id", "number" ], "properties": { "id": { "description": "Readable GCP project ID. Analytics Hub reports it only when the subscription was created through the API, so it can be null.", "type": "string", "nullable": true }, "number": { "description": "GCP project number. Always present.", "type": "string" } }, "type": "object" }, "linkedDataset": { "description": "Dataset the subscriber reads through. This is what is left behind as an unusable linked dataset when the exposure is deleted.", "type": "string", "nullable": true }, "organization": { "description": "GCP organization owning the consumer project.", "required": [ "id", "displayName" ], "properties": { "id": { "type": "string", "nullable": true }, "displayName": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "subscriberContact": { "description": "Email address of the subscriber, as reported by Analytics Hub.", "type": "string", "nullable": true }, "state": { "description": "Subscription state. Only `active` subscriptions can read the data.", "type": "string", "enum": [ "active", "stale", "inactive", "unspecified" ] }, "createdAt": { "type": "string", "format": "date-time" }, "lastModifiedAt": { "type": "string", "format": "date-time" }, "consumerProjectId": { "type": "string", "nullable": true }, "consumerProjectNumber": { "title": "A provider-side read renders the consumer as `projects/{number}/locations/{loc}/subscriptions/{id}`,\nnever as a project ID.", "type": "string" }, "organizationId": { "type": "string", "nullable": true }, "organizationDisplayName": { "type": "string", "nullable": true } }, "type": "object" }, "BucketListingSnowflakeMemberResponse": { "required": [ "name", "status", "grants", "missingGrants" ], "properties": { "name": { "description": "Role name in grant mode.", "type": "string" }, "status": { "description": "`active`: listed in the exposure and holds every grant. `missing`: listed but lacks at least one grant, see `missingGrants`; a role that no longer exists lacks all of them, and so does every grantee while the create job is still pending (`objectName` is null). `pendingRemoval`: no longer listed, still holds grants because an earlier update or delete failed; the next update or delete of the exposure revokes them. `external`: never listed, holds grants given outside the exposure, which Keboola does not revoke.", "type": "string", "enum": [ "active", "missing", "pendingRemoval", "external" ] }, "grants": { "description": "Schema-level grants of the exposure the role holds. Grants on single tables and views are not read.", "type": "array", "items": { "type": "string", "enum": [ "USAGE ON SCHEMA", "SELECT ON FUTURE TABLES", "SELECT ON FUTURE VIEWS" ] } }, "missingGrants": { "description": "Grants a listed role lacks. Empty for every status but `missing`.", "type": "array", "items": { "type": "string", "enum": [ "USAGE ON SCHEMA", "SELECT ON FUTURE TABLES", "SELECT ON FUTURE VIEWS" ] } } }, "type": "object" }, "BucketListingSnowflakeMembersResponse": { "required": [ "mode", "objectName", "members" ], "properties": { "mode": { "type": "string", "enum": [ "grant", "share" ] }, "objectName": { "description": "As in the exposure detail; null until the create job finishes. The members are read either way.", "type": "string", "nullable": true }, "members": { "description": "The roles listed in the exposure, then the roles it no longer lists that still hold grants, then the other roles holding the same grants. Roles managed by Keboola are left out.", "type": "array", "items": { "$ref": "#/components/schemas/BucketListingSnowflakeMemberResponse" } } }, "type": "object" }, "BucketListingSubscriptionsResponse": { "required": [ "subscriptions" ], "properties": { "subscriptions": { "description": "Consumers that currently subscribe to the bucket exposure. Read live from the backend, so the list reflects the state at request time. Always empty for a Snowflake exposure, which has no subscriptions; see `snowflake`.", "type": "array", "items": { "$ref": "#/components/schemas/BucketListingSubscriptionResponse" } }, "snowflake": { "$ref": "#/components/schemas/BucketListingSnowflakeMembersResponse" } }, "type": "object" }, "ProjectBucketListingResponse": { "required": [ "bucketId", "name", "backend", "createdAt" ], "properties": { "bucketId": { "description": "Identifier of the bucket the listing is attached to.", "type": "string" }, "name": { "description": "Human-readable listing name (used as the backend listing displayName).", "type": "string" }, "description": { "description": "Listing description. Present only when one is set.", "type": "string" }, "backend": { "description": "Backend of the listed bucket.", "type": "string", "enum": [ "bigquery", "snowflake" ] }, "bigquery": { "$ref": "#/components/schemas/BigQueryBucketListingDetailResponse" }, "snowflake": { "$ref": "#/components/schemas/SnowflakeBucketListingDetailResponse" }, "createdAt": { "description": "Listing creation timestamp.", "type": "string", "format": "date-time" } }, "type": "object" }, "BucketShareDeleteResponse": { "required": [ "id", "status", "url", "tableId", "operationName", "operationParams", "createdTime", "startTime", "endTime", "runId", "results", "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.", "required": [ "id", "description" ], "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. Present only when the job failed.", "required": [ "code", "message", "exceptionId" ], "properties": { "code": { "description": "Error code if job failed.", "type": "string" }, "message": { "description": "Error message if job failed.", "type": "string" }, "exceptionId": { "description": "Exception identifier.", "type": "string" } }, "type": "object" } }, "type": "object" }, "BucketShareOrganizationResponse": { "required": [ "id", "status", "url", "tableId", "operationName", "operationParams", "createdTime", "startTime", "endTime", "runId", "results", "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.", "required": [ "id", "description" ], "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. Present only when the job failed.", "required": [ "code", "message", "exceptionId" ], "properties": { "code": { "description": "Error code if job failed.", "type": "string" }, "message": { "description": "Error message if job failed.", "type": "string" }, "exceptionId": { "description": "Exception identifier.", "type": "string" } }, "type": "object" } }, "type": "object" }, "BucketShareOrganizationProjectResponse": { "required": [ "id", "status", "url", "tableId", "operationName", "operationParams", "createdTime", "startTime", "endTime", "runId", "results", "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.", "required": [ "id", "description" ], "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. Present only when the job failed.", "required": [ "code", "message", "exceptionId" ], "properties": { "code": { "description": "Error code if job failed.", "type": "string" }, "message": { "description": "Error message if job failed.", "type": "string" }, "exceptionId": { "description": "Exception identifier.", "type": "string" } }, "type": "object" } }, "type": "object" }, "ColumnDefinitionResponse": { "description": "The part of a column definition that changes how data loads into the column. Default value and description are not part of it.", "required": [ "type", "length", "nullable" ], "properties": { "type": { "description": "Backend data type as stored, for example `NUMBER` on Snowflake or `NUMERIC` on BigQuery.", "type": "string", "example": "NUMBER" }, "length": { "description": "Length or precision as stored; `null` when none is set.", "type": "string", "example": "10,2", "nullable": true }, "nullable": { "description": "Whether the column accepts `NULL`; `true` when not stored.", "type": "boolean" } }, "type": "object" }, "TableChangeColumnResponse": { "description": "A column of one side of the comparison.", "required": [ "name", "definition" ], "properties": { "name": { "description": "Column name exactly as stored on that side. Names are matched byte for byte, so a column whose name differs only in case is reported as removed and added.", "type": "string", "example": "tax_rate" }, "definition": { "oneOf": [ { "$ref": "#/components/schemas/ColumnDefinitionResponse" } ], "nullable": true, "description": "`null` for every column of an untyped table, and for a column of a typed table whose type is not recorded." } }, "type": "object" }, "ColumnOrderChangeResponse": { "description": "The column order of both sides. Reported when a column present on both sides is at a different position: columns appended at the end of the branch table do not count, a column removed from the middle does, because every column after it moves.", "required": [ "production", "branch", "columns" ], "properties": { "production": { "description": "All production column names in production order, removed columns included.", "type": "array", "items": { "type": "string" }, "example": [ "id", "name", "sku", "old_price", "amount", "category" ] }, "branch": { "description": "All branch column names in branch order, added columns included.", "type": "array", "items": { "type": "string" }, "example": [ "id", "sku", "name", "amount", "category", "tax_rate" ] }, "columns": { "description": "Every column of either side with its position on each side: shared and added columns in branch order, then removed columns in production order.", "type": "array", "items": { "required": [ "name", "productionPosition", "branchPosition" ], "properties": { "name": { "description": "Column name.", "type": "string" }, "productionPosition": { "description": "1-based position of the column in production; `null` when the column is not in production.", "type": "integer", "nullable": true }, "branchPosition": { "description": "1-based position of the column in the branch; `null` when the column is not in the branch.", "type": "integer", "nullable": true } }, "type": "object" } } }, "type": "object" }, "TableSchemaChangesResponse": { "description": "How the branch table differs from production. All five keys are always present: a list is empty and an object is `null` when that kind of change is absent.", "required": [ "addedColumns", "removedColumns", "typeChangedColumns", "primaryKey", "columnOrder" ], "properties": { "addedColumns": { "description": "Columns in the branch and not in production, in branch order, with the branch definition.", "type": "array", "items": { "$ref": "#/components/schemas/TableChangeColumnResponse" } }, "removedColumns": { "description": "Columns in production and not in the branch, in production order, with the production definition.", "type": "array", "items": { "$ref": "#/components/schemas/TableChangeColumnResponse" } }, "typeChangedColumns": { "description": "Columns on both sides whose `type`, `length` or `nullable` differs, in branch order. When only one side has a definition, the other side is `null`.", "type": "array", "items": { "required": [ "name", "production", "branch" ], "properties": { "name": { "description": "Column name.", "type": "string" }, "production": { "oneOf": [ { "$ref": "#/components/schemas/ColumnDefinitionResponse" } ], "nullable": true, "description": "Production definition; `null` when production has none." }, "branch": { "oneOf": [ { "$ref": "#/components/schemas/ColumnDefinitionResponse" } ], "nullable": true, "description": "Branch definition; `null` when the branch has none." } }, "type": "object" } }, "primaryKey": { "description": "Primary-key column names of each side in stored order; `null` when the two ordered lists are equal.", "required": [ "production", "branch" ], "properties": { "production": { "type": "array", "items": { "type": "string" } }, "branch": { "type": "array", "items": { "type": "string" } } }, "type": "object", "nullable": true }, "columnOrder": { "oneOf": [ { "$ref": "#/components/schemas/ColumnOrderChangeResponse" } ], "nullable": true, "description": "`null` unless the column order changed and the column positions are known on both sides." } }, "type": "object" }, "TableChangeResponse": { "description": "A table of the development branch that is new or modified compared with production. A `new` entry carries the full branch schema in `columns` and `primaryKey`; a `modified` entry carries the differences in `changes`.", "required": [ "id", "name", "displayName", "bucket", "changeType", "isTyped", "summary" ], "properties": { "id": { "description": "Table ID, the same on both sides.", "type": "string", "example": "in.c-sales.products" }, "name": { "description": "Table name in the branch.", "type": "string" }, "displayName": { "description": "Table display name in the branch.", "type": "string" }, "bucket": { "description": "The bucket of the branch table.", "required": [ "id", "name", "displayName" ], "properties": { "id": { "type": "string", "example": "in.c-sales" }, "name": { "type": "string", "example": "c-sales" }, "displayName": { "type": "string", "example": "sales" } }, "type": "object" }, "changeType": { "description": "`new` when production has no table with this ID, `modified` when the schemas differ. `deleted` is reserved for a later version and never returned by this one.", "type": "string", "enum": [ "new", "modified", "deleted" ] }, "isTyped": { "description": "Whether the branch table is typed. When only one side is typed, every shared column with a definition on the typed side is in `changes.typeChangedColumns`, with `null` on the untyped side.", "type": "boolean" }, "summary": { "description": "Counts derived from the changes. For a `new` table `addedColumns` is its column count and the rest is zero or false.", "required": [ "addedColumns", "removedColumns", "typeChangedColumns", "primaryKeyChanged", "columnOrderChanged" ], "properties": { "addedColumns": { "type": "integer" }, "removedColumns": { "type": "integer" }, "typeChangedColumns": { "type": "integer" }, "primaryKeyChanged": { "type": "boolean" }, "columnOrderChanged": { "type": "boolean" } }, "type": "object" }, "columns": { "description": "Present for `new` only: every column of the branch table in branch order.", "type": "array", "items": { "$ref": "#/components/schemas/TableChangeColumnResponse" } }, "primaryKey": { "description": "Present for `new` only: the primary-key column names of the branch table in stored order.", "type": "array", "items": { "type": "string" } }, "changes": { "description": "Present for `modified` only.", "allOf": [ { "$ref": "#/components/schemas/TableSchemaChangesResponse" } ] } }, "type": "object" }, "TableChangesListResponse": { "description": "Tables of the development branch that are new or modified compared with production as it is now, ordered by table ID. Tables whose schema is equal on both sides, and tables that cannot be compared, are omitted.", "required": [ "tables" ], "properties": { "tables": { "type": "array", "items": { "$ref": "#/components/schemas/TableChangeResponse" } } }, "type": "object" }, "ComponentArrayRead": { "description": "Component array read model that represents a component with its configuration and metadata.", "required": [ "id", "type", "name", "description", "longDescription", "version", "complexity", "categories", "hasUI", "hasRun", "ico32", "ico64", "ico128", "data", "flags", "configurationSchema", "configurationRowSchema", "emptyConfiguration", "emptyConfigurationRow", "createConfigurationRowSchema", "uiOptions", "configurationDescription", "features", "expiredOn", "dataTypesConfiguration", "processorConfiguration", "uri" ], "properties": { "id": { "description": "Unique identifier of the component", "type": "string", "example": "keboola.ex-db-mysql" }, "type": { "description": "Type of the component as the Developer Portal reports it, e.g. `extractor`, `writer`, `application` or `transformation`", "type": "string", "example": "extractor" }, "name": { "description": "Display name of the component", "type": "string", "example": "MySQL Database Extractor" }, "description": { "description": "Short description of the component", "type": "string", "example": "Extracts data from MySQL database" }, "longDescription": { "description": "Detailed description of the component", "type": "string", "nullable": true }, "version": { "description": "Version number of the component", "type": "integer", "example": 2 }, "complexity": { "description": "Complexity level of the component", "type": "string", "nullable": true, "enum": [ "low", "medium", "high" ] }, "categories": { "description": "List of component categories", "type": "array", "items": { "type": "string" }, "example": [ "extractor", "database" ] }, "hasUI": { "description": "Whether the component has a user interface", "type": "boolean" }, "hasRun": { "description": "Whether the component can be run", "type": "boolean" }, "ico32": { "description": "32x32 icon URL", "type": "string", "nullable": true }, "ico64": { "description": "64x64 icon URL", "type": "string", "nullable": true }, "ico128": { "description": "128x128 icon URL", "type": "string", "nullable": true }, "data": { "description": "Additional component data. `\"\"` when the stored JSON is invalid, `null` or a boolean; a legacy value stored as a JSON array or string is returned as is.", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} }, { "type": "string" } ] }, "flags": { "description": "List of component flags", "type": "array", "items": { "type": "string" } }, "configurationSchema": { "description": "JSON schema of the component configuration; an empty array `[]` when the stored JSON is empty.", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "configurationRowSchema": { "description": "JSON schema of the component configuration row; an empty array `[]` when the stored JSON is empty.", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "emptyConfiguration": { "description": "Default empty configuration; an empty array `[]` when the stored JSON is empty.", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "emptyConfigurationRow": { "description": "Default empty configuration row; an empty array `[]` when the stored JSON is empty.", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "createConfigurationRowSchema": { "description": "JSON schema for creating a new configuration row; an empty array `[]` when the stored JSON is empty.", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "uiOptions": { "description": "UI customization options; an empty array `[]` when the stored JSON is empty.", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "configurationDescription": { "description": "Description of the configuration structure", "type": "string", "nullable": true }, "features": { "description": "List of component features", "type": "array", "items": { "type": "string" } }, "expiredOn": { "description": "Date when the component expires, ISO 8601 with a `+hhmm` offset", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "uri": { "description": "URI of the component", "type": "string", "example": "https://connection.keboola.com/v2/storage/components/keboola.ex-db-mysql", "nullable": true }, "documentationUrl": { "description": "URL to the component documentation. Present only when the component has one.", "type": "string" }, "dataTypesConfiguration": { "description": "Configuration for data types. With none stored: `{}` from the component detail and list, `null` from the index; an empty array `[]` when the stored JSON is empty.", "oneOf": [ { "properties": { "dataTypesSupport": { "type": "string", "example": "none" } }, "type": "object", "nullable": true, "additionalProperties": true }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "processorConfiguration": { "description": "Configuration for processors. With none stored: `{}` from the component detail and list, `null` from the index; an empty array `[]` when the stored JSON is empty.", "oneOf": [ { "properties": { "allowedProcessorPosition": { "type": "string", "example": "any" } }, "type": "object", "nullable": true, "additionalProperties": true }, { "type": "array", "items": {}, "maxItems": 0 } ] } }, "type": "object" }, "ConfigurationCreatorTokenResponse": { "required": [ "id", "description" ], "properties": { "id": { "description": "Id of the token that created the object or version.", "type": "integer", "format": "int64", "example": 27978 }, "description": { "description": "Description of the token (typically the user e-mail).", "type": "string", "example": "dev@keboola.com", "nullable": true } }, "type": "object" }, "ConfigurationRowInConfigurationResponse": { "description": "Configuration row as embedded in a configuration response.", "required": [ "id", "name", "description", "isDisabled", "version", "created", "creatorToken", "actor", "changeDescription", "versionIdentifier" ], "properties": { "id": { "description": "Row id.", "type": "string", "example": "row1" }, "name": { "description": "Row name.", "type": "string", "example": "First row" }, "description": { "description": "Row description.", "type": "string", "example": "" }, "isDisabled": { "description": "Whether the row is disabled.", "type": "boolean", "example": false }, "version": { "description": "Current row version number.", "type": "integer", "example": 1 }, "created": { "description": "When the row was created, ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2017-02-13T12:01:05+0100" }, "creatorToken": { "$ref": "#/components/schemas/ConfigurationCreatorTokenResponse" }, "actor": { "description": "Who created it and through which credential; null only when no creator is recorded.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "changeDescription": { "description": "Change description of the current row version.", "type": "string", "example": "Row created", "nullable": true }, "versionIdentifier": { "description": "ULID uniquely identifying the current row version.", "type": "string", "example": "01H2W8N0ZJJB6V126C8ZSND28N", "nullable": true }, "state": { "description": "Row state data. Present only when `state` is included. `\"\"` when the stored JSON is invalid, `null` or a boolean; a legacy value stored as a JSON array or string is returned as is.", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} }, { "type": "string" } ] }, "configuration": { "description": "Row configuration data. Present only when `configuration` is included. `\"\"` when the stored JSON is invalid, `null` or a boolean; a legacy value stored as a JSON array or string is returned as is.", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} }, { "type": "string" } ] } }, "type": "object" }, "ConfigurationCurrentVersionResponse": { "description": "Metadata of the current (head) version of the configuration.", "required": [ "created", "creatorToken", "actor", "changeDescription", "versionIdentifier" ], "properties": { "created": { "description": "When the current version was created, ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2017-02-13T12:01:05+0100" }, "creatorToken": { "$ref": "#/components/schemas/ConfigurationCreatorTokenResponse" }, "actor": { "description": "Who created it and through which credential; null only when no creator is recorded.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "changeDescription": { "description": "Change description of the current version.", "type": "string", "example": "Initial configuration", "nullable": true }, "versionIdentifier": { "description": "ULID uniquely identifying the current version across branches.", "type": "string", "example": "01H2W7DAN0QT78NZQ2BD2BZT4S", "nullable": true } }, "type": "object" }, "ConfigurationPartialResponse": { "description": "Component configuration as returned by create, restore and the components list. `configuration`, `state`, `rowsSortOrder` and `rows` are present only when the endpoint includes them: create includes `configuration` and `state`; restore includes none; the components list follows its `include`.", "required": [ "id", "name", "description", "created", "creatorToken", "actor", "version", "changeDescription", "isDisabled", "isDeleted", "folder", "folderUpdated", "currentVersion" ], "properties": { "id": { "description": "Configuration id, unique within the component.", "type": "string", "example": "236606822" }, "name": { "description": "Configuration name.", "type": "string", "example": "My new configuration" }, "description": { "description": "Configuration description.", "type": "string", "example": "" }, "created": { "description": "When the configuration was created, ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2017-02-13T12:01:05+0100" }, "creatorToken": { "required": [ "id", "description" ], "properties": { "id": { "description": "Id of the token that created the configuration.", "type": "integer", "format": "int64", "example": 27978 }, "description": { "description": "Description of the token (typically the user e-mail).", "type": "string", "example": "dev@keboola.com" } }, "type": "object" }, "actor": { "description": "Who created it and through which credential; null only when no creator is recorded.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "version": { "description": "Current version number. Use it as the `If-Match` precondition for update, delete and purge.", "type": "integer", "example": 1 }, "changeDescription": { "description": "Change description of the current version.", "type": "string", "example": "Initial configuration", "nullable": true }, "isDisabled": { "description": "Whether the configuration is disabled.", "type": "boolean", "example": false }, "isDeleted": { "description": "Whether the configuration is in the trash.", "type": "boolean", "example": false }, "folder": { "description": "Folder the configuration is grouped under; `null` when it is in none.", "type": "string", "example": "Marketing", "nullable": true, "maxLength": 400 }, "folderUpdated": { "description": "When the folder was last written (set, cleared, copied to a branch or merged), ISO 8601 with a `+hhmm` offset; `null` when the configuration has no folder. Read-only.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "configuration": { "description": "Configuration data, arbitrary object defined by the component. `\"\"` when the stored JSON is invalid, `null` or a boolean; a legacy value stored as a JSON array or string is returned as is.", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} }, { "type": "string" } ] }, "rowsSortOrder": { "description": "Row ids in the desired order; empty when the default order (by id) applies.", "type": "array", "items": { "type": "string" } }, "rows": { "description": "Configuration rows (not deleted ones).", "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationRowInConfigurationResponse" } }, "state": { "description": "Configuration state data, arbitrary object. `\"\"` when the stored JSON is invalid, `null` or a boolean; a legacy value stored as a JSON array or string is returned as is.", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} }, { "type": "string" } ] }, "currentVersion": { "$ref": "#/components/schemas/ConfigurationCurrentVersionResponse" } }, "type": "object" }, "ComponentWithConfigurationsResponse": { "description": "Component definition with the project configurations of that component.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ComponentArrayRead" }, { "required": [ "configurations" ], "properties": { "configurations": { "description": "Configurations of the component in the project. `configuration`, `state` and `rows` are present only when requested via `include`.", "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationPartialResponse" } } }, "type": "object" } ] }, "ConfigurationResponse": { "description": "Component configuration with its data, state and rows, as returned by detail, list, update, state update and rebase.", "required": [ "id", "name", "description", "created", "creatorToken", "actor", "version", "changeDescription", "isDisabled", "isDeleted", "folder", "folderUpdated", "configuration", "rowsSortOrder", "rows", "state", "currentVersion" ], "properties": { "id": { "description": "Configuration id, unique within the component.", "type": "string", "example": "236606822" }, "name": { "description": "Configuration name.", "type": "string", "example": "My new configuration" }, "description": { "description": "Configuration description.", "type": "string", "example": "" }, "created": { "description": "When the configuration was created, ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2017-02-13T12:01:05+0100" }, "creatorToken": { "required": [ "id", "description" ], "properties": { "id": { "description": "Id of the token that created the configuration.", "type": "integer", "format": "int64", "example": 27978 }, "description": { "description": "Description of the token (typically the user e-mail).", "type": "string", "example": "dev@keboola.com" } }, "type": "object" }, "actor": { "description": "Who created it and through which credential; null only when no creator is recorded.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "version": { "description": "Current version number. Use it as the `If-Match` precondition for update, delete and purge.", "type": "integer", "example": 1 }, "changeDescription": { "description": "Change description of the current version.", "type": "string", "example": "Initial configuration", "nullable": true }, "isDisabled": { "description": "Whether the configuration is disabled.", "type": "boolean", "example": false }, "isDeleted": { "description": "Whether the configuration is in the trash.", "type": "boolean", "example": false }, "folder": { "description": "Folder the configuration is grouped under; `null` when it is in none.", "type": "string", "example": "Marketing", "nullable": true, "maxLength": 400 }, "folderUpdated": { "description": "When the folder was last written (set, cleared, copied to a branch or merged), ISO 8601 with a `+hhmm` offset; `null` when the configuration has no folder. Read-only.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "configuration": { "description": "Configuration data, arbitrary object defined by the component.", "type": "object", "additionalProperties": true }, "rowsSortOrder": { "description": "Row ids in the desired order; empty when the default order (by id) applies.", "type": "array", "items": { "type": "string" } }, "rows": { "description": "Configuration rows (not deleted ones), each with its `state` and `configuration`.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/ConfigurationRowInConfigurationResponse" }, { "required": [ "state", "configuration" ] } ] } }, "state": { "description": "Configuration state data, arbitrary object.", "type": "object", "additionalProperties": true }, "currentVersion": { "$ref": "#/components/schemas/ConfigurationCurrentVersionResponse" } }, "type": "object" }, "ConfigurationRowDiffData": { "description": "User-editable content of a single configuration row nested in a diff side. Array order reflects rowsSortOrder and is meaningful. Unlike the configuration-level diff a row carries no changeDescription and no deletion tombstone \u2014 a row deleted on one side is resolved by its presence in the base side.", "required": [ "id", "name", "description", "isDisabled", "configuration" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "isDisabled": { "type": "boolean" }, "configuration": { "type": "object" } }, "type": "object" }, "ConfigurationDiffData": { "description": "User-editable configuration content of a single diff side. This is the payload a client feeds directly into a three-way diff editor and, once resolved, sends back to the rebase endpoint. `rows` are the configuration rows valid at this side's version, in rowsSortOrder.", "required": [ "name", "description", "changeDescription", "isDisabled", "configuration", "rows" ], "properties": { "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "changeDescription": { "type": "string", "nullable": true }, "isDisabled": { "type": "boolean" }, "configuration": { "type": "object" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationRowDiffData" } } }, "type": "object" }, "ConfigurationVersionResponse": { "description": "A single side of the three-way diff: the user-editable content (`diff`) plus per-side metadata. `version` is the side version (e.g. the default branch version to rebase onto). `isDeleted` marks a deletion tombstone \u2014 the side existed but was soft-deleted (distinct from a null side, which never existed).", "required": [ "version", "isDeleted", "diff" ], "properties": { "version": { "type": "integer" }, "isDeleted": { "type": "boolean" }, "diff": { "$ref": "#/components/schemas/ConfigurationDiffData" } }, "type": "object" }, "ConfigurationDiffResponse": { "description": "Three-way diff of a configuration body. Each side is a configuration version snapshot, or null when the configuration does not exist on that side. When there is no conflict all three sides are equal.", "required": [ "base", "ours", "theirs" ], "properties": { "base": { "oneOf": [ { "$ref": "#/components/schemas/ConfigurationVersionResponse" } ], "nullable": true }, "ours": { "oneOf": [ { "$ref": "#/components/schemas/ConfigurationVersionResponse" } ], "nullable": true }, "theirs": { "oneOf": [ { "$ref": "#/components/schemas/ConfigurationVersionResponse" } ], "nullable": true } }, "type": "object" }, "WorkspaceDetailResponse": { "required": [ "id", "type", "name", "component", "configurationId", "configurationVersion", "created", "connection", "backendSize", "statementTimeoutSeconds", "creatorToken", "actor", "readOnlyStorageAccess", "platformUsageType", "state", "lastActivityAt", "warnAt", "deactivateAt", "deleteAt" ], "properties": { "id": { "description": "ID of the workspace.", "type": "integer" }, "type": { "description": "Type of the workspace.", "type": "string", "enum": [ "file", "table" ] }, "name": { "description": "Name of the workspace (schema name for table type).", "type": "string", "nullable": true }, "component": { "description": "ID of the component that created the workspace.", "type": "string", "nullable": true }, "configurationId": { "description": "ID of the configuration that created the workspace.", "type": "string", "nullable": true }, "configurationVersion": { "description": "Pinned configuration version.", "type": "integer", "nullable": true }, "created": { "description": "Date and time of workspace creation, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100" }, "connection": { "description": "Connection details for the workspace.", "type": "object", "oneOf": [ { "required": [ "backend", "region", "host", "database", "schema", "warehouse", "user", "loginType", "ssoLoginAvailable" ], "properties": { "backend": { "description": "Workspace backend type.", "type": "string", "enum": [ "snowflake", "synapse", "exasol", "teradata", "bigquery", "postgres", "ducklake" ] }, "region": { "description": "Region of the workspace backend.", "type": "string" }, "host": { "description": "Hostname of the workspace backend.", "type": "string" }, "database": { "description": "Database name (project name for Snowflake).", "type": "string", "nullable": true }, "schema": { "description": "Schema name.", "type": "string", "nullable": true }, "warehouse": { "description": "Warehouse name (for Snowflake).", "type": "string", "nullable": true }, "user": { "description": "Username for connecting to the workspace. Empty when loginType is \"none\" or \"governed\".", "type": "string" }, "loginType": { "description": "Login type used for the connection. Value \"none\" means the workspace has no direct credentials and is intended for QueryService. Value \"governed\" means the same, and in addition only QueryService can obtain credentials for it. Create direct connection credentials later using the workspace credentials endpoint.", "type": "string", "enum": [ "default", "snowflake-legacy-service", "snowflake-person-sso", "snowflake-person-keypair", "snowflake-service-keypair", "none", "governed" ] }, "ssoLoginAvailable": { "description": "Indicates if SSO login is available.", "type": "boolean" }, "account": { "description": "Snowflake account locator. Present only for Snowflake workspaces.", "type": "string" }, "role": { "description": "Snowflake role of the workspace user. Present only for Snowflake workspaces.", "type": "string", "nullable": true } } }, { "required": [ "backend", "container", "region" ], "properties": { "backend": { "description": "File storage backend type (e.g., azure, aws).", "type": "string" }, "container": { "description": "Container name for file storage.", "type": "string", "nullable": true }, "region": { "description": "Region of the file storage.", "type": "string" } } } ] }, "backendSize": { "description": "Size of the backend (e.g., for Snowflake).", "type": "string", "nullable": true }, "statementTimeoutSeconds": { "description": "Statement timeout in seconds.", "type": "integer" }, "creatorToken": { "required": [ "id", "description" ], "properties": { "id": { "description": "ID of the token that created the workspace; 0 when the creator is not backed by a token.", "type": "integer" }, "description": { "description": "Description of the token.", "type": "string", "nullable": true } }, "type": "object" }, "actor": { "description": "Who created the workspace. Null only for a workspace that records no creator.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "readOnlyStorageAccess": { "description": "Indicates if read-only storage access is enabled.", "type": "boolean" }, "platformUsageType": { "description": "Platform usage type.", "type": "string", "nullable": true, "enum": [ "service", "user", "reader" ] }, "state": { "description": "Lifecycle state of the workspace. A deactivated workspace is kept listed so its owner can delete it, but its backend identity is disabled and cannot be connected to; contact support to reactivate it.", "type": "string", "enum": [ "active", "deactivated" ] }, "lastActivityAt": { "description": "Last observed workspace use (backend login or Storage job), ISO 8601 with a `+hhmm` offset. May be a seeded floor for an unused workspace; null when unknown.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "warnAt": { "description": "Projected date retention would warn this workspace, ISO 8601 with a `+hhmm` offset. It can move when the workspace is used; null when retention does not apply or activity has not been synced recently.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "deactivateAt": { "description": "When retention will deactivate this unused workspace, ISO 8601 with a `+hhmm` offset. Null unless the owner has been warned. Connecting to the workspace cancels it. Can lie in the past while retention only notifies.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "deleteAt": { "description": "When retention will delete this deactivated workspace, ISO 8601 with a `+hhmm` offset. Null unless the workspace is deactivated. Support can reactivate it until then.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true } }, "type": "object" }, "WorkspaceCreatedResponse": { "description": "Workspace detail extended with the freshly created secret. The secret is not stored and is returned only once, right after the workspace is created.", "required": [ "id", "type", "name", "component", "configurationId", "configurationVersion", "created", "connection", "backendSize", "statementTimeoutSeconds", "creatorToken", "actor", "readOnlyStorageAccess", "platformUsageType", "state", "lastActivityAt", "warnAt", "deactivateAt", "deleteAt" ], "properties": { "id": { "description": "ID of the workspace.", "type": "integer" }, "type": { "description": "Type of the workspace.", "type": "string", "enum": [ "file", "table" ] }, "name": { "description": "Name of the workspace (schema name for table type).", "type": "string", "nullable": true }, "component": { "description": "ID of the component that created the workspace.", "type": "string", "nullable": true }, "configurationId": { "description": "ID of the configuration that created the workspace.", "type": "string", "nullable": true }, "configurationVersion": { "description": "Pinned configuration version.", "type": "integer", "nullable": true }, "created": { "description": "Date and time of workspace creation, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100" }, "connection": { "description": "Connection details for the workspace.", "type": "object", "oneOf": [ { "required": [ "backend", "region", "host", "database", "schema", "warehouse", "loginType", "ssoLoginAvailable" ], "properties": { "backend": { "description": "Workspace backend type.", "type": "string", "enum": [ "snowflake", "synapse", "exasol", "teradata", "bigquery", "postgres", "ducklake" ] }, "region": { "description": "Region of the workspace backend.", "type": "string" }, "host": { "description": "Hostname of the workspace backend.", "type": "string" }, "database": { "description": "Database name (project name for Snowflake).", "type": "string", "nullable": true }, "schema": { "description": "Schema name.", "type": "string", "nullable": true }, "warehouse": { "description": "Warehouse name (for Snowflake).", "type": "string", "nullable": true }, "user": { "description": "Username for connecting to the workspace. Empty when loginType is \"none\" or \"governed\". Absent for a BigQuery workspace created with a key, which returns `credentials` instead.", "type": "string" }, "loginType": { "description": "Login type used for the connection. Value \"none\" means the workspace has no direct credentials and is intended for QueryService. Value \"governed\" means the same, and in addition only QueryService can obtain credentials for it. Create direct connection credentials later using the workspace credentials endpoint.", "type": "string", "enum": [ "default", "snowflake-legacy-service", "snowflake-person-sso", "snowflake-person-keypair", "snowflake-service-keypair", "none", "governed" ] }, "ssoLoginAvailable": { "description": "Indicates if SSO login is available.", "type": "boolean" }, "account": { "description": "Snowflake account locator. Present only for Snowflake workspaces.", "type": "string" }, "role": { "description": "Snowflake role of the workspace user. Present only for Snowflake workspaces.", "type": "string", "nullable": true }, "password": { "description": "Password of the workspace user. Present only for a table workspace other than BigQuery created with a password login type.", "type": "string" }, "credentials": { "description": "Google service account key. Present only for a BigQuery workspace created with a key; the `user` key is omitted in that case.", "properties": { "type": { "type": "string", "example": "service_account" }, "project_id": { "type": "string" }, "private_key_id": { "type": "string" }, "private_key": { "type": "string" }, "client_email": { "type": "string" }, "client_id": { "type": "string" }, "auth_uri": { "type": "string" }, "token_uri": { "type": "string" }, "auth_provider_x509_cert_url": { "type": "string" }, "client_x509_cert_url": { "type": "string" } }, "type": "object" } } }, { "required": [ "backend", "container", "region" ], "properties": { "backend": { "description": "File storage backend type (e.g., azure, aws).", "type": "string" }, "container": { "description": "Container name for file storage.", "type": "string", "nullable": true }, "region": { "description": "Region of the file storage.", "type": "string" }, "connectionString": { "description": "SAS connection string. Present only for a file (ABS) workspace created with a secret.", "type": "string" } } } ] }, "backendSize": { "description": "Size of the backend (e.g., for Snowflake).", "type": "string", "nullable": true }, "statementTimeoutSeconds": { "description": "Statement timeout in seconds.", "type": "integer" }, "creatorToken": { "required": [ "id", "description" ], "properties": { "id": { "description": "ID of the token that created the workspace; 0 when the creator is not backed by a token.", "type": "integer" }, "description": { "description": "Description of the token.", "type": "string", "nullable": true } }, "type": "object" }, "actor": { "description": "Who created the workspace. Null only for a workspace that records no creator.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "readOnlyStorageAccess": { "description": "Indicates if read-only storage access is enabled.", "type": "boolean" }, "platformUsageType": { "description": "Platform usage type.", "type": "string", "nullable": true, "enum": [ "service", "user", "reader" ] }, "state": { "description": "Lifecycle state of the workspace. A deactivated workspace is kept listed so its owner can delete it, but its backend identity is disabled and cannot be connected to; contact support to reactivate it.", "type": "string", "enum": [ "active", "deactivated" ] }, "lastActivityAt": { "description": "Last observed workspace use (backend login or Storage job), ISO 8601 with a `+hhmm` offset. May be a seeded floor for an unused workspace; null when unknown.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "warnAt": { "description": "Projected date retention would warn this workspace, ISO 8601 with a `+hhmm` offset. It can move when the workspace is used; null when retention does not apply or activity has not been synced recently.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "deactivateAt": { "description": "When retention will deactivate this unused workspace, ISO 8601 with a `+hhmm` offset. Null unless the owner has been warned. Connecting to the workspace cancels it. Can lie in the past while retention only notifies.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "deleteAt": { "description": "When retention will delete this deactivated workspace, ISO 8601 with a `+hhmm` offset. Null unless the workspace is deactivated. Support can reactivate it until then.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true } }, "type": "object" }, "ConfigurationMetadataResponse": { "required": [ "id", "key", "value", "timestamp" ], "properties": { "id": { "description": "Metadata entry id.", "type": "string", "example": "19509" }, "key": { "description": "Metadata key.", "type": "string", "example": "some-key" }, "value": { "description": "Metadata value.", "type": "string", "example": "Some value" }, "timestamp": { "description": "When the entry was last set, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100" } }, "type": "object" }, "ConfigurationRowResponse": { "required": [ "id", "name", "description", "isDisabled", "version", "created", "creatorToken", "actor", "changeDescription", "versionIdentifier", "state", "configuration" ], "properties": { "id": { "description": "Row identifier, unique within the configuration.", "type": "string", "example": "236781646" }, "name": { "description": "Row name.", "type": "string", "example": "My row" }, "description": { "description": "Row description.", "type": "string", "example": "" }, "isDisabled": { "description": "Disabled flag.", "type": "boolean", "example": false }, "version": { "description": "Current row version number.", "type": "integer", "example": 1 }, "created": { "description": "Row creation time, ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2017-02-13T12:01:05+0100" }, "creatorToken": { "description": "Token that created the row.", "required": [ "id", "description" ], "properties": { "id": { "description": "Token ID.", "type": "integer", "format": "int64", "example": 27978 }, "description": { "description": "Token description.", "type": "string", "example": "dev@keboola.com", "nullable": true } }, "type": "object" }, "actor": { "description": "Who created it and through which credential; null only when no creator is recorded.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "changeDescription": { "description": "Description of the change that produced the current version.", "type": "string", "example": "Added new row", "nullable": true }, "versionIdentifier": { "description": "Unique identifier of the current row version.", "type": "string", "example": "01H59WQGTDQT8AC7XNWKQDS75P", "nullable": true }, "state": { "description": "Row state data; `{}` when none is stored.", "type": "object", "additionalProperties": true }, "configuration": { "description": "Row configuration data.", "type": "object", "example": { "host": "localhost", "port": 4406 }, "additionalProperties": true } }, "type": "object" }, "ConfigurationRowVersionResponse": { "required": [ "id", "name", "description", "isDisabled", "version", "created", "creatorToken", "actor", "changeDescription", "versionIdentifier", "configuration" ], "properties": { "id": { "description": "Row identifier.", "type": "string", "example": "236781646" }, "name": { "description": "Row name in this version.", "type": "string", "example": "" }, "description": { "description": "Row description in this version.", "type": "string", "example": "" }, "isDisabled": { "description": "Disabled flag in this version.", "type": "boolean", "example": false }, "version": { "description": "Version number.", "type": "integer", "example": 2 }, "created": { "description": "Version creation time, ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2017-02-13T12:01:05+0100" }, "creatorToken": { "description": "Token that created the version.", "required": [ "id", "description" ], "properties": { "id": { "description": "Token ID.", "type": "integer", "format": "int64", "example": 1392 }, "description": { "description": "Token description.", "type": "string", "example": "martin@keboola.com", "nullable": true } }, "type": "object" }, "actor": { "description": "Who created it and through which credential; null only when no creator is recorded.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "changeDescription": { "description": "Description of the change.", "type": "string", "example": "Cause of the change", "nullable": true }, "versionIdentifier": { "description": "Unique identifier of the version.", "type": "string", "example": "01H59WQGTDQT8AC7XNWKQDS75P", "nullable": true }, "configuration": { "description": "Row configuration data.", "type": "object", "example": { "host": "localhost" }, "additionalProperties": true } }, "type": "object" }, "ConfigurationRowVersionListItemResponse": { "description": "A configuration row version as listed.", "required": [ "id", "name", "description", "isDisabled", "version", "created", "creatorToken", "actor", "changeDescription", "versionIdentifier" ], "properties": { "id": { "description": "Row identifier.", "type": "string", "example": "236781646" }, "name": { "description": "Row name in this version.", "type": "string", "example": "" }, "description": { "description": "Row description in this version.", "type": "string", "example": "" }, "isDisabled": { "description": "Disabled flag in this version.", "type": "boolean", "example": false }, "version": { "description": "Version number.", "type": "integer", "example": 2 }, "created": { "description": "Version creation time, ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2017-02-13T12:01:05+0100" }, "creatorToken": { "description": "Token that created the version.", "required": [ "id", "description" ], "properties": { "id": { "description": "Token ID.", "type": "integer", "format": "int64", "example": 1392 }, "description": { "description": "Token description.", "type": "string", "example": "martin@keboola.com", "nullable": true } }, "type": "object" }, "actor": { "description": "Who created it and through which credential; null only when no creator is recorded.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "changeDescription": { "description": "Description of the change.", "type": "string", "example": "Cause of the change", "nullable": true }, "versionIdentifier": { "description": "Unique identifier of the version.", "type": "string", "example": "01H59WQGTDQT8AC7XNWKQDS75P", "nullable": true }, "configuration": { "description": "Row configuration data; present only when `configuration` is included.", "type": "object", "example": { "host": "localhost" }, "additionalProperties": true } }, "type": "object" }, "ConfigurationCopyResponse": { "required": [ "id" ], "properties": { "id": { "description": "Id of the newly created configuration.", "type": "string", "example": "236606823" } }, "type": "object" }, "ConfigurationVersionDetailResponse": { "description": "A historical configuration version with its name, description, configuration and rows.", "required": [ "version", "created", "versionIdentifier", "creatorToken", "actor", "changeDescription", "isDisabled", "isDeleted", "name", "description", "configuration", "rowsSortOrder", "rows" ], "properties": { "version": { "description": "Version number.", "type": "integer", "example": 1 }, "created": { "description": "When the version was created, ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2017-02-13T12:01:05+0100" }, "versionIdentifier": { "description": "ULID uniquely identifying the version across branches.", "type": "string", "example": "01H2W7DAN0QT78NZQ2BD2BZT4S", "nullable": true }, "creatorToken": { "$ref": "#/components/schemas/ConfigurationCreatorTokenResponse" }, "actor": { "description": "Who created it and through which credential; null only when no creator is recorded.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "changeDescription": { "description": "Change description of the version.", "type": "string", "example": "", "nullable": true }, "isDisabled": { "description": "Disabled flag at this version.", "type": "boolean", "example": false }, "isDeleted": { "description": "Whether this version is a deletion tombstone.", "type": "boolean", "example": false }, "name": { "description": "Configuration name at this version.", "type": "string", "example": "test" }, "description": { "description": "Configuration description at this version.", "type": "string", "example": "", "nullable": true }, "configuration": { "description": "Configuration data at this version.", "type": "object", "additionalProperties": true }, "rowsSortOrder": { "description": "Row ids in the desired order at this version.", "type": "array", "items": { "type": "string" } }, "rows": { "description": "Row versions valid at this configuration version, in sort order.", "type": "array", "items": { "required": [ "id", "name", "description", "isDisabled", "version", "created", "creatorToken", "actor", "changeDescription", "versionIdentifier", "configuration" ], "properties": { "id": { "type": "string", "example": "row1" }, "name": { "type": "string", "example": "First row" }, "description": { "type": "string", "example": "" }, "isDisabled": { "type": "boolean", "example": false }, "version": { "type": "integer", "example": 1 }, "created": { "description": "ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2017-02-13T12:01:05+0100" }, "creatorToken": { "$ref": "#/components/schemas/ConfigurationCreatorTokenResponse" }, "actor": { "description": "Who created it and through which credential; null only when no creator is recorded.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "changeDescription": { "type": "string", "nullable": true }, "versionIdentifier": { "type": "string", "example": "01H2W8N0ZJJB6V126C8ZSND28N", "nullable": true }, "configuration": { "type": "object", "additionalProperties": true } }, "type": "object" } } }, "type": "object" }, "ConfigurationVersionListItemResponse": { "description": "A historical configuration version as listed. `name`, `description` and `configuration` are present only when requested by `include` (default `name,description`).", "required": [ "version", "created", "versionIdentifier", "creatorToken", "actor", "changeDescription", "isDisabled", "isDeleted" ], "properties": { "version": { "description": "Version number.", "type": "integer", "example": 1 }, "created": { "description": "When the version was created, ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2017-02-13T12:01:05+0100" }, "versionIdentifier": { "description": "ULID uniquely identifying the version across branches.", "type": "string", "example": "01H2W7DAN0QT78NZQ2BD2BZT4S", "nullable": true }, "creatorToken": { "$ref": "#/components/schemas/ConfigurationCreatorTokenResponse" }, "actor": { "description": "Who created it and through which credential; null only when no creator is recorded.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "changeDescription": { "description": "Change description of the version.", "type": "string", "example": "", "nullable": true }, "isDisabled": { "description": "Disabled flag at this version.", "type": "boolean", "example": false }, "isDeleted": { "description": "Whether this version is a deletion tombstone.", "type": "boolean", "example": false }, "name": { "description": "Configuration name at this version.", "type": "string", "example": "test" }, "description": { "description": "Configuration description at this version.", "type": "string", "example": "", "nullable": true }, "configuration": { "description": "Configuration data at this version.", "type": "object", "additionalProperties": true } }, "type": "object" }, "ConfigurationVersionRollbackResponse": { "required": [ "version" ], "properties": { "version": { "description": "Number of the newly created configuration version. Returned as a string.", "type": "string", "example": "3" } }, "type": "object" }, "DevBranchResponse": { "description": "Development branch detail.", "required": [ "id", "name", "description", "created", "isDefault", "creatorToken", "actor" ], "properties": { "id": { "description": "Branch ID.", "type": "integer", "example": 123 }, "name": { "description": "Branch name.", "type": "string", "example": "My branch" }, "description": { "description": "Branch description.", "type": "string", "example": "" }, "created": { "description": "Creation time, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100" }, "isDefault": { "description": "True for the default (production) branch.", "type": "boolean", "example": false }, "creatorToken": { "description": "Token that created the branch; `[]` for a branch with no creator token, such as the default branch.", "oneOf": [ { "required": [ "id", "name" ], "properties": { "id": { "description": "Creator token ID; 0 when the creator is not backed by a token.", "type": "integer", "example": 267 }, "name": { "description": "Creator token description.", "type": "string", "example": "dev@keboola.com" } }, "type": "object" }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "actor": { "description": "Who created the branch. Null for a branch with no creator, such as the default branch.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] } }, "type": "object" }, "MetadataItemWithoutProviderResponse": { "description": "Single metadata record of a development branch.", "required": [ "id", "key", "value", "timestamp" ], "properties": { "id": { "description": "Metadata record identifier", "type": "string", "example": "19509" }, "key": { "description": "Metadata key", "type": "string", "example": "some-key" }, "value": { "description": "Metadata value", "type": "string", "example": "Some value", "nullable": true }, "timestamp": { "description": "When the metadata was created or last updated, ISO 8601 with a `+hhmm` offset", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T23:36:10+0100" } }, "type": "object" }, "EventAttachmentResponse": { "required": [ "id", "isSliced", "uploadType", "isExpired", "created", "name", "url", "sizeBytes" ], "properties": { "id": { "description": "Id of the attached file.", "type": "integer", "example": 6789 }, "isSliced": { "description": "Whether the file is sliced.", "type": "boolean", "example": false }, "uploadType": { "description": "Upload type of the file.", "type": "string", "example": "userUpload" }, "isExpired": { "description": "Whether the file has already expired.", "type": "boolean", "example": false }, "created": { "description": "When the file was created, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100" }, "name": { "description": "File name.", "type": "string", "example": "backup.csv.gz" }, "url": { "description": "Download URL of the file.", "type": "string", "example": "https://s3.amazonaws.com/kbc-sapi-files/exp-15/1234/files.keboola/backup.csv.gz" }, "sizeBytes": { "description": "File size in bytes.", "type": "integer", "example": 1024, "nullable": true } }, "type": "object" }, "EventResponse": { "required": [ "uuid", "event", "component", "message", "description", "type", "runId", "created", "configurationId", "objectId", "objectName", "objectType", "context", "params", "results", "performance", "token", "idBranch", "uri", "attachments" ], "properties": { "uuid": { "description": "Event UUID v7 identifier.", "type": "string", "example": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3" }, "event": { "description": "Event identifier such as `storage.tableImportDone` or `storage.tableDetail`. External events are named `ext.{component}.{configurationId}`.", "type": "string", "example": "storage.workspaceLoaded" }, "component": { "description": "Name of the component that logged the event. Events can be logged by the `storage` component or any other registered component.", "type": "string", "example": "storage" }, "message": { "description": "Human readable description of the event.", "type": "string", "example": "Table in.c-application-testing.cashier-data was loaded to the workspace workspace_78423 as my-table." }, "description": { "description": "Additional description of the event, such as a detailed error description.", "type": "string", "example": "" }, "type": { "description": "Type of the event.", "type": "string", "example": "info", "enum": [ "info", "success", "warn", "error" ] }, "runId": { "description": "Id of the associated job.", "type": "string", "example": null, "nullable": true }, "created": { "description": "When the event was created, ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2017-02-13T12:01:05+0100" }, "configurationId": { "description": "Id of a configuration used by an external component.", "type": "string", "example": null, "nullable": true }, "objectId": { "description": "Id of the target object of the event, e.g. table id for `storage.tableImportDone`. An integer for objects with numeric ids, such as files, workspaces, branches and admins.", "example": "in.c-application-testing.cashier-data", "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "objectName": { "description": "Name of the target object, e.g. table name for `storage.tableImportDone`.", "type": "string", "example": "cashier-data" }, "objectType": { "description": "Type of the target object, e.g. `table` for `storage.tableImportDone`.", "type": "string", "example": "table" }, "context": { "description": "Details about the origin of the API call that triggered the event; an empty array `[]` when the event has no context.", "oneOf": [ { "properties": { "remoteAddr": { "type": "string", "example": "203.0.113.10", "nullable": true }, "httpReferer": { "type": "string", "example": null, "nullable": true }, "httpUserAgent": { "type": "string", "example": "Keboola Storage PHP Client", "nullable": true }, "httpUserAgentOriginal": { "type": "string", "example": "Keboola Storage PHP Client", "nullable": true }, "authorization": { "type": "string", "example": "token", "nullable": true }, "apiVersion": { "type": "string", "example": "v2", "nullable": true } }, "type": "object" }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "params": { "description": "Arbitrary parameters associated with the event, e.g. CSV file settings for table import.", "type": "object", "additionalProperties": {} }, "results": { "description": "Arbitrary results of the event.", "type": "object", "additionalProperties": {} }, "performance": { "description": "Arbitrary performance metrics associated with the event.", "type": "object", "additionalProperties": {} }, "token": { "description": "Creator of the event.", "required": [ "id", "name" ], "properties": { "id": { "description": "Id of the token.", "type": "integer", "example": 1234 }, "name": { "description": "Token owner.", "type": "string", "example": "support@keboola.com", "nullable": true } }, "type": "object" }, "idBranch": { "description": "Id of the branch the event belongs to, including the default branch; `null` when the event is not tied to a branch.", "type": "integer", "example": 1234, "nullable": true }, "uri": { "description": "Event URI.", "type": "string", "example": "https://connection.keboola.com/v2/storage/events/01958f48-b1fc-7f05-b9b9-8a4a7b385bc3" }, "attachments": { "description": "Files attached to the event, e.g. backups for table import events.", "type": "array", "items": { "$ref": "#/components/schemas/EventAttachmentResponse" } } }, "type": "object" }, "EventsListResponse": { "type": "array", "items": { "$ref": "#/components/schemas/EventResponse" } }, "CreateEventResponse": { "required": [ "id", "uuid" ], "properties": { "id": { "description": "Deprecated, will be removed in the future. Contains the same value as `uuid`.", "type": "string", "example": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3", "deprecated": true }, "uuid": { "description": "UUID v7 identifier of the created event.", "type": "string", "example": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3" } }, "type": "object" }, "FileResponse": { "required": [ "id", "created", "isPublic", "isSliced", "isEncrypted", "name", "fileType", "url", "provider", "region", "sizeBytes", "tags", "maxAgeDays", "runId", "runIds", "creatorToken" ], "properties": { "id": { "description": "Identifier of the file.", "type": "integer", "example": 236518631 }, "created": { "description": "Creation time of the file, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100" }, "isPublic": { "description": "Whether the file is publicly accessible via a direct URL.", "type": "boolean", "example": false }, "isSliced": { "description": "Whether the file consists of multiple slices (chunks) described by a manifest file.", "type": "boolean", "example": false }, "isEncrypted": { "description": "Whether the file content is encrypted in the storage.", "type": "boolean", "example": true }, "name": { "description": "Sanitized file name.", "type": "string", "example": "somefile.csv" }, "fileType": { "description": "Human readable file type derived from the file name.", "type": "string", "example": "csv" }, "url": { "description": "Pre-signed download URL of the file. The URL expires after one hour.", "type": "string", "example": "https://s3.amazonaws.com/kbc-sapi-files/exp-180/578/files/2017/02/14/236518630.somefile.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=374...a4c" }, "provider": { "description": "File storage provider.", "type": "string", "example": "aws", "enum": [ "aws", "azure", "gcp" ] }, "region": { "description": "Region of the file storage.", "type": "string", "example": "us-east-1" }, "sizeBytes": { "description": "File size in bytes, null when not known.", "type": "integer", "example": 12345, "nullable": true }, "tags": { "description": "Tags assigned to the file.", "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ] }, "maxAgeDays": { "description": "Number of days the file is kept before it expires. Null for permanent files.", "type": "integer", "example": 15, "nullable": true }, "runId": { "description": "Run ID taken from the X-KBC-RunId header when the file was created.", "type": "string", "example": null, "nullable": true }, "runIds": { "description": "All run IDs derived from the hierarchical run ID.", "type": "array", "items": { "type": "string" }, "example": [] }, "creatorToken": { "description": "Token that created the file.", "required": [ "id", "description" ], "properties": { "id": { "type": "integer", "example": 27978 }, "description": { "type": "string", "example": "dev@keboola.com" } }, "type": "object" } }, "type": "object" }, "FileDetailResponse": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/FileResponse" }, { "description": "Download credentials are included only when `federationToken=true`; which keys are present depends on the file provider.", "properties": { "credentials": { "description": "Temporary AWS credentials with read access to the file. Present only for the `aws` provider.", "required": [ "AccessKeyId", "SecretAccessKey", "SessionToken", "Expiration" ], "properties": { "AccessKeyId": { "type": "string", "example": "ASI...O7A" }, "SecretAccessKey": { "type": "string", "example": "gIT...RtE" }, "SessionToken": { "type": "string", "example": "Ago...QU=" }, "Expiration": { "type": "string", "format": "date-time", "example": "2017-02-14T22:10:17+00:00" } }, "type": "object" }, "s3Path": { "description": "Location of the file in S3. Present only for the `aws` provider.", "required": [ "bucket", "key" ], "properties": { "bucket": { "type": "string", "example": "kbc-sapi-files" }, "key": { "type": "string", "example": "exp-180/578/files/2017/02/14/236504176.235728260.csvmanifest" } }, "type": "object" }, "absCredentials": { "description": "SAS credentials with read access to the container. Present only for the `azure` provider.", "required": [ "SASConnectionString", "expiration" ], "properties": { "SASConnectionString": { "type": "string", "example": "BlobEndpoint=https://kbcfshc7chguaeh2km.blob.core.windows.net;SharedAccessSignature=sv=2017-11-09&sr=c&sp=rl&sig=tBsXf..." }, "expiration": { "description": "ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100" } }, "type": "object" }, "absPath": { "description": "Location of the file in Azure Blob Storage. Present only for the `azure` provider.", "required": [ "container", "name" ], "properties": { "container": { "type": "string", "example": "exp-15-files-4516-27364641-2022-11-09" }, "name": { "type": "string", "example": "somefile.csv" } }, "type": "object" }, "gcsCredentials": { "description": "Access token with read access to the file. Present only for the `gcp` provider.", "required": [ "access_token", "expires_in", "token_type", "projectId" ], "properties": { "access_token": { "type": "string", "example": "ya29.dr..." }, "expires_in": { "type": "integer", "example": 3599 }, "token_type": { "type": "string", "example": "Bearer" }, "projectId": { "type": "string", "example": "ci-connection-361807" } }, "type": "object" }, "gcsPath": { "description": "Location of the file in Google Cloud Storage. Present only for the `gcp` provider.", "required": [ "bucket", "key" ], "properties": { "bucket": { "type": "string", "example": "kbc-ci-connection-files-storage" }, "key": { "type": "string", "example": "exp-15/23058/files/2022/11/09/851783.somefile.csv" } }, "type": "object" } } } ] }, "AbsFilePrepareRequest": { "required": [ "name" ], "properties": { "name": { "description": "File name. Sanitized to a valid filename.", "type": "string", "example": "someFile.csv" }, "isPermanent": { "description": "Keeps a file forever. If false, the file will be deleted after 15 days.", "type": "boolean", "example": false, "default": false }, "isSliced": { "description": "If true, multiple chunks of a file are allowed to be uploaded and the provided key points to a manifest file.", "type": "boolean", "example": false, "default": false }, "contentType": { "description": "File MIME type.", "type": "string", "example": "text/csv", "default": "application/octet-stream" }, "tags": { "description": "Assigns one or more tags to the file.", "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ] }, "sizeBytes": { "description": "File size in bytes.", "type": "integer", "example": 12345, "nullable": true }, "federationTokenRequired": { "type": "boolean" } }, "type": "object" }, "GcsFilePrepareRequest": { "required": [ "name" ], "properties": { "name": { "description": "File name. Sanitized to a valid filename.", "type": "string", "example": "someFile.csv" }, "isPermanent": { "description": "Keeps a file forever. If false, the file will be deleted after 15 days.", "type": "boolean", "example": false, "default": false }, "isSliced": { "description": "If true, multiple chunks of a file are allowed to be uploaded and the provided key points to a manifest file.", "type": "boolean", "example": false, "default": false }, "contentType": { "description": "File MIME type.", "type": "string", "example": "text/csv", "default": "application/octet-stream" }, "tags": { "description": "Assigns one or more tags to the file.", "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ] }, "sizeBytes": { "description": "File size in bytes.", "type": "integer", "example": 12345, "nullable": true }, "federationTokenRequired": { "type": "boolean" } }, "type": "object" }, "S3FilePrepareRequest": { "required": [ "name" ], "properties": { "name": { "description": "File name. Sanitized to a valid filename.", "type": "string", "example": "someFile.csv" }, "isPublic": { "description": "Whether the file should be publicly accessible via a direct URL.", "type": "boolean", "example": false, "default": false }, "notify": { "description": "Notifies project administrators that a file was uploaded.", "type": "boolean", "example": false, "default": false }, "isPermanent": { "description": "Keeps a file forever. If false, the file will be deleted after 15 days.", "type": "boolean", "example": false, "default": false }, "isSliced": { "description": "If true, multiple chunks of a file are allowed to be uploaded and the provided key points to a manifest file.", "type": "boolean", "example": false, "default": false }, "isEncrypted": { "description": "If true, the file content will be encrypted in the provided storage. Azure and Google Cloud always create encrypted files regardless of this setting.", "type": "boolean", "example": false, "default": false }, "federationToken": { "description": "Must be set to `true`; requests temporary federation token credentials for the upload. Form uploads without it are deprecated and rejected.", "type": "boolean", "example": true, "default": false }, "contentType": { "description": "File MIME type.", "type": "string", "example": "text/csv", "default": "application/octet-stream" }, "tags": { "description": "Assigns one or more tags to the file.", "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ] }, "sizeBytes": { "description": "File size in bytes.", "type": "integer", "example": 12345, "nullable": true }, "federationTokenRequired": { "type": "boolean" } }, "type": "object" }, "FilePrepareResponse": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/FileResponse" }, { "properties": { "uploadParams": { "description": "Upload parameters. Present only for the `aws` provider.", "required": [ "key", "bucket", "acl", "credentials" ], "properties": { "key": { "description": "S3 object key. For sliced files it is the prefix of the slices and of the manifest file.", "type": "string", "example": "exp-180/578/files/2017/02/14/236518630.somefile.csv" }, "bucket": { "description": "S3 bucket.", "type": "string", "example": "kbc-sapi-files" }, "acl": { "description": "ACL to use for the uploaded object.", "type": "string", "example": "private", "enum": [ "private", "public-read" ] }, "credentials": { "description": "Temporary AWS credentials with write access to the key.", "required": [ "AccessKeyId", "SecretAccessKey", "SessionToken", "Expiration" ], "properties": { "AccessKeyId": { "type": "string", "example": "ASI...D2Q" }, "SecretAccessKey": { "type": "string", "example": "H+/...BYy" }, "SessionToken": { "type": "string", "example": "Ago...sUF" }, "Expiration": { "type": "string", "format": "date-time", "example": "2017-02-14T21:34:46+00:00" } }, "type": "object" }, "x-amz-server-side-encryption": { "description": "Present only when `isEncrypted` is true; the encryption header to send with the upload.", "type": "string", "example": "AES256" } }, "type": "object" }, "absUploadParams": { "description": "Upload parameters. Present only for the `azure` provider.", "required": [ "blobName", "accountName", "container", "absCredentials" ], "properties": { "blobName": { "type": "string", "example": "somefile.csv" }, "accountName": { "type": "string", "example": "kbcfshc7chguaeh2km" }, "container": { "type": "string", "example": "exp-15-files-4516-27364641-2022-11-09" }, "absCredentials": { "description": "SAS credentials with write access to the container.", "required": [ "SASConnectionString", "expiration" ], "properties": { "SASConnectionString": { "type": "string", "example": "BlobEndpoint=https://kbcfshc7chguaeh2km.blob.core.windows.net;SharedAccessSignature=sv=2017-11-09&sr=c&sp=rwl&sig=x6csI..." }, "expiration": { "description": "ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100" } }, "type": "object" } }, "type": "object" }, "gcsUploadParams": { "description": "Upload parameters. Present only for the `gcp` provider.", "required": [ "projectId", "bucket", "key", "access_token", "expires_in", "token_type" ], "properties": { "projectId": { "type": "string", "example": "ci-connection-361807" }, "bucket": { "type": "string", "example": "kbc-ci-connection-files-storage" }, "key": { "type": "string", "example": "exp-15/23058/files/2022/11/09/851783.somefile.csv" }, "access_token": { "type": "string", "example": "ya29.dr..." }, "expires_in": { "description": "Token lifetime in seconds.", "type": "integer", "example": 3599 }, "token_type": { "type": "string", "example": "Bearer" } }, "type": "object" } } } ] }, "GlobalSearchItemBranch": { "description": "Branch a search hit belongs to.", "required": [ "id", "name", "isDefault", "isNative" ], "properties": { "id": { "description": "Branch id.", "type": "integer" }, "name": { "description": "Branch name.", "type": "string" }, "isDefault": { "description": "Whether this is the project default branch.", "type": "boolean" }, "isNative": { "description": "False when the branch was resolved from a fake branch rather than being a real development branch.", "type": "boolean" } }, "type": "object" }, "GlobalSearchIdName": { "description": "Identifier and display name of an object on the path to a search hit.", "required": [ "id", "name" ], "properties": { "id": { "description": "Identifier of the object.", "type": "string" }, "name": { "description": "Display name of the object; `null` for a configuration stored without a name.", "type": "string", "nullable": true } }, "type": "object" }, "GlobalSearchItemFullPath": { "description": "Where a search hit lives. Which members are present depends on the hit `type`.", "required": [ "project", "branch" ], "properties": { "project": { "description": "Project the object belongs to.", "required": [ "id", "name" ], "properties": { "id": { "description": "Project id.", "type": "integer", "example": 10 }, "name": { "description": "Project name.", "type": "string" } }, "type": "object" }, "branch": { "$ref": "#/components/schemas/GlobalSearchItemBranch" }, "bucket": { "description": "Bucket the object lives in. Present for tables and bucket-scoped objects. An empty array `[]` when the bucket could not be resolved uniquely at index time.", "oneOf": [ { "$ref": "#/components/schemas/GlobalSearchIdName" }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "component": { "description": "Component of the configuration. Present for configurations and configuration rows. An empty array `[]` when the component could not be resolved uniquely at index time.", "oneOf": [ { "$ref": "#/components/schemas/GlobalSearchIdName" }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "configuration": { "$ref": "#/components/schemas/GlobalSearchIdName" } }, "type": "object" }, "GlobalSearchItem": { "description": "One global search hit.", "required": [ "id", "type", "name", "fullPath", "organizationId", "projectId", "created" ], "properties": { "id": { "description": "Identifier within its type \u2014 bucket or table string id, configuration id, configuration row id.", "type": "string", "example": "in.c-main.users" }, "type": { "description": "Kind of the matched object.", "type": "string", "enum": [ "bucket", "table", "configuration", "configuration-row" ] }, "name": { "description": "Display name of the object.", "type": "string" }, "fullPath": { "$ref": "#/components/schemas/GlobalSearchItemFullPath" }, "uri": { "description": "API detail URL. Present for buckets and tables only.", "type": "string", "example": "https://connection.keboola.com/v2/storage/tables/in.c-main.users" }, "componentId": { "description": "Component the configuration belongs to. Present for configurations and configuration rows.", "type": "string" }, "matchedColumns": { "description": "Column names that matched, taken from the search highlight. Present for tables matched by a column name; the full column list is never returned.", "type": "array", "items": { "type": "string" } }, "organizationId": { "description": "Organization the object belongs to.", "type": "integer" }, "projectId": { "description": "Project the object belongs to.", "type": "integer" }, "projectName": { "description": "Name of that project.", "type": "string" }, "created": { "description": "When the object was created.", "type": "string", "format": "date-time" } }, "type": "object" }, "GlobalSearchResponse": { "description": "Global search results with per-type and per-project match counts.", "required": [ "all", "items", "byType", "byProject" ], "properties": { "all": { "description": "Total number of matches across the organization, ignoring `limit` and `offset`.", "type": "integer", "example": 42 }, "items": { "description": "Matches for the requested page.", "type": "array", "items": { "$ref": "#/components/schemas/GlobalSearchItem" } }, "byType": { "description": "Match counts per object type, plus `total`. Only types with at least one match are present.", "required": [ "total" ], "properties": { "total": { "description": "Number of matches across all types.", "type": "integer" } }, "type": "object", "example": { "total": 42, "table": 30, "configuration": 12 }, "additionalProperties": { "type": "integer" } }, "byProject": { "description": "Names of the projects the matches come from, keyed by project id; an empty array `[]` when nothing matched.", "example": { "10": "Project name" }, "oneOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "array", "items": {}, "maxItems": 0 } ] } }, "type": "object" }, "MergeRequestResponse": { "required": [ "id", "creator", "title", "description", "state", "branches", "merge", "createdAt", "externalId", "autoMergeStrategy", "autoMergeAt", "approvals", "reviewers" ], "properties": { "id": { "type": "integer" }, "creator": { "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "title": { "type": "string" }, "description": { "type": "string" }, "state": { "type": "string", "enum": [ "development", "in_review", "approved", "in_merge", "published", "canceled" ] }, "branches": { "required": [ "branchFromId", "branchIntoId" ], "properties": { "branchFromId": { "type": "integer", "nullable": true }, "branchIntoId": { "type": "integer", "nullable": true } }, "type": "object" }, "merge": { "required": [ "mergedAt", "mergerId", "mergerName" ], "properties": { "mergedAt": { "description": "When the merge request was merged, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "mergerId": { "type": "integer", "nullable": true }, "mergerName": { "type": "string" } }, "type": "object" }, "createdAt": { "description": "ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100" }, "externalId": { "type": "string" }, "autoMergeStrategy": { "type": "string", "enum": [ "immediately", "scheduled", "none" ] }, "autoMergeAt": { "description": "Scheduled auto-merge time in UTC, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T11:01:05+0000", "nullable": true }, "approvals": { "type": "array", "items": { "required": [ "approverId", "approverName", "createdAt" ], "properties": { "approverId": { "type": "string" }, "approverName": { "type": "string" }, "createdAt": { "description": "ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100" } }, "type": "object" } }, "reviewers": { "type": "array", "items": { "required": [ "id", "name", "email", "status" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "status": { "type": "string", "nullable": true, "enum": [ "approved", "rejected" ] } }, "type": "object" } } }, "type": "object" }, "MergeRequestWithChangeLogResponse": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/MergeRequestResponse" }, { "required": [ "changeLog" ], "properties": { "changeLog": { "description": "Configurations the merge request carries, as recorded by MergeRequest::updateChangeLog().", "properties": { "configurations": { "description": "Present only once review was requested or skipped; until then `changeLog` is `{}`.", "type": "array", "items": { "required": [ "componentId", "configurationId", "lastVersionIdentifier", "isDeleted" ], "properties": { "componentId": { "type": "string" }, "configurationId": { "type": "string" }, "lastVersionIdentifier": { "description": "Version of the configuration on the source branch at the time the change log was built.", "type": "string", "example": "01H5M1BDJHD1K6N3G14EZ8XDE2" }, "isDeleted": { "description": "Whether the configuration is deleted on the source branch.", "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } ] }, "MergeRequestDetailResponse": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/MergeRequestWithChangeLogResponse" }, { "properties": { "activityLog": { "description": "Chronological list of lifecycle events. Only present when `?include=activityLog` is provided.", "type": "array", "items": { "required": [ "id", "eventType", "admin", "note", "createdAt" ], "properties": { "id": { "type": "integer" }, "eventType": { "type": "string", "enum": [ "review_requested", "approved", "changes_requested", "merged", "canceled" ] }, "admin": { "description": "Acting admin. Null for system-initiated events (e.g. auto-merge).", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "note": { "description": "Free-text note. Empty string for events that do not carry a note (currently populated only for `changes_requested` events, where it holds the optional `reason` from the request).", "type": "string" }, "createdAt": { "description": "ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100" } }, "type": "object" } } } } ] }, "MergeRequestRejectRequest2": { "properties": { "reason": { "description": "Optional explanation why the merge request is being rejected. Stored in the activity log.", "type": "string", "nullable": true, "default": null, "maxLength": 1000 } }, "type": "object" }, "SearchTablesResponse": { "description": "Table matching the metadata search. Optional keys are present according to the `include` parameter.", "required": [ "uri", "id", "name", "displayName", "transactional", "primaryKey", "indexType", "indexKey", "distributionType", "distributionKey", "syntheticPrimaryKeyEnabled", "created", "lastImportDate", "lastChangeDate", "rowsCount", "dataSizeBytes", "isAlias", "isAliasable", "isTyped", "isDescriptionSystemManaged", "timestampType", "tableType", "path" ], "properties": { "uri": { "type": "string", "example": "https://connection.keboola.com/v2/storage/tables/in.c-application-testing.cashier-data" }, "id": { "type": "string", "example": "in.c-application-testing.cashier-data" }, "name": { "type": "string", "example": "cashier-data" }, "displayName": { "type": "string", "example": "cashier-data" }, "transactional": { "type": "boolean", "example": false }, "primaryKey": { "type": "array", "items": { "type": "string" } }, "indexType": { "type": "string", "nullable": true }, "indexKey": { "type": "array", "items": { "type": "string" } }, "distributionType": { "type": "string", "nullable": true }, "distributionKey": { "type": "array", "items": { "type": "string" } }, "syntheticPrimaryKeyEnabled": { "type": "boolean" }, "created": { "description": "Creation timestamp, ISO 8601 with a `+hhmm` offset; `null` for a zero date.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "lastImportDate": { "description": "Last import timestamp, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "lastChangeDate": { "description": "Last change timestamp, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "rowsCount": { "type": "integer", "nullable": true }, "dataSizeBytes": { "type": "integer", "nullable": true }, "isAlias": { "type": "boolean" }, "isAliasable": { "type": "boolean" }, "isTyped": { "type": "boolean" }, "isDescriptionSystemManaged": { "type": "boolean" }, "timestampType": { "type": "string", "example": "MANAGED" }, "tableType": { "type": "string", "example": "table" }, "path": { "type": "string", "example": "kbc_578.c-application-testing.cashier-data" }, "sourceTable": { "$ref": "#/components/schemas/TableSourceTableResponse" }, "aliasColumnsAutoSync": { "description": "Present only for simple (non-SQL) alias tables.", "type": "boolean" }, "aliasFilter": { "$ref": "#/components/schemas/AliasFilterResponse" }, "selectSql": { "description": "Present only for custom SQL aliases.", "type": "string" }, "isPersisted": { "description": "Whether the alias is persisted as a table in the backend. Present only for alias tables.", "type": "boolean" }, "attributes": { "description": "Deprecated, always empty. Present with `include=attributes` (default).", "type": "array", "items": { "type": "object" } }, "columns": { "description": "Present with `include=columns`.", "type": "array", "items": { "type": "string" } }, "bucket": { "$ref": "#/components/schemas/TableBucketResponse" }, "metadata": { "description": "Table metadata. Present with `include=metadata`.", "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } }, "columnMetadata": { "$ref": "#/components/schemas/TableColumnMetadataResponse" } }, "type": "object" }, "SharingTargetsListResponse": { "required": [ "projects", "users" ], "properties": { "projects": { "description": "Projects of the organization a bucket can be shared to, including the caller's own project.", "type": "array", "items": { "required": [ "id", "name" ], "properties": { "id": { "type": "integer", "example": 123 }, "name": { "type": "string", "example": "Project name" } }, "type": "object" } }, "users": { "description": "Admins of the organization's projects a bucket can be shared to, sorted by email.", "type": "array", "items": { "required": [ "id", "name", "email" ], "properties": { "id": { "type": "integer", "example": 5 }, "name": { "type": "string", "example": "Jan Developer" }, "email": { "type": "string", "example": "jan.dev@keboola.com" } }, "type": "object" } } }, "type": "object" }, "SnapshotDetailResponse": { "description": "Table snapshot with the snapshotted table settings.", "required": [ "id", "description", "createdTime", "type", "creatorToken", "actor", "uri", "dataFileId", "table" ], "properties": { "id": { "description": "Snapshot identifier.", "type": "string", "example": "20" }, "description": { "description": "Snapshot description.", "type": "string", "example": "", "nullable": true }, "createdTime": { "description": "ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2013-08-12T12:33:04+0200" }, "type": { "type": "string", "example": "table", "enum": [ "table" ] }, "creatorToken": { "required": [ "id", "description" ], "properties": { "id": { "type": "integer", "example": 221 }, "description": { "type": "string", "example": "Master Token" } }, "type": "object" }, "actor": { "description": "Who created the snapshot. Null only for a snapshot that records no creator.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "uri": { "type": "string", "example": "https://connection.keboola.com/v2/storage/snapshots/20" }, "dataFileId": { "description": "ID of the file holding the snapshot data.", "type": "integer", "example": 161757 }, "table": { "description": "Settings of the snapshotted table.", "required": [ "id", "primaryKey", "attributes", "columns" ], "properties": { "id": { "type": "string", "example": "in.c-dalsi.alias" }, "primaryKey": { "type": "array", "items": { "type": "string" }, "example": [] }, "attributes": { "description": "Deprecated, always an empty array.", "type": "array", "items": { "type": "object" }, "example": [] }, "columns": { "type": "array", "items": { "type": "string" }, "example": [ "id", "name" ] } }, "type": "object" } }, "type": "object" }, "StatsListResponse": { "description": "Import/export statistics of tables and files for a run ID.", "required": [ "tables", "files" ], "properties": { "tables": { "description": "Table import and export statistics aggregated from storage events.", "required": [ "import", "export" ], "properties": { "import": { "required": [ "totalCount", "tables" ], "properties": { "totalCount": { "description": "Total number of import events in the run.", "type": "integer" }, "tables": { "type": "array", "items": { "required": [ "id", "count", "durationTotalSeconds" ], "properties": { "id": { "description": "Table ID.", "type": "string", "example": "out.c-futurelytics.order_lines" }, "count": { "type": "integer", "example": 1 }, "durationTotalSeconds": { "type": "number", "format": "float", "example": 103.53 } }, "type": "object" } } }, "type": "object" }, "export": { "required": [ "totalCount", "tables" ], "properties": { "totalCount": { "description": "Total number of export events in the run.", "type": "integer" }, "tables": { "type": "array", "items": { "required": [ "id", "count", "durationTotalSeconds" ], "properties": { "id": { "description": "Table ID.", "type": "string", "example": "out.c-futurelytics.order_lines" }, "count": { "type": "integer", "example": 1 }, "durationTotalSeconds": { "type": "number", "format": "float", "example": 103.53 } }, "type": "object" } } }, "type": "object" } }, "type": "object" }, "files": { "description": "File upload statistics.", "required": [ "total", "tags" ], "properties": { "total": { "required": [ "count", "dataSizeBytes" ], "properties": { "count": { "description": "Number of files in the run.", "type": "integer" }, "dataSizeBytes": { "required": [ "total", "mean", "max", "min" ], "properties": { "total": { "type": "number" }, "mean": { "type": "number", "nullable": true }, "max": { "type": "number", "nullable": true }, "min": { "type": "number", "nullable": true } }, "type": "object" } }, "type": "object" }, "tags": { "required": [ "other", "tags" ], "properties": { "other": { "description": "Number of files with tags not listed in `tags`.", "type": "integer" }, "tags": { "type": "array", "items": { "required": [ "tag", "count", "dataSizeBytes" ], "properties": { "tag": { "type": "string" }, "count": { "type": "integer" }, "dataSizeBytes": { "required": [ "total", "mean", "max", "min" ], "properties": { "total": { "type": "number" }, "mean": { "type": "number", "nullable": true }, "max": { "type": "number", "nullable": true }, "min": { "type": "number", "nullable": true } }, "type": "object" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "ComponentMinimalInfoResponse": { "description": "Component reduced to its listing keys, as the index returns it with `exclude=componentDetails`.", "required": [ "id", "name", "type", "ico64", "ico128", "features", "flags", "description", "categories" ], "properties": { "id": { "description": "Unique identifier of the component", "type": "string", "example": "keboola.ex-db-mysql" }, "name": { "description": "Display name of the component", "type": "string", "example": "MySQL Database Extractor" }, "type": { "description": "Type of the component as the Developer Portal reports it, e.g. `extractor`, `writer`, `application` or `transformation`", "type": "string", "example": "extractor" }, "ico64": { "description": "64x64 icon URL", "type": "string", "nullable": true }, "ico128": { "description": "128x128 icon URL", "type": "string", "nullable": true }, "features": { "description": "List of component features", "type": "array", "items": { "type": "string" } }, "flags": { "description": "List of component flags", "type": "array", "items": { "type": "string" } }, "description": { "description": "Short description of the component", "type": "string", "example": "Extracts data from MySQL database" }, "categories": { "description": "List of component categories", "type": "array", "items": { "type": "string" }, "example": [ "extractor", "database" ] } }, "type": "object" }, "AliasFilterSetResponse": { "description": "The alias table with its filter applied. This is the plain table payload (no columns, metadata, attributes, bucket or definition).", "required": [ "uri", "id", "name", "displayName", "transactional", "primaryKey", "indexType", "indexKey", "distributionType", "distributionKey", "syntheticPrimaryKeyEnabled", "created", "lastImportDate", "lastChangeDate", "rowsCount", "dataSizeBytes", "isAlias", "isAliasable", "isTyped", "isDescriptionSystemManaged", "timestampType", "tableType", "path", "aliasColumnsAutoSync", "aliasFilter", "isPersisted" ], "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, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "lastImportDate": { "description": "Last import date, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "lastChangeDate": { "description": "Last change date, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "rowsCount": { "description": "Rows count (null for a filtered alias)", "type": "integer", "nullable": true }, "dataSizeBytes": { "description": "Data size in bytes (null for a filtered alias)", "type": "integer", "nullable": true }, "isAlias": { "description": "Is alias", "type": "boolean" }, "isAliasable": { "description": "Is aliasable", "type": "boolean" }, "isTyped": { "description": "Is typed table", "type": "boolean" }, "isDescriptionSystemManaged": { "description": "Whether the description is managed by the system", "type": "boolean" }, "timestampType": { "description": "Timestamp column type", "type": "string" }, "tableType": { "description": "Table type", "type": "string" }, "path": { "description": "Table path", "type": "string" }, "sourceTable": { "description": "Source table info. Present only when the alias has a resolved source table.", "required": [ "id", "uri", "project" ], "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" } }, "type": "object" }, "aliasColumnsAutoSync": { "description": "Alias columns auto sync", "type": "boolean" }, "aliasFilter": { "$ref": "#/components/schemas/AliasFilterResponse" }, "isPersisted": { "description": "Whether the alias is persisted", "type": "boolean" } }, "type": "object" }, "ExportTableRequest2": { "description": "Parameters for an asynchronous table export.", "properties": { "changedSince": { "description": "Export only rows imported since this time. Timestamp of import is stored within each row. Accepts a unix timestamp or a strtotime() compatible string (e.g. `-2 days`).", "type": "string", "example": "-2 days", "nullable": true }, "changedUntil": { "description": "Export only rows imported until this time. Accepts a unix timestamp or a strtotime() compatible string.", "type": "string", "example": "-1 day", "nullable": true }, "days": { "description": "Deprecated (use changedSince instead). Accepted for backward compatibility and ignored.", "type": "integer", "nullable": true, "deprecated": true }, "whereColumn": { "description": "Deprecated (use whereFilters instead). Column for exporting only matching rows.", "type": "string", "nullable": true, "deprecated": true }, "whereValues": { "description": "Deprecated (use whereFilters instead). Values for exporting only matching rows.", "type": "array", "items": { "type": "string" }, "nullable": true, "deprecated": true }, "whereOperator": { "description": "Deprecated (use whereFilters instead). Operator for value comparison.", "type": "string", "nullable": true, "deprecated": true, "default": "eq", "enum": [ "eq", "ne" ] }, "limit": { "description": "Limit the number of returned rows.", "type": "integer", "example": 1000, "nullable": true, "minimum": 0 }, "columns": { "description": "Comma separated list of columns to export; by default all columns are exported.", "type": "string", "example": "id,name", "nullable": true }, "format": { "description": "File format: `rfc` (CSV according to RFC 4180) or `json`.", "type": "string", "nullable": true, "default": "rfc", "enum": [ "rfc", "json" ] }, "whereFilters": { "description": "Row filters, joined by AND.", "type": "array", "items": { "$ref": "#/components/schemas/WhereFiltersObject" }, "example": [ { "column": "UserID", "operator": "eq", "values": [ "123", "234" ] } ], "nullable": true }, "orderBy": { "description": "Sort conditions.", "type": "array", "items": { "$ref": "#/components/schemas/OrderByObject" }, "example": [ { "column": "Price", "order": "DESC", "dataType": "DOUBLE" } ], "nullable": true }, "sourceBranchId": { "description": "Branch id to load the source from. If not provided, the default branch is used. Honoured only for JSON requests.", "type": "integer", "example": 1234, "nullable": true }, "gzip": { "description": "The exported file will be gzipped if set to true.", "type": "boolean", "default": false }, "includeInternalTimestamp": { "description": "Include the internal `_timestamp` column (timestamp of the last row change) in the exported data, even when not in the columns list. Snowflake only.", "type": "boolean", "default": false }, "fileType": { "description": "Type of the file created in File Storage. Parquet is supported on Snowflake only. Parquet writes `TIMESTAMP_LTZ` and `TIMESTAMP_TZ` columns as UTC wall-clock `TIMESTAMP_NTZ`; the original offset is not kept.", "type": "string", "default": "csv", "enum": [ "csv", "parquet" ] }, "timezone": { "description": "IANA timezone name (e.g. `America/Los_Angeles`, `Europe/Prague`). When set, the Snowflake session timezone is configured before export, affecting TIMESTAMP_LTZ column display. Not supported for Parquet exports. Snowflake only.", "type": "string", "example": "Europe/Prague", "nullable": true }, "legacyTimestampFilterKind": { "type": "string", "nullable": true, "default": null } }, "type": "object" }, "ImportSyncResponse": { "description": "Result of a synchronous table import.", "required": [ "transaction", "warnings", "importedColumns", "totalRowsCount", "totalDataSizeBytes", "importedRowsCount", "newColumns" ], "properties": { "transaction": { "description": "Always `null`, kept for backward compatibility.", "type": "string", "example": null, "nullable": true, "enum": [ null ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "importedColumns": { "description": "Columns the data was imported into.", "type": "array", "items": { "type": "string" } }, "totalRowsCount": { "type": "integer" }, "totalDataSizeBytes": { "type": "integer" }, "importedRowsCount": { "description": "For a full load this equals `totalRowsCount`; for an incremental load it is the number of imported rows.", "type": "integer" }, "newColumns": { "description": "Columns added to the table by the import. An object keyed by the column's position in the import when the new columns do not lead the column list, e.g. `{\"2\": \"c\"}`.", "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "additionalProperties": { "type": "string" } } ] } }, "type": "object" }, "ProfileResponse": { "required": [ "uuid", "bucketId", "tableName", "createdAt", "profile", "columns", "profiledByToken", "actor" ], "properties": { "uuid": { "description": "Profile identifier (UUID v7).", "type": "string", "example": "019732aa-6f92-77ea-a715-865a695908b8" }, "bucketId": { "description": "Internal numeric id of the bucket.", "type": "integer", "example": 13 }, "tableName": { "description": "Table string id.", "type": "string", "example": "in.c-main.another" }, "createdAt": { "description": "When the profile was created (`Y-m-d H:i:s`).", "type": "string", "example": "2025-06-02 11:55:00" }, "profile": { "description": "Table-level profile metrics. Produced by the storage driver (`CreateProfileTableCommand`); the metric set is backend-specific and passed through unchanged.", "type": "object", "additionalProperties": {} }, "columns": { "description": "Per-column profiles.", "type": "array", "items": { "required": [ "name", "profile" ], "properties": { "name": { "description": "Column name.", "type": "string", "example": "id" }, "profile": { "description": "Column-level profile metrics. Produced by the storage driver (`CreateProfileTableCommand`); the metric set is backend-specific and passed through unchanged.", "type": "object", "additionalProperties": {} } }, "type": "object" } }, "profiledByToken": { "description": "Token that created the profile.", "required": [ "id", "name" ], "properties": { "id": { "type": "integer", "format": "int64", "example": 221 }, "name": { "type": "string", "example": "Master Token" } }, "type": "object" }, "actor": { "description": "Who created the profile and through which credential; null only for a legacy profile whose token id no actor can describe.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] } }, "type": "object" }, "TableSnapshotResponse": { "required": [ "id", "description", "createdTime", "type", "creatorToken", "actor", "uri", "dataFileId" ], "properties": { "id": { "type": "string" }, "description": { "type": "string", "nullable": true }, "createdTime": { "description": "ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100" }, "type": { "type": "string" }, "creatorToken": { "required": [ "id", "description" ], "properties": { "id": { "type": "integer" }, "description": { "type": "string" } }, "type": "object" }, "actor": { "description": "Who created the snapshot. Null only for a snapshot that records no creator.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "uri": { "type": "string" }, "dataFileId": { "type": "integer" } }, "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" }, "TableAttributionResponse": { "description": "The component, configuration, configuration row and branch recorded as having created or last written the table. Informational only: it mirrors the provider `system` `KBC.createdBy.*` / `KBC.lastUpdatedBy.*` table metadata, which Output Mapping writes and any token with write access to the bucket can also set through the metadata API. An alias with `aliasColumnsAutoSync: true`, including a table of a linked bucket, shows the values of its root table; an alias with a curated column set shows its own values.", "required": [ "componentId", "configurationId", "configurationRowId", "branchId" ], "properties": { "componentId": { "description": "Component ID.", "type": "string", "example": "keboola.snowflake-transformation", "nullable": true }, "configurationId": { "description": "Configuration ID; `null` for a write without a configuration, such as a workspace unload.", "type": "string", "example": "12345", "nullable": true }, "configurationRowId": { "description": "Configuration row ID; set for row-based configurations only.", "type": "string", "example": "67890", "nullable": true }, "branchId": { "description": "Branch ID; set only when the write came from a development branch.", "type": "string", "example": "1234", "nullable": true } }, "type": "object" }, "TableDetailResponse": { "required": [ "uri", "id", "name", "displayName", "transactional", "primaryKey", "indexType", "indexKey", "distributionType", "distributionKey", "syntheticPrimaryKeyEnabled", "created", "lastImportDate", "lastChangeDate", "rowsCount", "dataSizeBytes", "isAlias", "isAliasable", "isTyped", "isDescriptionSystemManaged", "timestampType", "tableType", "path", "columns", "columnMetadata", "attributes", "metadata", "bucket", "definition", "createdBy", "lastUpdatedBy" ], "properties": { "uri": { "description": "Table detail URI", "type": "string" }, "id": { "description": "Table identifier", "type": "string" }, "name": { "description": "Table name", "type": "string" }, "displayName": { "description": "Display name of the table", "type": "string" }, "transactional": { "description": "Transactional flag", "type": "boolean" }, "primaryKey": { "type": "array", "items": { "type": "string" } }, "indexType": { "type": "string", "nullable": true }, "indexKey": { "type": "array", "items": { "type": "string" } }, "distributionType": { "type": "string", "nullable": true }, "distributionKey": { "type": "array", "items": { "type": "string" } }, "syntheticPrimaryKeyEnabled": { "type": "boolean" }, "created": { "description": "Created timestamp, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "lastImportDate": { "description": "Last import date, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "lastChangeDate": { "description": "Last change date, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "rowsCount": { "type": "integer", "nullable": true }, "dataSizeBytes": { "type": "integer", "nullable": true }, "isAlias": { "type": "boolean" }, "isAliasable": { "type": "boolean" }, "isTyped": { "type": "boolean" }, "isDescriptionSystemManaged": { "description": "True when the table description is managed by the system.", "type": "boolean" }, "timestampType": { "description": "How the `_timestamp` column is managed.", "type": "string", "enum": [ "MANAGED", "SELFMANAGED", "NONE" ] }, "tableType": { "type": "string" }, "path": { "type": "string" }, "columns": { "type": "array", "items": { "type": "string" } }, "columnMetadata": { "$ref": "#/components/schemas/TableColumnMetadataResponse" }, "attributes": { "description": "Always an empty array, kept for backward compatibility.", "type": "array", "items": { "type": "object" } }, "metadata": { "description": "Table metadata records.", "type": "array", "items": { "$ref": "#/components/schemas/MetadataItemResponse" } }, "bucket": { "$ref": "#/components/schemas/TableBucketResponse" }, "sourceTable": { "$ref": "#/components/schemas/TableSourceTableResponse" }, "aliasColumnsAutoSync": { "description": "Present only for simple aliases.", "type": "boolean" }, "aliasFilter": { "$ref": "#/components/schemas/AliasFilterResponse" }, "selectSql": { "description": "Present only for custom SQL aliases.", "type": "string" }, "isPersisted": { "description": "Whether the alias is persisted as a table in the backend. Present only for alias tables.", "type": "boolean" }, "definition": { "$ref": "#/components/schemas/TableDefinitionResponse" }, "createdBy": { "oneOf": [ { "$ref": "#/components/schemas/TableAttributionResponse" } ], "nullable": true, "description": "What created the table; `null` when nothing is recorded. An alias with `aliasColumnsAutoSync: true` shows its root table's value." }, "lastUpdatedBy": { "oneOf": [ { "$ref": "#/components/schemas/TableAttributionResponse" } ], "nullable": true, "description": "What last wrote the table; `null` when nothing is recorded. An alias with `aliasColumnsAutoSync: true` shows its root table's value." } }, "type": "object" }, "TableEventAttachmentResponse": { "required": [ "id", "isSliced", "uploadType", "isExpired", "created", "name", "url", "sizeBytes" ], "properties": { "id": { "description": "Attachment file ID.", "type": "integer" }, "isSliced": { "description": "Whether the file is sliced.", "type": "boolean" }, "uploadType": { "description": "Upload type of the file.", "type": "string" }, "isExpired": { "description": "Whether the file is expired.", "type": "boolean" }, "created": { "description": "Attachment creation timestamp, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100" }, "name": { "description": "Attachment file name.", "type": "string" }, "url": { "description": "Attachment download URL.", "type": "string" }, "sizeBytes": { "description": "Attachment file size in bytes.", "type": "integer", "nullable": true } }, "type": "object" }, "TableEventResponse": { "required": [ "uuid", "event", "message", "description", "type", "component", "runId", "configurationId", "objectId", "objectName", "objectType", "idBranch", "token", "context", "created", "uri", "params", "results", "performance", "attachments" ], "properties": { "uuid": { "description": "Unique identifier of the event.", "type": "string" }, "event": { "description": "Name of the event.", "type": "string" }, "message": { "description": "Event message.", "type": "string" }, "description": { "description": "Event description.", "type": "string" }, "type": { "description": "Type of the event.", "type": "string", "example": "info", "enum": [ "info", "success", "warn", "error" ] }, "component": { "description": "Component name.", "type": "string" }, "runId": { "description": "Run ID of the event.", "type": "string", "nullable": true }, "configurationId": { "description": "Configuration ID associated with the event.", "type": "string", "nullable": true }, "objectId": { "description": "ID of the object the event relates to.", "type": "string" }, "objectName": { "description": "Name of the object the event relates to.", "type": "string" }, "objectType": { "description": "Type of the object the event relates to.", "type": "string" }, "idBranch": { "description": "ID of the branch the event belongs to; `null` when the event is not tied to a branch.", "type": "integer", "nullable": true }, "token": { "description": "Token that produced the event.", "required": [ "id", "name" ], "properties": { "id": { "description": "Token ID.", "type": "integer" }, "name": { "description": "Token name.", "type": "string", "nullable": true } }, "type": "object" }, "context": { "description": "Request context the event was created in; an empty array `[]` when the event has no context.", "oneOf": [ { "properties": { "httpUserAgent": { "description": "User agent of the request.", "type": "string", "nullable": true }, "authorization": { "description": "Authorization type of the request.", "type": "string" }, "httpUserAgentOriginal": { "description": "Original user agent of the request. Present only when the request sent `X-User-Agent`.", "type": "string", "nullable": true }, "httpReferer": { "description": "Referer of the request.", "type": "string", "nullable": true }, "remoteAddr": { "description": "Remote address of the request.", "type": "string", "nullable": true }, "apiVersion": { "description": "API version of the request or of the job that raised the event.", "type": "string" }, "userAgent": { "description": "User agent of the request that created the job. Present only on events raised by a job.", "type": "string" }, "async": { "description": "Always `true`. Present only on events raised by a job.", "type": "boolean" } }, "type": "object" }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "created": { "description": "Event creation timestamp, ISO 8601 with a `+hhmm` offset; `\"\"` when none was recorded.", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4})?$", "example": "2017-02-13T12:01:05+0100" }, "uri": { "description": "Link to the event details.", "type": "string" }, "params": { "description": "Event parameters.", "type": "object" }, "results": { "description": "Event results.", "type": "object" }, "performance": { "description": "Event performance metrics.", "type": "object" }, "attachments": { "description": "Files attached to the event.", "type": "array", "items": { "$ref": "#/components/schemas/TableEventAttachmentResponse" } } }, "type": "object" }, "TableEventsListResponse": { "type": "array", "items": { "$ref": "#/components/schemas/TableEventResponse" } }, "TableListV2BucketResponse": { "description": "The bucket the table row comes from.", "required": [ "id", "name", "displayName", "stage", "backend", "idBranch" ], "properties": { "id": { "description": "Bucket ID.", "type": "string", "example": "in.c-main" }, "name": { "description": "Bucket name.", "type": "string", "example": "c-main" }, "displayName": { "description": "Bucket display name.", "type": "string", "example": "main" }, "stage": { "description": "Bucket stage.", "type": "string", "example": "in", "enum": [ "in", "out", "sys" ] }, "backend": { "description": "Storage backend of the bucket.", "type": "string", "example": "snowflake" }, "idBranch": { "description": "ID of the branch the bucket belongs to.", "type": "integer", "example": 1234 } }, "type": "object" }, "TableListV2SourceProjectResponse": { "description": "The project of an alias source table.", "required": [ "id", "name" ], "properties": { "id": { "description": "Project ID.", "type": "integer", "example": 123 }, "name": { "description": "Project name as recorded when the alias was created.", "type": "string", "example": "Sales", "nullable": true } }, "type": "object" }, "TableListV2MetadataResponse": { "description": "A table-level metadata record, as `GET /v2/storage/tables/{tableId}/metadata` returns it.", "required": [ "id", "key", "value", "provider", "timestamp" ], "properties": { "id": { "description": "Metadata record identifier.", "type": "string", "example": "19509" }, "key": { "description": "Metadata key.", "type": "string", "example": "KBC.createdBy.component.id" }, "value": { "description": "Metadata value.", "type": "string", "example": "keboola.ex-db-snowflake", "nullable": true }, "provider": { "description": "ID of the component that created the metadata.", "type": "string", "example": "system" }, "timestamp": { "description": "When the metadata was created or last updated, ISO 8601 with a `+hhmm` offset; empty when unknown.", "type": "string", "example": "2017-02-13T23:36:10+0100" } }, "type": "object" }, "TableListV2SourceTableResponse": { "description": "The table an alias reads from.", "required": [ "id", "project" ], "properties": { "id": { "description": "Source table ID.", "type": "string", "example": "in.c-main.users" }, "project": { "$ref": "#/components/schemas/TableListV2SourceProjectResponse" }, "metadata": { "description": "With `include=metadata` only: the table-level metadata of the root source table; `null` for an alias that does not sync its columns.", "type": "array", "items": { "$ref": "#/components/schemas/TableListV2MetadataResponse" }, "nullable": true } }, "type": "object" }, "TableListV2AliasFilterResponse": { "description": "The row filter of a filtered alias.", "required": [ "column", "operator", "values" ], "properties": { "column": { "description": "Filtered column.", "type": "string", "example": "city" }, "operator": { "description": "Comparison operator.", "type": "string", "example": "eq", "nullable": true, "enum": [ "eq", "ne" ] }, "values": { "description": "Values the column is compared with, as stored; older filters may hold numbers.", "type": "array", "items": {}, "example": [ "PRG" ], "nullable": true } }, "type": "object" }, "TableListV2ItemResponse": { "description": "A table of the list. Lighter than the table detail (`GET /v2/storage/tables/{tableId}`), which carries everything else.", "required": [ "id", "bucketId", "name", "displayName", "branchId", "bucket", "primaryKey", "isAlias", "isAliasable", "isTyped", "tableType", "rowsCount", "dataSizeBytes", "created", "lastImportDate", "lastChangeDate", "description", "isDescriptionSystemManaged", "createdBy", "lastUpdatedBy" ], "properties": { "id": { "description": "Table ID.", "type": "string", "example": "in.c-main.users" }, "bucketId": { "description": "ID of the table bucket.", "type": "string", "example": "in.c-main" }, "name": { "description": "Table name.", "type": "string", "example": "users" }, "displayName": { "description": "Table display name.", "type": "string", "example": "users" }, "branchId": { "description": "ID of the branch the row comes from, the branch of its bucket.", "type": "integer", "example": 1234 }, "bucket": { "$ref": "#/components/schemas/TableListV2BucketResponse" }, "primaryKey": { "description": "Primary key column names.", "type": "array", "items": { "type": "string" }, "example": [ "id" ] }, "isAlias": { "description": "Whether the table is an alias.", "type": "boolean", "example": false }, "isAliasable": { "description": "Whether an alias can be created from the table: true for a table that is not an alias, and for an alias that follows the source columns and is neither filtered nor a custom-SQL alias.", "type": "boolean", "example": true }, "isTyped": { "description": "Whether the table is typed.", "type": "boolean", "example": true }, "tableType": { "description": "Kind of the backend object.", "type": "string", "example": "table" }, "rowsCount": { "description": "Number of rows; `null` for a filtered alias.", "type": "integer", "example": 1000, "nullable": true }, "dataSizeBytes": { "description": "Data size in bytes; `null` for a filtered alias.", "type": "integer", "example": 65536, "nullable": true }, "created": { "description": "Creation time.", "type": "string", "format": "date-time", "example": "2026-10-22T10:00:00+0200", "nullable": true }, "lastImportDate": { "description": "Last import time.", "type": "string", "format": "date-time", "example": "2026-10-22T10:05:00+0200", "nullable": true }, "lastChangeDate": { "description": "Last change time.", "type": "string", "format": "date-time", "example": "2026-10-22T10:05:00+0200", "nullable": true }, "description": { "description": "Table description, from the native description field only: a description kept only in the legacy `KBC.description` metadata is not shown. An alias that syncs its columns falls back to the description of its source chain.", "type": "string", "example": "Registered users", "nullable": true }, "isDescriptionSystemManaged": { "description": "Whether the description is maintained by the system rather than a user.", "type": "boolean", "example": true }, "createdBy": { "oneOf": [ { "$ref": "#/components/schemas/TableAttributionResponse" } ], "nullable": true, "description": "What created the table; `null` when nothing is recorded. An alias with `aliasColumnsAutoSync: true` shows its root table's value." }, "lastUpdatedBy": { "oneOf": [ { "$ref": "#/components/schemas/TableAttributionResponse" } ], "nullable": true, "description": "What last wrote the table; `null` when nothing is recorded. An alias with `aliasColumnsAutoSync: true` shows its root table's value." }, "sourceTable": { "oneOf": [ { "$ref": "#/components/schemas/TableListV2SourceTableResponse" } ], "nullable": true, "description": "Aliases only: the source table.", "default": null }, "aliasColumnsAutoSync": { "description": "Aliases other than custom-SQL aliases only: whether the alias follows the source columns.", "type": "boolean", "nullable": true, "default": null }, "aliasFilter": { "oneOf": [ { "$ref": "#/components/schemas/TableListV2AliasFilterResponse" } ], "nullable": true, "description": "Filtered aliases only: the row filter.", "default": null }, "selectSql": { "description": "Custom-SQL aliases only: the SQL of the alias.", "type": "string", "nullable": true, "default": null }, "columns": { "description": "With `include=columns` only: the column names in the order of the table detail.", "type": "array", "items": { "type": "string" }, "example": [ "id", "name" ], "nullable": true, "default": null }, "metadata": { "description": "With `include=metadata` only: the table-level metadata, as `GET /v2/storage/tables/{tableId}/metadata` returns it.", "type": "array", "items": { "$ref": "#/components/schemas/TableListV2MetadataResponse" }, "nullable": true, "default": null }, "definition": { "oneOf": [ { "$ref": "#/components/schemas/TableDefinitionResponse" } ], "nullable": true, "description": "With `include=definition` only: the table definition, equal to the `definition` of the table detail. `null` for a typed table whose column types are not all on the native fields (the detail reads the legacy metadata for it), and for an alias of such a table. The table `description` comes from the native field only; the detail falls back to the legacy `KBC.description` table metadata when it is empty.", "default": null } }, "type": "object" }, "PaginationMeta": { "required": [ "total", "limit", "cursor" ], "properties": { "total": { "description": "Number of items matching the filters, ignoring pagination.", "type": "integer" }, "limit": { "description": "Page size applied (`page[limit]`).", "type": "integer" }, "cursor": { "description": "How to build the `page[after]` cursor from the last row read, without another call.", "required": [ "param", "encoding", "fields", "order" ], "properties": { "param": { "description": "Query parameter the cursor goes in.", "type": "string", "example": "page[after]" }, "encoding": { "description": "base64url (RFC 4648 \u00a75, padding optional) of a JSON object.", "type": "string", "example": "base64url(json)" }, "fields": { "description": "Keys of the JSON object, each the last row's value of the item field of the same name.", "type": "array", "items": { "required": [ "name", "type", "nullable" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "integer", "string", "date-time" ] }, "nullable": { "type": "boolean" } }, "type": "object" } }, "order": { "description": "Order of the rows; the cursor keys follow it.", "type": "string", "example": "deletedTime DESC NULLS LAST, id DESC" } }, "type": "object" } }, "type": "object" }, "PaginationLinks": { "required": [ "self", "first", "next" ], "properties": { "self": { "description": "This page.", "type": "string", "format": "uri" }, "first": { "description": "The first page (no `page[after]`).", "type": "string", "format": "uri" }, "next": { "description": "The page after this one; `null` on the last page.", "type": "string", "format": "uri", "nullable": true } }, "type": "object" }, "TableListV2Response": { "required": [ "data", "meta", "links" ], "properties": { "data": { "description": "Tables on the requested page.", "type": "array", "items": { "$ref": "#/components/schemas/TableListV2ItemResponse" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } }, "type": "object" }, "GenerateNewIdResponse": { "required": [ "id" ], "properties": { "id": { "description": "New unique sequential 64 bit ID, returned as a string.", "type": "string", "example": "123454352345" } }, "type": "object" }, "TokenListResponse": { "required": [ "id", "created", "refreshed", "description", "uri", "isMasterToken", "canManageBuckets", "canManageTokens", "canReadAllFileUploads", "canPurgeTrash", "canManageProtectedDefaultBranch", "canCreateJobs", "canReadAllProjectEvents", "canManageDevBranches", "expires", "isExpired", "isDisabled", "dailyCapacity", "actor", "bucketPermissions" ], "properties": { "id": { "description": "Unique identifier of the token.", "type": "string" }, "created": { "description": "Token creation timestamp, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "nullable": true }, "refreshed": { "description": "Token last refresh timestamp, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "nullable": true }, "description": { "description": "User-provided description of the token.", "type": "string" }, "uri": { "description": "URI to retrieve detailed token information.", "type": "string" }, "isMasterToken": { "description": "Whether this is a master token.", "type": "boolean" }, "canManageBuckets": { "description": "Token permission to manage buckets.", "type": "boolean" }, "canManageTokens": { "description": "Token permission to manage tokens.", "type": "boolean" }, "canReadAllFileUploads": { "description": "Token permission to read all file uploads.", "type": "boolean" }, "canPurgeTrash": { "description": "Token permission to purge trash.", "type": "boolean" }, "canManageProtectedDefaultBranch": { "description": "Token permission to manage protected default branch.", "type": "boolean" }, "canCreateJobs": { "description": "Token permission to create jobs.", "type": "boolean" }, "canReadAllProjectEvents": { "description": "Token permission to read all project events.", "type": "boolean" }, "canManageDevBranches": { "description": "Token permission to manage dev branches.", "type": "boolean" }, "expires": { "description": "Expiration timestamp of the token, ISO 8601 with a `+hhmm` offset; null when the token never expires.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "nullable": true }, "isExpired": { "description": "Whether the token is expired.", "type": "boolean" }, "isDisabled": { "description": "Whether the token is disabled.", "type": "boolean" }, "dailyCapacity": { "description": "Daily capacity of the token.", "type": "integer" }, "token": { "description": "Decrypted token value. Present only when the project has a dedicated project feature enabled, the default branch is not protected and the token cannot manage the protected default branch.", "type": "string" }, "creatorToken": { "description": "Token that created this token. Present only when the token was created by another token.", "required": [ "id", "description" ], "properties": { "id": { "description": "ID of the creator token.", "type": "integer", "format": "int64" }, "description": { "description": "Description of the creator token.", "type": "string" } }, "type": "object" }, "actor": { "description": "Who created this token and through which credential, not the identity of this token; null when no creator is recorded.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "componentAccess": { "description": "Allowed components to access. Present only when at least one component is granted.", "type": "array", "items": { "type": "string" } }, "bucketPermissions": { "description": "Bucket permissions map; an empty array `[]` when the token has no bucket permissions.", "oneOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "array", "items": {}, "maxItems": 0 } ] }, "admin": { "description": "Administrator the token belongs to. Present only when the token belongs to an administrator.", "required": [ "name", "id", "role" ], "properties": { "name": { "description": "Admin name.", "type": "string" }, "id": { "description": "Admin ID.", "type": "integer" }, "role": { "description": "Admin role. Null when the project membership has no role stored.", "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" }, "TokensListResponse": { "type": "array", "items": { "$ref": "#/components/schemas/TokenListResponse" } }, "TokenCreateResponse": { "required": [ "id", "created", "refreshed", "description", "uri", "isMasterToken", "canManageBuckets", "canManageTokens", "canReadAllFileUploads", "canPurgeTrash", "canManageProtectedDefaultBranch", "canCreateJobs", "canReadAllProjectEvents", "canManageDevBranches", "expires", "isExpired", "isDisabled", "dailyCapacity", "actor", "bucketPermissions" ], "properties": { "id": { "description": "Unique identifier of the token.", "type": "string", "example": "484" }, "created": { "description": "Token creation timestamp, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "refreshed": { "description": "Token last refresh timestamp, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "description": { "description": "User-provided description of the token.", "type": "string", "example": "my-new-token" }, "uri": { "description": "URI of the token detail.", "type": "string", "example": "https://connection.keboola.com/v2/storage/tokens/484" }, "isMasterToken": { "description": "Whether this is a master (admin) token.", "type": "boolean" }, "canManageBuckets": { "description": "Token permission to manage all buckets.", "type": "boolean" }, "canManageTokens": { "description": "Token permission to manage tokens.", "type": "boolean" }, "canReadAllFileUploads": { "description": "Token permission to read all file uploads.", "type": "boolean" }, "canPurgeTrash": { "description": "Token permission to permanently remove deleted configurations.", "type": "boolean" }, "canManageProtectedDefaultBranch": { "description": "Token permission to manage the protected default branch.", "type": "boolean" }, "canCreateJobs": { "description": "Token permission to create jobs.", "type": "boolean" }, "canReadAllProjectEvents": { "description": "Token permission to read all project events.", "type": "boolean" }, "canManageDevBranches": { "description": "Token permission to manage development branches.", "type": "boolean" }, "expires": { "description": "Expiration timestamp of the token, ISO 8601 with a `+hhmm` offset; null when the token never expires.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "nullable": true }, "isExpired": { "description": "Whether the token is expired.", "type": "boolean" }, "isDisabled": { "description": "Whether the token is disabled.", "type": "boolean" }, "dailyCapacity": { "description": "Daily capacity of the token.", "type": "integer", "example": 5 }, "token": { "description": "Decrypted token value. Present only in the create response; omitted on update.", "type": "string", "example": "75-12d4bfa4995694a1c956e7bb1eea0df5cc53acdb" }, "creatorToken": { "description": "Token that created this token. Present only when the token was created by another token.", "required": [ "id", "description" ], "properties": { "id": { "description": "ID of the creator token.", "type": "integer", "format": "int64", "example": 1 }, "description": { "description": "Description of the creator token.", "type": "string", "example": "dev@keboola.com" } }, "type": "object" }, "actor": { "description": "Who created this token and through which credential, not the identity of this token; null when no creator is recorded.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "componentAccess": { "description": "Component IDs the token may access. Present only when at least one component is granted.", "type": "array", "items": { "type": "string" }, "example": [ "keboola.ex-db-mysql" ] }, "bucketPermissions": { "description": "Bucket permissions keyed by bucket ID (`read`, `write` or `manage`).", "type": "object", "example": { "in.c-main": "read" }, "additionalProperties": { "type": "string" } } }, "type": "object" }, "TokenRefreshResponse": { "required": [ "id", "created", "refreshed", "description", "uri", "isMasterToken", "canManageBuckets", "canManageTokens", "canReadAllFileUploads", "canPurgeTrash", "canManageProtectedDefaultBranch", "canCreateJobs", "canReadAllProjectEvents", "canManageDevBranches", "expires", "isExpired", "isDisabled", "dailyCapacity", "actor", "bucketPermissions" ], "properties": { "id": { "description": "Unique identifier of the token.", "type": "string", "example": "484" }, "created": { "description": "Token creation timestamp, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "refreshed": { "description": "Token last refresh timestamp, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "description": { "description": "User-provided description of the token.", "type": "string", "example": "my-new-token" }, "uri": { "description": "URI of the token detail.", "type": "string", "example": "https://connection.keboola.com/v2/storage/tokens/484" }, "isMasterToken": { "description": "Whether this is a master (admin) token.", "type": "boolean" }, "canManageBuckets": { "description": "Token permission to manage all buckets.", "type": "boolean" }, "canManageTokens": { "description": "Token permission to manage tokens.", "type": "boolean" }, "canReadAllFileUploads": { "description": "Token permission to read all file uploads.", "type": "boolean" }, "canPurgeTrash": { "description": "Token permission to permanently remove deleted configurations.", "type": "boolean" }, "canManageProtectedDefaultBranch": { "description": "Token permission to manage the protected default branch.", "type": "boolean" }, "canCreateJobs": { "description": "Token permission to create jobs.", "type": "boolean" }, "canReadAllProjectEvents": { "description": "Token permission to read all project events.", "type": "boolean" }, "canManageDevBranches": { "description": "Token permission to manage development branches.", "type": "boolean" }, "expires": { "description": "Expiration timestamp of the token, ISO 8601 with a `+hhmm` offset; null when the token never expires.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "nullable": true }, "isExpired": { "description": "Whether the token is expired.", "type": "boolean" }, "isDisabled": { "description": "Whether the token is disabled.", "type": "boolean" }, "dailyCapacity": { "description": "Daily capacity of the token.", "type": "integer", "example": 5 }, "token": { "description": "Decrypted token value. Present only for non-master tokens, for the token used for authorization, or when the project has a dedicated project feature enabled.", "type": "string", "example": "75-12d4bfa4995694a1c956e7bb1eea0df5cc53acdb" }, "creatorToken": { "description": "Token that created this token. Present only when the token was created by another token.", "required": [ "id", "description" ], "properties": { "id": { "description": "ID of the creator token.", "type": "integer", "format": "int64", "example": 1 }, "description": { "description": "Description of the creator token.", "type": "string", "example": "dev@keboola.com" } }, "type": "object" }, "actor": { "description": "Who created this token and through which credential, not the identity of this token; null when no creator is recorded.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "componentAccess": { "description": "Component IDs the token may access. Present only when at least one component is granted.", "type": "array", "items": { "type": "string" }, "example": [ "keboola.ex-db-mysql" ] }, "bucketPermissions": { "description": "Bucket permissions keyed by bucket ID (`read`, `write` or `manage`).", "type": "object", "example": { "in.c-main": "read" }, "additionalProperties": { "type": "string" } } }, "type": "object" }, "TriggerResponse": { "required": [ "id", "runWithTokenId", "component", "configurationId", "lastRun", "creatorToken", "actor", "coolDownPeriodMinutes", "tables" ], "properties": { "id": { "description": "Trigger ID.", "type": "string", "example": "3" }, "runWithTokenId": { "description": "ID of token used for running configured component.", "type": "integer", "example": 123 }, "component": { "description": "Component ID of the triggered configuration.", "type": "string", "example": "orchestration" }, "configurationId": { "description": "ID of component configuration.", "type": "string", "example": "config-100" }, "lastRun": { "description": "Time of the last trigger run, ISO 8601 with a `+hhmm` offset; `null` if never fired.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "creatorToken": { "description": "Token that created the trigger.", "required": [ "id", "description" ], "properties": { "id": { "description": "Token ID.", "type": "integer", "format": "int64", "example": 1 }, "description": { "description": "Token description.", "type": "string", "example": "dev@keboola.com" } }, "type": "object" }, "actor": { "$ref": "#/components/schemas/ActorResponse" }, "coolDownPeriodMinutes": { "description": "Minimal cool down period before firing action again in minutes.", "type": "integer", "example": 20 }, "tables": { "description": "Watched tables.", "type": "array", "items": { "required": [ "tableId" ], "properties": { "tableId": { "description": "Table ID.", "type": "string", "example": "in.c-test.watched-1" } }, "type": "object" } } }, "type": "object" }, "WebalizeColumnNamesResponse": { "required": [ "columnNames" ], "properties": { "columnNames": { "description": "Webalized column names, in the order they were sent. Each one satisfies `StorageColumnName` unless the input had no usable character left, in which case it is an empty string \u2014 so the items are deliberately not `$ref`ed to that component.", "type": "array", "items": { "type": "string" }, "example": [ "First_Column_Name", "Second_Column_Name" ] } }, "type": "object" }, "WebalizeDisplayNameResponse": { "required": [ "displayName" ], "properties": { "displayName": { "description": "The input normalised into a name the create and update endpoints accept.", "type": "string", "example": "My-Display-Name", "allOf": [ { "$ref": "#/components/schemas/StorageName" } ] } }, "type": "object" }, "InputMappingLoadPreviewResponse": { "required": [ "input" ], "properties": { "input": { "type": "array", "items": { "required": [ "source", "destination", "loadType", "possibleLoadTypes" ], "properties": { "source": { "type": "string" }, "destination": { "type": "string" }, "loadType": { "type": "string", "enum": [ "COPY", "CLONE", "VIEW" ] }, "possibleLoadTypes": { "type": "array", "items": { "type": "string", "enum": [ "COPY", "CLONE", "VIEW" ] } } }, "type": "object" } } }, "type": "object" }, "ObjectListResponse": { "required": [ "name", "type" ], "properties": { "name": { "description": "Name of the object in the workspace.", "type": "string" }, "type": { "description": "Type of the object.", "type": "string", "enum": [ "table", "view" ] } }, "type": "object" }, "InputMappingLoadDryRunResponse": { "required": [ "dryRun", "operationName", "input" ], "properties": { "dryRun": { "type": "boolean" }, "operationName": { "type": "string" }, "input": { "type": "array", "items": { "required": [ "source", "destination", "loadType", "possibleLoadTypes" ], "properties": { "source": { "type": "string" }, "destination": { "type": "string" }, "loadType": { "type": "string", "enum": [ "COPY", "CLONE", "VIEW" ] }, "possibleLoadTypes": { "type": "array", "items": { "type": "string", "enum": [ "COPY", "CLONE", "VIEW" ] } } }, "type": "object" } } }, "type": "object" }, "LoadRequestInputTable": { "description": "One table to load into the workspace, as an item of `LoadRequest.input`. Exactly one of `source` or `dataFileId` is required, together with `destination`.", "required": [ "destination" ], "properties": { "dataFileId": { "title": "Following methods are just getters for test", "description": "ID of a prepared upload file to load from. Mutually exclusive with `source`.", "type": "integer", "nullable": true }, "destination": { "description": "Name of the destination table inside the workspace.", "type": "string" }, "source": { "description": "Name of the source Storage table to load from. Mutually exclusive with `dataFileId`.", "type": "string", "nullable": true }, "sourceBranchId": { "description": "ID of the dev branch the source table belongs to, if not the current branch.", "type": "integer", "nullable": true }, "description": { "description": "Description of the workspace table; overrides the Storage description. Empty or null inherits it. Ignored for VIEW loads.", "type": "string", "nullable": true, "maxLength": 65535 }, "columnDescriptions": { "description": "Source column name => description of the workspace column; overrides the Storage description. Empty or null inherits it. Ignored for VIEW loads.", "type": "object", "additionalProperties": { "type": "string", "nullable": true, "maxLength": 65535 } }, "rows": { "description": "Limit the number of loaded rows.", "type": "integer", "nullable": true }, "seconds": { "description": "Load only rows changed within the last N seconds.", "type": "integer", "nullable": true }, "changedSince": { "description": "Load only rows changed since this date/time.", "type": "string", "format": "date-time", "nullable": true }, "changedUntil": { "description": "Load only rows changed until this date/time.", "type": "string", "format": "date-time", "nullable": true }, "primaryKey": { "description": "Explicit primary key definition for the loaded table.", "properties": { "authority": { "description": "`manual` to use `columns` below, `storage` to use the source table's primary key.", "type": "string", "enum": [ "manual", "storage" ] }, "columns": { "description": "Primary key column names, required when authority is `manual`.", "type": "array", "items": { "type": "string" } } }, "type": "object", "nullable": true }, "datatypes": { "description": "Legacy per-column datatype overrides, one entry per column. Each item is either a plain type name string, or an object with detailed column settings (the object form carries its own `column` field).", "type": "array", "items": { "oneOf": [ { "type": "string" }, { "properties": { "column": { "type": "string" }, "type": { "type": "string" }, "length": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "nullable": { "type": "boolean" }, "convertEmptyValuesToNull": { "type": "boolean" }, "compression": { "description": "Legacy Redshift compression encoding, kept for backward compatibility.", "type": "string", "enum": [ "RAW", "BYTEDICT", "DELTA", "DELTA32K", "LZO", "MOSTLY8", "MOSTLY16", "MOSTLY32", "RUNLENGTH", "TEXT255", "TEXT32K", "ZSTD" ] } }, "type": "object" } ] }, "nullable": true }, "columns": { "description": "Per-column load settings. Each item is either a legacy column name string, or an object; `source` is required on the object form.", "type": "array", "items": { "oneOf": [ { "type": "string" }, { "required": [ "source" ], "properties": { "source": { "type": "string" }, "destination": { "type": "string" }, "type": { "type": "string" }, "length": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "nullable": { "type": "boolean" }, "convertEmptyValuesToNull": { "type": "boolean" }, "compression": { "description": "Legacy Redshift compression encoding, kept for backward compatibility.", "type": "string", "enum": [ "RAW", "BYTEDICT", "DELTA", "DELTA32K", "LZO", "MOSTLY8", "MOSTLY16", "MOSTLY32", "RUNLENGTH", "TEXT255", "TEXT32K", "ZSTD" ] } }, "type": "object" } ] }, "nullable": true }, "whereColumn": { "description": "Name of the column to filter rows by. Must be set together with `whereValues`.", "type": "string", "nullable": true }, "whereValues": { "description": "Values to filter `whereColumn` by. Must be set together with `whereColumn`.", "type": "array", "items": { "type": "string" }, "nullable": true }, "whereOperator": { "description": "Operator used to compare `whereColumn` against `whereValues`.", "type": "string", "nullable": true, "enum": [ "eq", "ne" ] }, "whereFilters": { "description": "Row filters, an alternative to `whereColumn`/`whereValues`/`whereOperator` supporting multiple columns and richer operators.", "type": "array", "items": { "required": [ "column", "values" ], "properties": { "column": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } }, "operator": { "description": "Defaults to `eq`. `eq`/`ne` support multiple values (IN/NOT IN); `lt`/`gt`/`le`/`ge` support a single value only.", "type": "string", "enum": [ "eq", "ne", "lt", "gt", "le", "ge" ] }, "dataType": { "description": "Data type used to interpret `values` (e.g. for numeric comparisons).", "type": "string" }, "type": { "type": "string", "enum": [ "SCALAR", "TIME_STRING" ] } }, "type": "object" }, "nullable": true }, "incremental": { "description": "Whether to load incrementally (append/update) instead of a full overwrite.", "type": "boolean", "nullable": true }, "overwrite": { "description": "Whether to drop and recreate the destination table before loading.", "type": "boolean", "nullable": true }, "useView": { "description": "Load the source table as a view instead of copying data.", "type": "boolean", "nullable": true }, "loadType": { "description": "Explicitly selects the load type. Omit or use AUTO to let the server pick.", "type": "string", "nullable": true, "enum": [ "COPY", "CLONE", "VIEW", "AUTO" ] }, "dropTimestampColumn": { "description": "Whether to omit the internal `_timestamp` column from the loaded table.", "type": "boolean", "nullable": true } }, "type": "object" }, "LoadRequest": { "description": "Request body of POST /workspaces/{id}/load.", "required": [ "input" ], "properties": { "input": { "description": "Tables to load into the workspace.", "type": "array", "items": { "$ref": "#/components/schemas/LoadRequestInputTable" } }, "preserve": { "description": "Whether to keep tables already present in the workspace that are not part of this load.", "type": "boolean", "default": false } }, "type": "object" }, "WorkspacePasswordResetResponse": { "description": "Exactly one key is present depending on the workspace type: `password` (a table workspace other than BigQuery), `credentials` (BigQuery) or `connectionString` (file workspace).", "properties": { "password": { "description": "New password of the workspace user. Present only for a table workspace other than BigQuery.", "type": "string" }, "connectionString": { "description": "New SAS connection string with 24h expiration. Present only for a file workspace.", "type": "string" }, "credentials": { "description": "Google service account key with the new private key. Present only for a BigQuery workspace.", "properties": { "type": { "type": "string", "example": "service_account" }, "project_id": { "type": "string" }, "private_key_id": { "type": "string" }, "private_key": { "type": "string" }, "client_email": { "type": "string" }, "client_id": { "type": "string" }, "auth_uri": { "type": "string" }, "token_uri": { "type": "string" }, "auth_provider_x509_cert_url": { "type": "string" }, "client_x509_cert_url": { "type": "string" } }, "type": "object" } }, "type": "object" }, "WorkspaceSaml2LoginResponse": { "required": [ "acsUrl", "samlResponse", "relayState", "expiresAt" ], "properties": { "acsUrl": { "description": "Snowflake Assertion Consumer Service URL the SAML response must be POSTed to.", "type": "string", "format": "uri" }, "samlResponse": { "description": "Base64-encoded signed SAML 2.0 response.", "type": "string" }, "relayState": { "description": "Relay state to send along with the SAML response.", "type": "string" }, "expiresAt": { "description": "Expiration of the SAML assertion.", "type": "string", "format": "date-time" } }, "type": "object" }, "WorkspaceDetailResponseWithSecret": { "required": [ "id", "type", "name", "component", "configurationId", "configurationVersion", "created", "connection", "backendSize", "statementTimeoutSeconds", "creatorToken", "actor", "readOnlyStorageAccess", "platformUsageType", "state", "lastActivityAt", "warnAt", "deactivateAt", "deleteAt" ], "properties": { "id": { "description": "ID of the workspace.", "type": "integer" }, "type": { "description": "Type of the workspace.", "type": "string", "enum": [ "file", "table" ] }, "name": { "description": "Name of the workspace (schema name for table type).", "type": "string", "nullable": true }, "component": { "description": "ID of the component that created the workspace.", "type": "string", "nullable": true }, "configurationId": { "description": "ID of the configuration that created the workspace.", "type": "string", "nullable": true }, "configurationVersion": { "description": "Pinned configuration version.", "type": "integer", "nullable": true }, "created": { "description": "Date and time of workspace creation, ISO 8601 with a `+hhmm` offset.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100" }, "connection": { "description": "Connection details for the workspace.", "type": "object", "oneOf": [ { "required": [ "backend", "region", "host", "database", "schema", "warehouse", "loginType", "ssoLoginAvailable" ], "properties": { "backend": { "description": "Workspace backend type.", "type": "string", "enum": [ "snowflake", "synapse", "exasol", "teradata", "bigquery", "postgres", "ducklake" ] }, "region": { "description": "Region of the workspace backend.", "type": "string" }, "host": { "description": "Hostname of the workspace backend.", "type": "string" }, "database": { "description": "Database name (project name for Snowflake).", "type": "string", "nullable": true }, "schema": { "description": "Schema name.", "type": "string", "nullable": true }, "warehouse": { "description": "Warehouse name (for Snowflake).", "type": "string", "nullable": true }, "user": { "description": "Username for connecting to the workspace. Empty when loginType is \"none\" or \"governed\". Absent for a BigQuery workspace, whose key is in `credentials`.", "type": "string" }, "loginType": { "description": "Login type used for the connection. Value \"none\" means the workspace has no direct credentials and is intended for QueryService. Value \"governed\" means the same, and in addition only QueryService can obtain credentials for it. Create direct connection credentials later using the workspace credentials endpoint.", "type": "string", "enum": [ "default", "snowflake-legacy-service", "snowflake-person-sso", "snowflake-person-keypair", "snowflake-service-keypair", "none", "governed" ] }, "ssoLoginAvailable": { "description": "Indicates if SSO login is available.", "type": "boolean" }, "account": { "description": "Snowflake account locator. Present only for Snowflake workspaces.", "type": "string" }, "role": { "description": "Snowflake role of the workspace user. Present only for Snowflake workspaces.", "type": "string", "nullable": true }, "password": { "description": "Password of the workspace user. Present only for a credential other than BigQuery that has a password and no key-pair certificate.", "type": "string" }, "privateKey": { "description": "Private key for workspace user. Present only for a Snowflake credential with a key-pair certificate.", "type": "string" }, "credentials": { "description": "Present only for a Snowflake credential with a key-pair certificate (`id` only), or a BigQuery credential (`id` plus the Google service account key).", "required": [ "id" ], "properties": { "id": { "description": "ID of the storage credentials.", "type": "integer" }, "type": { "description": "Present only for BigQuery.", "type": "string", "example": "service_account" }, "project_id": { "description": "Present only for BigQuery.", "type": "string" }, "private_key_id": { "description": "Present only for BigQuery.", "type": "string" }, "private_key": { "description": "Private key for workspace user. Present only for BigQuery.", "type": "string" }, "client_email": { "description": "Present only for BigQuery.", "type": "string" }, "client_id": { "description": "Present only for BigQuery.", "type": "string" }, "auth_uri": { "description": "Present only for BigQuery.", "type": "string" }, "token_uri": { "description": "Present only for BigQuery.", "type": "string" }, "auth_provider_x509_cert_url": { "description": "Present only for BigQuery.", "type": "string" }, "client_x509_cert_url": { "description": "Present only for BigQuery.", "type": "string" } }, "type": "object" } } }, { "required": [ "backend", "container", "region" ], "properties": { "backend": { "description": "File storage backend type (e.g., azure, aws).", "type": "string" }, "container": { "description": "Container name for file storage.", "type": "string", "nullable": true }, "region": { "description": "Region of the file storage.", "type": "string" } } } ] }, "backendSize": { "description": "Size of the backend (e.g., for Snowflake).", "type": "string", "nullable": true }, "statementTimeoutSeconds": { "description": "Statement timeout in seconds.", "type": "integer" }, "creatorToken": { "required": [ "id", "description" ], "properties": { "id": { "description": "ID of the token that created the workspace; 0 when the creator is not backed by a token.", "type": "integer" }, "description": { "description": "Description of the token.", "type": "string", "nullable": true } }, "type": "object" }, "actor": { "description": "Who created the workspace. Null only for a workspace that records no creator.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ActorResponse" } ] }, "readOnlyStorageAccess": { "description": "Indicates if read-only storage access is enabled.", "type": "boolean" }, "platformUsageType": { "description": "Platform usage type.", "type": "string", "nullable": true, "enum": [ "service", "user", "reader" ] }, "state": { "description": "Lifecycle state of the workspace. A deactivated workspace is kept listed so its owner can delete it, but its backend identity is disabled and cannot be connected to; contact support to reactivate it.", "type": "string", "enum": [ "active", "deactivated" ] }, "lastActivityAt": { "description": "Last observed workspace use (backend login or Storage job), ISO 8601 with a `+hhmm` offset. May be a seeded floor for an unused workspace; null when unknown.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "warnAt": { "description": "Projected date retention would warn this workspace, ISO 8601 with a `+hhmm` offset. It can move when the workspace is used; null when retention does not apply or activity has not been synced recently.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "deactivateAt": { "description": "When retention will deactivate this unused workspace, ISO 8601 with a `+hhmm` offset. Null unless the owner has been warned. Connecting to the workspace cancels it. Can lie in the past while retention only notifies.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true }, "deleteAt": { "description": "When retention will delete this deactivated workspace, ISO 8601 with a `+hhmm` offset. Null unless the workspace is deactivated. Support can reactivate it until then.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+-]\\d{4}$", "example": "2017-02-13T12:01:05+0100", "nullable": true } }, "type": "object" }, "ExecuteQueryResponse": { "required": [ "status" ], "properties": { "status": { "description": "Response status. Possible values: ok or error.", "type": "string" }, "message": { "description": "Error or statement message. Present unless a `SELECT`/`WITH` query ran on the legacy Snowflake path.", "type": "string", "nullable": true, "default": null }, "data": { "description": "Result set. Present only for queries that return one.", "required": [ "columns", "rows" ], "properties": { "columns": { "type": "array", "items": { "type": "string" } }, "rows": { "description": "Rows keyed by column name. A value is `null` for SQL `NULL`; a row with no fields is an empty array `[]`.", "type": "array", "items": { "oneOf": [ { "type": "object", "additionalProperties": { "type": "string", "nullable": true } }, { "type": "array", "items": {}, "maxItems": 0 } ] } } }, "type": "object", "nullable": true, "default": null } }, "type": "object" } }, "securitySchemes": { "StorageKey": { "type": "apiKey", "name": "X-StorageApi-Token", "in": "header" }, "ManageKey": { "type": "apiKey", "name": "X-KBC-ManageApiToken", "in": "header" }, "BearerAuth": { "type": "http", "bearerFormat": "Access Token (kbc_at_...)", "scheme": "bearer" } } }, "security": [ { "StorageKey": [] }, { "ManageKey": [] }, { "BearerAuth": [] } ], "tags": [ { "name": "Tokens and Permissions", "description": "When joining a project, each project administrator is assigned a [*master* token](https://help.keboola.com/storage/tokens/),\nwhich enables them to create other tokens with limited privileges for buckets and components.\n\nSelected tokens endpoints can be used with `default` for the `branch_id` parameter and emulate the call without a development branch.\nIt means that endpoint `GET /v2/storage/tokens/verify` is the same as `GET /v2/storage/branch/default/tokens/verify`.\n" }, { "name": "Miscellaneous", "description": "API index and the list of registered components." }, { "name": "Buckets", "description": "[Buckets](https://help.keboola.com/storage/buckets/) are containers for one or more data tables.\nAccess to buckets can be limited by access tokens. Each bucket has a *backend* in which all tables are created:\n- Snowflake (default)\n- BigQuery\n\nBucket sharing endpoints [enable sharing](https://help.keboola.com/storage/buckets/sharing/) of a bucket within the\norganization, to selected projects or to selected users; they are available only to organization administrators.\n" }, { "name": "Tables", "description": "Create, load, export, preview and manage tables, their columns, primary keys, rows and data profiles." }, { "name": "Table Aliases", "description": "[Aliases](https://help.keboola.com/storage/tables/) behave like database Views. Alias tables are read-only.\nAliases cannot be chained and can be applied only between buckets with the same backend.\n\nRows present in an alias table can be filtered by a simple condition similar to table export filtering.\nThe filter parameter `aliasFilter` must be set during an alias table creation or later to enable filtering:\n\n* **column** - Filtered by column name\n* **operator** - Filter operator: `eq`, `ne`\n* **values[]** - One or more filter values\n\n#### Alias table columns\nBy default, the alias columns are automatically synced with the source table. You can disable this behaviour\nby setting up `aliasColumnsAutosync` to `false` and setting up list of columns by `aliasColumns` parameter.\nLater you can modify the alias columns by the table columns methods.\nWhen turning `aliasColumnsAutoSync` back on, the columns will be immediately synced with the source table.\n" }, { "name": "Table Snapshotting", "description": "Table data and metadata (column settings) can be persisted by creating a snapshot. When a snapshot is created you can use it to restore the table back to the snapshotted state. During the restoration process, the data can be applied to the original table or they can be restored into a new table.\n" }, { "name": "Workspaces", "description": "Workspaces provide a playground for your data. You can load data from your storage, explore or modify it\nand then, optionally, load it back to storage tables. A workspace is represented by access credentials to a storage\nbackend with permissions to write to the workspace specific database schema.\n\nAll workspaces endpoints can be used with `default` for the `branch_id` parameter and emulate the call without a development branch.\nIt means that endpoint `GET /v2/storage/workspaces` is the same as `GET /v2/storage/branch/default/workspaces`.\n" }, { "name": "Events", "description": "Virtually every interaction of the client (an API call) creates an Event. Apart from that, external events may\nalso be added via an API. Events are stored for a limited time.\nYou can access all events created on an account.\n\nId field is deprecated and will be removed in the future. Please use Uuid instead.\n\nEvents can be filtered by various filters:\n- `sinceId`, `maxId` - Events newer or older than the passed id or Uuid (id is deprecated and will be removed in the future)\n- `component` - Component name\n- `configurationId` - Configuration id\n- `runId` - Run id\n- `q` - Advanced search using a query string. [Query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax)\n\nThe events pagination uses two parameters:\n- `limit` - Number of returned events. The default value: 100\n- `offset` - Pagination offset\n\nSelected events endpoints can be used with `default` for the `branch_id` parameter and emulate the call without a development branch.\nIt means that endpoint `GET /v2/storage/events` is the same as `GET /v2/storage/branch/default/events`.\n" }, { "name": "Metadata", "description": "You can associate custom metadata with buckets, tables or columns. Metadata are timestamped key-value pairs separated by the provider, where the provider is the originating component. Metadata allows you to assign custom information to your resources. Bucket metadata methods are described below. Work with table and column metadata in the same manner; simply use a table or column instead of a bucket in the url.\n" }, { "name": "Jobs", "description": "Jobs are objects that manage asynchronous tasks, these are all potentially long-running actions such as\nloading table data, snapshotting, table structure modifications. Jobs are created by actions on target\nresources, e.g., an asynchronous import request creates\na table import job. For each new job, the Id and URL of the job is returned.\n\nWhen working with jobs, follow these steps:\n1. **Start the job** - Job resource is created and a URL for polling is returned.\n2. **Poll job status** - Poll the job URL in a loop until the job `status` is set to `success` or `error`.\n3. **Check the results** - When the job is finished, the `results` field will contain the actual result of the original request.\n\nAvailable Statuses:\n- `waiting` - The job is in the queue and is waiting for execution.\n- `processing` - The job is being processed by a worker.\n- `success` - The job is done with a success.\n- `error` - The job is done with an error.\n" }, { "name": "Files", "description": "File Storage is used for storing arbitrary files. This is used for data imported into tables and data exported\nfrom tables. Additionally, the File storage can be used for data backup and exchange between project participants.\n\nFile Storage is heavily used for data exchange between Storage API and other components, import backups, etc.\nThis kind of data is not kept forever. By default, all files are stored for **15 days**. They can be stored permanently by\nusing the `isPermanent` parameter. Files can also be tagged to categorize file uploads. When the `X-KBC-RunId` header is\nprovided, it is stored as the file `runId`.\n\nInternally, all files are stored encrypted and are private. When you access the file through the API,\na URL with one hour expiration is generated.\n\nLarge files may be split into slices (chunks). A sliced file must have the `isSliced` parameter set to `true`. In that case\nthe provided key (blob) points to a **manifest file**. The manifest file contains the actual list of uploaded chunks. When uploading a sliced\nfile, you have to use the provided key as a prefix for chunks and generate the manifest file with the list of uploaded chunks.\nWhen a CSV file is imported into Storage Tables, there is no difference between a normal and a sliced file.\n\n**Example:**\n\nAssume that the upload method returns the following S3 key `exp-180/11/files/2014/02/25/11085.import`.\nThen you can upload e.g. these files:\n- exp-180/11/files/2014/02/25/11085.import001\n- exp-180/11/files/2014/02/25/11085.import002\n- exp-180/11/files/2014/02/25/11085.import003\n\nThen create the following manifest file:\n```\n{\n \"entries\": [\n {\"url\":\"s3://kbc-sapi-files-devel/exp-180/11/files/2014/02/25/11085.import001\"},\n {\"url\":\"s3://kbc-sapi-files-devel/exp-180/11/files/2014/02/25/11085.import002\"},\n {\"url\":\"s3://kbc-sapi-files-devel/exp-180/11/files/2014/02/25/11085.import003\"}\n ]\n}\n```\n\nAnd then, upload that manifest file to the key `exp-180/11/files/2014/02/25/11085.importmanifest`. See our\n[Developers documentation](https://developers.keboola.com/integrate/storage/api/import-export/#working-with-sliced-files)\nfor a more detailed guide.\n" }, { "name": "Tickets", "description": "Tickets are unique sequential 64 bit IDs. Tickets are used to generate unique run identifiers for all components using Keboola Connection.\n" }, { "name": "Components and Configurations", "description": "Component Configuration represents specific settings of a registered Component\nin a project. See the [Developers Documentation](https://developers.keboola.com/integrate/storage/api/configurations/)\nfor examples and use cases.\nThis is a utility resource available only for master tokens and tokens with the `canManageBuckets` permission.\nConfigurations may include *Configuration Rows* if they are composed of multiple objects. Configuration rows are\nused in case parts of the configuration are supposed to be updated independently.\nConfigurations are automatically versioned. Configuration Rows are versioned separately, but they are also recorded as\nchanges of the configuration. The `configuration` and\n`rows.configuration` fields can contain arbitrary objects. The content and interpretation of those fields is fully\ndefined by the component.\n\nAll components and configurations endpoints can be used with `default` for the `branch_id` parameter and emulate the call without a development branch.\nIt means that endpoint `GET /v2/storage/components` is the same as `GET /v2/storage/branch/default/components`.\n" }, { "name": "Scheduled tasks", "description": "Scheduled tasks of the project." }, { "name": "Search", "description": "Search tables and other objects by metadata, and global search across the project." }, { "name": "Stats", "description": "Project storage statistics." }, { "name": "Triggers", "description": "Triggers listen on a set of tables and run a component configuration when the tables change. The token has to be [*master*](https://help.keboola.com/storage/tokens/); if it isn't, it has to have the `canManageBuckets` permission or `componentAccess` permission for the triggered component.\n" }, { "name": "Webalize", "description": "Webalize strings for use as `displayName` of tables and buckets or as column names." }, { "name": "Validate", "description": "Validate strings for use as column names." }, { "name": "Development Branches", "description": "**EXPERIMENTAL**\n\nDevelopment branches allow you to prepare changes to configuration and tables in isolation. When ready, you can replace the production with the development branch.\n\nYou can use development branch in selected API calls by changing url.\nFor example, you want to list configurations:\n- `GET /v2/storage/components/ex-foo/configs` - in default branch (common usage)\n- `GET /v2/storage/branch/default/components/ex-foo/configs` - in default branch (with `default` as branch prefix) - same result as above\n- `GET /v2/storage/branch/123/components/ex-foo/configs` - in development branch (with `ID` as branch prefix)\n" } ] }